Authentication

Before you start

You need an API client for your organization and its admin login:

Don't have a client yet? Create one in the business portal, or contact Waffy. Each environment needs its own client and credentials. The Postman collection comes with an environment file already filled in for your client.

The examples below use $ID_BASE_URL for the host of Waffy ID in your environment.

Which token for what

A client admin token carries the CLIENT_ADMIN role, which neither the org token nor a customer can have. An endpoint that needs it answers 403 to any other token.

Step 1: Get an org token

curl -s -X POST "$ID_BASE_URL/realms/waffy/protocol/openid-connect/token" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=client_credentials" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"

{
  "access_token": "eyJhbGc...",
  "expires_in": 600,
  "scope": "EXTERNAL"
}

Send it as Authorization: Bearer <access_token>. Cache it on your server and renew it shortly before expires_in runs out. Do not request a new token for every call.

Step 2: Get a client admin token

Needed for the business calls (contracts, settlement, balance). It is a normal API call, with no browser step, so it works from a backend:

curl -s -X POST "$ID_BASE_URL/realms/waffy/protocol/openid-connect/token" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=password" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "username=$ORG_ADMIN_USERNAME" \
  --data-urlencode "password=$ORG_ADMIN_PASSWORD"

• client_id must belong to your own organization. A client from another organization fails with 400 invalid_grant.
• A contract you create is attributed to the client you signed in with, so use the same client for the checkout start URL in that session.

Step 3: Get a payment ticket (at payment time)

When a customer who has given consent is ready to pay, your backend exchanges your client for a short-lived ticket for that customer and that payment:

curl -s -X POST "$ID_BASE_URL/realms/waffy/protocol/openid-connect/token" \
  -H "Accept: application/json" \
  --data-urlencode "grant_type=urn:waffy:params:oauth:grant-type:customer-token-exchange" \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET" \
  --data-urlencode "login_hint=$CUSTOMER_PHONE" \
  --data-urlencode "scope=payment:$PAYMENT_REF"

{ "ticket": "a1b2c3...", "expiresIn": 300 }

• PAYMENT_REF is the contract's shortId, the same value that is in the checkout URL path (.../external/6VzpzZlR?... means 6VzpzZlR). It is not an internal id or an order reference of your own.
• You then redirect the customer's browser to the checkout URL with &ticket=... appended. Waffy's checkout exchanges it for a real token itself, so your integration ends at the redirect.
• The ticket is valid for 5 minutes. Request it right before the redirect.

Which token each call needs

Error responses