H2H: Payouts to Saved Payee Cards

Bind a payee's card once and receive a paymentInstrumentToken starting with pi_. Use this token in disbursements instead of sending the card number every time. Binding does not create a payout.

To save a customer's card for payments, see Card Tokenization via API. Customer cards and payee cards are kept separately: see Token scope.

Before you start

Endpoint paths below are relative to the processing base URL for your environment. See Access URLs and API Authentication.

Supported methods

Other payout methods, including Napas, do not support binding. The examples use BankCardKZ and KZT.

Identifiers and token scope

A payee card token belongs to one settlement account, one merchantPayeeReference and one payment method. A token bound for payee payee-12345 in account A cannot be used for another payee, another account or another payment method. Sandbox and production tokens are separate.

Customer cards saved during payments are not used for payouts, and a payee card token is not accepted in a payment.

flowchart LR
  bind["Bind the payee card"] --> token["pi_ token"]
  token -->|"Payout by token, any number of times"| token
  token -->|"Delete the binding"| deleted["Token unavailable"]
  deleted -->|"Bind the card again"| replacement["New pi_ token"]

Bind a payee card

API reference: Bind a payout card.

{
  "paymentMethodName": "BankCardKZ",
  "merchantPayeeReference": "payee-12345",
  "incomingDetails": {
    "number": "4111111111111111"
  }
}

{
  "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAF",
  "type": "CARD",
  "status": "ACTIVE",
  "paymentMethodId": "PM204264682781298692",
  "paymentMethodName": "BankCardKZ",
  "merchantPayeeReference": "payee-12345",
  "createdAt": "2026-10-20T10:15:30Z",
  "storedDetails": {
    "brand": "VISA",
    "maskedNumber": "411111******1111"
  }
}

Binding the same card to the same payee with the same payment method again returns the same token. The same card bound to a different payee gets a different token.

Pay out by token

Pass the token in payeePaymentInstrument and the payee reference in payee instead of the card details. Both ways of creating a disbursement accept a token:

{
  "clientReferenceId": "payout-20261020-0001",
  "useCheckoutForm": false,
  "disbursements": [
    {
      "payee": {
        "merchantPayeeReference": "payee-12345"
      },
      "payeePaymentInstrument": {
        "paymentMethodName": "BankCardKZ",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAF"
      },
      "submittedAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "authAmount": {
        "currency": "KZT"
      },
      "clientReferenceId": "payout-20261020-0001-1",
      "webhookUrl": "https://merchant.example.com/webhooks/disbursements"
    }
  ]
}

{
  "intentId": "241485468702138350",
  "payments": [],
  "disbursements": [
    {
      "id": "241485668832161722",
      "submittedAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "authAmount": {
        "value": 12300.00,
        "currency": "KZT"
      },
      "payeePaymentInstrument": {
        "id": "PI352596778994327283",
        "storedDetails": {
          "maskedNumber": "411111******1111",
          "lastFour": "1111",
          "bin": "411111"
        }
      },
      "createdAt": "2026-10-20T10:20:00Z",
      "status": "ACCEPTED",
      "clientReferenceTransactionId": "payout-20261020-0001-1"
    }
  ],
  "paymentCreationErrors": [],
  "disbursementCreationErrors": [],
  "clientReferenceIntentId": "payout-20261020-0001",
  "intentStatus": "CREATED"
}

The token is checked before anything is created. If any disbursement in the request has an invalid token, the whole request is rejected with an HTTP error, and no Intent or disbursement is created.

A token has no expiry date and no limit on the number of payouts. Your payout limits and duplicate-payout checks apply as for payouts with card details. If the payee's card is reissued with the same number, the token keeps working; a card with a new number must be bound again.

The disbursement possibility check does not use the token: to check a payout, send the card details in that request, as before.

Delete a payee card

After deletion:

• New payouts by this token are rejected with HTTP 404 and INSTRUMENT_NOT_FOUND.
• Binding the same card again creates a new token.
• Payouts already created are not affected: deletion does not cancel a payout in progress.

Errors

For a payout, 404 is returned in the same form in every case listed above, so the response does not reveal whether a token exists outside your scope. Check the token, the payee reference and the payment method.

{
  "errorCode": "INSTRUMENT_NOT_FOUND",
  "failureMessage": "Saved payment instrument not found"
}

Errors that occur after the disbursement is created, such as a decline by the bank, are reported as for any payout: see Creation Errors and Processing Errors.

Test the integration

Use a sandbox settlement account with H2H tokenization enabled and a payout route for the payment method. Test card numbers and status triggers are the same as for payouts with card details: see the test data in KZ: Bank Card - Disbursements and RU: Bank Card - Disbursements.

Cover the complete journey: bind a card, bind it again and check that the token is the same, pay out by the token through both endpoints, make several payouts by one token, try the token with another payee reference and receive 404, delete the binding, and check that a payout by the deleted token is rejected.