---
updatedAt: 2026-06-22T07:00:57.000Z
agentTools:
  projectIndex: https://docs.shopback.com/llms.txt
---

# 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`.

# OpenAPI definition

```json
{
  "openapi": "3.0.1",
  "info": {
    "title": "Online Payments API",
    "version": "2.0"
  },
  "servers": [
    {
      "url": "https://integrations-sandbox.shopback.com/demo/merchant",
      "description": "staging environment"
    }
  ],
  "x-readme": {
    "metrics-enabled": false
  },
  "tags": [
    {
      "name": "Account Linking"
    }
  ],
  "x-tagGroups": [
    {
      "name": "Orders",
      "tags": [
        "Orders"
      ]
    },
    {
      "name": "Authentication",
      "tags": [
        "Authentication"
      ]
    },
    {
      "name": "Platform",
      "tags": [
        "Platform"
      ]
    },
    {
      "name": "Tokenized Payment",
      "tags": [
        "Account Linking",
        "Pre-Auth"
      ]
    }
  ],
  "paths": {
    "/tokenized-payment/v1/link-sessions/link": {
      "post": {
        "operationId": "initiate-link-session",
        "summary": "Initiate a tokenized payment link session",
        "description": "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`.",
        "tags": [
          "Account Linking"
        ],
        "security": [
          {
            "bearer": []
          }
        ],
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InitiateLinkSessionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Link session created; merchant should redirect user to `redirectUrl`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InitiateLinkSessionResponse"
                }
              }
            }
          },
          "400": {
            "description": "Invalid request body, malformed `callbackUrl`, `callbackUrl` not on the channel allowlist, or `userHint` missing or contains no sub-fields."
          },
          "401": {
            "description": "Missing or invalid merchant JWT."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Merchant JWT obtained from POST /merchant-gateway/auth/login."
      }
    },
    "schemas": {
      "UserHintDto": {
        "type": "object",
        "properties": {
          "phone": {
            "type": "string",
            "description": "Pre-redacted phone number as registered with the merchant (e.g. \"+6591xxxx67\"). Displayed as-is on the consent page. The merchant is responsible for redacting before sending.",
            "example": "+6591xxxx67",
            "maxLength": 30
          },
          "email": {
            "type": "string",
            "description": "Pre-redacted email address as registered with the merchant (e.g. \"r***@example.com\"). Displayed as-is on the consent page. The merchant is responsible for redacting before sending.",
            "example": "r***@example.com",
            "maxLength": 254
          }
        }
      },
      "InitiateLinkSessionRequest": {
        "required": [
          "callbackUrl",
          "state",
          "merchantUserId",
          "userHint"
        ],
        "type": "object",
        "properties": {
          "callbackUrl": {
            "type": "string",
            "description": "Merchant callback URL; must be on the per-channel allowlist.",
            "example": "https://merchant-name.sg/link/callback"
          },
          "state": {
            "type": "string",
            "description": "Merchant-supplied CSRF nonce; stored verbatim and echoed back unchanged in the callback redirect.",
            "example": "a8f3c2e1d7b4509f"
          },
          "merchantUserId": {
            "type": "string",
            "description": "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": "merchant_user_42"
          },
          "userHint": {
            "description": "Identity hints from the merchant displayed on the ShopBack consent page so the user can verify the linking request was intended for them. At least one sub-field must be present. ShopBack does not validate these values — they are display-only.",
            "allOf": [
              {
                "$ref": "#/components/schemas/UserHintDto"
              }
            ]
          }
        }
      },
      "InitiateLinkSessionResponse": {
        "required": [
          "linkToken",
          "redirectUrl",
          "expiresAt",
          "appToken"
        ],
        "type": "object",
        "properties": {
          "linkToken": {
            "type": "string",
            "description": "Opaque UUID identifying the linking session. Not embedded in `redirectUrl`.",
            "example": "550e8400-e29b-41d4-a716-446655440000"
          },
          "redirectUrl": {
            "type": "string",
            "description": "Base ShopBack URL. Does NOT include any token; the merchant appends token(s) themselves before opening the in-app browser. Valid until `expiresAt`.",
            "example": "https://pay.shopback.com/link"
          },
          "expiresAt": {
            "type": "string",
            "description": "Session TTL from creation. After this, the session is EXPIRED.",
            "example": "2026-04-30T10:20:00.000Z"
          },
          "appToken": {
            "type": "string",
            "description": "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": "<HS256-signed-jwt>"
          }
        }
      }
    }
  }
}
```