What are Payments with Provider tokens?

Provider-issued payment tokens are secure, non-sensitive identifiers generated by a Payment Service Provider to represent a customer's payment credentials, such as a payment card or bank account. These tokens enable Merchants to process authorised payments without storing or handling sensitive payment data.

This integration model allows Merchants to process subsequent payments using Provider-issued tokens that are securely stored in the processing platform's vault.

• During the initial customer-authorised payment, the Payment Provider generates a token representing the Customer's Payment method. The platform securely stores this Provider-issued token in its vault and maps it to a platform-generated vault token (payment_account_token).
• For all subsequent payments, the Merchant submits only the vault token. The platform uses this token to retrieve the corresponding Provider-issued token from the vault and process the payment with the Payment Provider. At no point are the original Provider token or the customer's payment credentials exposed through the API.

How it works?

This integration model is designed for Merchants who manage their own subscription lifecycle and billing logic. After the Customer completes the initial payment and authorises future charges, you can initiate recurring (off-session) payments without requiring any further Customer interaction.

Recurring payments are processed using the platform-generated vault token (payment_account_token), which references the customer's payment credentials securely stored in the platform's vault. You never need to store, transmit, or access cardholder data or the original Provider-issued token.

This approach enables secure Merchant-initiated transactions (MIT) without redirecting the Customer to a Hosted Payment Page (HPP) or requiring additional 3D Secure (3DS) authentication, unless requested by the Payment Provider or required by applicable regulations.

Payment flow stages

Stage 1: Customer-initiated transaction (CIT)

The initial payment is completed by the Customer with 3D Secure authentication. During this process, the Provider-issued payment token is securely stored in the vault for future use.

This stage always includes two API requests:

• create
• process

Stage 2: Merchant-initiated transaction (MIT)

You initiate all subsequent Recurring payments using the previously stored vault token. Since the Customer is not involved in these transactions, no additional authentication or payment details are required.

API

Base URL: https://{host}/api/private/v1/processing

Authentication: Bearer token (Organisation API key)

Stage 1: POST /payment-requests (CIT)

Step 1: Create

Step 2: Process

Response attributes

Response

{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "type": "payment-requests",
    "attributes": {
      "status": "processed",
      "resolution": "ok",
      "customer_info": {
        "id": "cus_xxxxxxxxxxxxxxxx",
        "reference_id": "merchant-customer-001",
        "accounts": [
          {
            "token": null,
            "type": "card",
            "position": 1,
            "details": {
              "mask": "411111******1111",
              "expiry_month": "12",
              "expiry_year": "2028"
            }
          }
        ]
      }
    }
  }
}

Stage 2: POST /payment-requests (MIT)

Step 1: Create

Step 2: Process

Response

{
  "data": {
    "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
    "type": "payment-requests",
    "attributes": {
      "status": "processed",
      "resolution": "ok",
      "amount": 1000,
      "currency": "USD"
    }
  }
}

GET /customers/id/payment-accounts

The request returns a list of client vault tokens. Used to obtain a vault token for MIT if the token in the response to the CIT process was null (private token type).

Path parameters

Response attributes

Response

{
  "data": [
    {
      "id": "sha1-hash",
      "type": "account-tokens",
      "attributes": {
        "token": null,
        "token_type": "private",
        "position": 1,
        "created_at": "2025-01-01T00:00:00+00:00",
        "expires_at": null
      }
    }
  ]
}

Error responses