Sign in

v1

latestOpenAPI 3.0.12026-07-24204977.5 KB
Account Linking

Initiate a tokenized payment link session

Creates a PENDING link session and returns a redirectUrl and appToken. The merchant opens redirectUrl in an in-app browser and passes appToken as X-ShopBack-App-Token.

post/tokenized-payment/v1/link-sessions/link

Request body

callbackUrlstring required

Merchant callback URL; must be on the per-channel allowlist.

statestring required

Merchant-supplied CSRF nonce; stored verbatim and echoed back unchanged in the callback redirect.

merchantUserIdstring required

Merchant's opaque user ID. Used to verify that tokenized payments can only be made to the same customer who initiated the link session.

Example request

{
  "callbackUrl": "https://merchant-name.sg/link/callback",
  "state": "a8f3c2e1d7b4509f",
  "merchantUserId": "merchant_user_42",
  "userHint": {
    "phone": "+6591xxxx67",
    "email": "r***@example.com"
  }
}

Response

Link session created; merchant should redirect user to redirectUrl.

linkTokenstring required

Opaque UUID identifying the linking session. Not embedded in redirectUrl.

redirectUrlstring required

Base ShopBack URL. Does NOT include any token; the merchant appends token(s) themselves before opening the in-app browser. Valid until expiresAt.

expiresAtstring required

Session TTL from creation. After this, the session is EXPIRED.

appTokenstring required

HS256-signed JWT binding this response to the link session. The payload contains { linkToken } and expires at the same time as the session. Pass this as the X-ShopBack-App-Token header when opening the in-app browser.

Example response

{
  "linkToken": "550e8400-e29b-41d4-a716-446655440000",
  "redirectUrl": "https://pay.shopback.com/link",
  "expiresAt": "2026-04-30T10:20:00.000Z",
  "appToken": "<HS256-signed-jwt>"
}