Customers & consent

Consent status

Until consent is established, calls that act for the customer fail with consent_required (or consent_rejected after a decline).

1. Register or link a customer

One call covers every case. A new phone number is registered and linked, an existing Waffy customer is just linked, and one already linked is returned as is. You never need to check first.

export CUSTOMER_PHONE=+9665XXXXXXXX

curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-partner/customers" \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"phoneNumber\":\"$CUSTOMER_PHONE\",\"firstName\":\"Sara\",\"lastName\":\"Al-Otaibi\"}"

{ "waffyUserId": 2264, "userIdentification": 39311497,
  "consent": { "status": "VERIFIED", "type": "CUSTOMER_APPROVED",
               "required": false, "autoAccept": false, "linkSent": false } }

• phoneNumber is required, in the form +9665XXXXXXXX. firstName, lastName and email are optional.
• Keep waffyUserId. You need it for bank account and address calls and for contracts.
• The other party of a contract (the provider) is registered with the exact same call. There is no separate type or role.

The consentMethod field

Do you need to ask for consent?

The registration response tells you, so you never ask a customer twice. Each field is about this customer and the client whose token you use:

1. Call the registration endpoint.
2. If consent.required is false, carry on. This is also what a second contract with the same customer sees: nothing is asked again.
3. If it is true, get consent with the SMS link (Path A) or your own OTP screen (Path B), then confirm with the same call or the lookup below.

If you sent consentMethod: "sms" and the SMS could not be accepted for sending, the customer is still registered: you get 201 with linkSent: false and required: true. Call the resend endpoint to retry.

Look up the status without registering anyone

curl -s "$ID_BASE_URL/realms/waffy/waffy-partner/customers/consent?phoneNumber=%2B9665XXXXXXXX" \
  -H "Authorization: Bearer $ORG_TOKEN"

{ "linked": true, "status": "PENDING", "type": null, "required": true }

Read-only: nothing is created and nothing is sent. A phone with no Waffy account and a phone not linked to your client both answer linked: false. Write the + as %2B in the URL. It shares the hourly limit of the resend call.

Read your client's settings

curl -s "$ID_BASE_URL/realms/waffy/waffy-partner/client" \
  -H "Authorization: Bearer $ORG_TOKEN"

{ "clientId": "wasetk_Portal_...", "autoAcceptConsent": false, "checkoutLoginMode": "ticket" }

2. Establish consent

Pick the path that fits your integration.

Path A: send or resend the consent link

consentMethod: "sms" only sends on the first call. To send again, because the customer missed it or declined and you want to ask once more, use this call. It works for PENDING and REJECTED customers. For a customer who already consented it sends nothing:

curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-partner/consent/send" \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"phoneNumber\":\"$CUSTOMER_PHONE\"}"

{ "sent": true }

sent: false is not a failure; it says why nothing was sent:

sent: true means accepted for sending, not delivered. A new link replaces the previous one only after the SMS was accepted.

The link can be used once. Opening it again, approving or declining twice, shows a "link no longer valid" page.

Path B: verify an OTP yourself

Send the code. This works even if the customer is not registered yet:

curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-partner/otp/send" \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"phoneNumber\":\"$CUSTOMER_PHONE\"}"

Collect the code in your own UI, then verify it. The call records consent. If you already registered the customer, send only the phone and the code:

curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-partner/otp/verify" \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"phoneNumber\":\"$CUSTOMER_PHONE\",\"otp\":\"123456\"}"

For a customer with no Waffy account yet, add the details and the same call registers them too. They are used only when the account is created; an existing customer's details are not changed:

curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-partner/otp/verify" \
  -H "Authorization: Bearer $ORG_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"phoneNumber\":\"$CUSTOMER_PHONE\",\"otp\":\"123456\",\"firstName\":\"Sara\",\"lastName\":\"Al-Otaibi\",\"email\":\"sara@example.com\"}"

With only the phone and the code, a phone that has no account yet still gets one, without a name or email. Use the second form for a new customer.

{ "waffyUserId": 2264, "userIdentification": 39311497 }

The response contains identifiers only, never a token. A successful verification also reverses an earlier decline. To pay, get a payment ticket as for any consented customer (see Authentication).

Testing consent without a phone

In the sandbox you can approve or decline as the customer would, from curl or Postman (the collection's Consent folder). There is no API to read a customer's consent token, because in production it only reaches them by SMS. In the sandbox, ask Waffy for the token of your test phone number.

export CONSENT_TOKEN=<from Waffy>

# View the page (always 200 text/html; check the body, not the status code)
curl -s "$ID_BASE_URL/realms/waffy/waffy-consent/$CONSENT_TOKEN"

# Approve: PENDING -> VERIFIED
curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-consent/$CONSENT_TOKEN/decision" \
  --data-urlencode "approved=true"

# Decline: PENDING -> REJECTED
curl -s -X POST "$ID_BASE_URL/realms/waffy/waffy-consent/$CONSENT_TOKEN/decision" \
  --data-urlencode "approved=false"