H2H: Card Tokenization via API

Save a customer's card and receive a paymentInstrumentToken starting with pi_. Use this token for future CIT and MIT payments and to list, retrieve or delete saved cards.

You can save a card during a purchase or authorise it without a purchase. A successful payment and a successful card save are separate results: check both before offering the saved card to the customer.

For saving cards on a hosted form, see Payment Instrument Tokenization in Checkout.

Before you start

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

Supported methods

Availability depends on the methods enabled for your account. Card saving and payment by token have separate availability.

The examples use BankCardRU and RUB.

Identifiers and token scope

A saved card belongs to a settlement account and a merchantPayerReference. A token saved for customer 12345 in account A cannot be used for another customer or account B. Use the payment method associated with that token. Sandbox and production tokens are separate.

Send the customer reference belonging to the authenticated user in your application. Your application is responsible for mapping its users to the correct references.

Saving lifecycle

This diagram shows a typical asynchronous flow. The initial response may also contain an already available result.

sequenceDiagram
    participant Customer
    participant Merchant
    participant API as Payment API
    Merchant->>API: POST Intent with savePaymentInstrument=true
    API-->>Merchant: Intent and payment IDs, savingRequested=true
    opt Cardholder verification required
        Merchant->>Customer: Open the returned verification URL
        Customer->>API: Complete verification, including 3DS if required
    end
    Note over API: Successful authorisation allows card saving
    par Saving
        API->>API: Record the card-saving result
    and Payment notification
        API-->>Merchant: Webhook, saving result may still be pending
    end
    Merchant->>API: GET Intent or payment
    API-->>Merchant: Payment status and current saving result
    Note over Merchant: Check isSaved and paymentInstrumentToken separately from payment status

Save a card during a payment

Create an Intent containing a card payment. Set savePaymentInstrument to true on the payment and pass payer.merchantPayerReference.

This example covers a standard card payment. Include any additional fields required by your account, business category or payment method.

{
  "clientReferenceId": "order-1001",
  "payments": [
    {
      "payer": {
        "merchantPayerReference": "12345"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "incomingDetails": {
          "number": "4462603043025620",
          "expiryMonth": "12",
          "expiryYear": "2028",
          "cvv": "123",
          "holderName": "TEST CUSTOMER",
          "redirectUrl": "https://merchant.example/payment/return",
          "failureUrl": "https://merchant.example/payment/failure"
        }
      },
      "submittedAmount": {
        "value": 100,
        "currency": "RUB"
      },
      "authCurrencyCode": "RUB",
      "savePaymentInstrument": true,
      "webhookUrl": "https://merchant.example/webhooks/payments"
    }
  ]
}

{
  "intentId": "204264682781298700",
  "payments": [
    {
      "id": "204264682781298701",
      "status": "ACCEPTED",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "savingRequested": true
      },
      "additionalData": {
        "details": {
          "url": "https://checkout.example/verification/session-1001"
        }
      }
    }
  ],
  "paymentCreationErrors": []
}

Open the returned additionalData.details.url and follow the BankCardRU authorisation flow. This step is required even if the customer is not asked to complete a 3DS challenge. The example URL is illustrative.

Retrieve the saving result

The platform saves the card after successful authorisation. You can read the result using GET /api/v1/intents/{intentId} or GET /api/v1/payments/{paymentId}. The result can also appear in a payment webhook.

{
  "id": "204264682781298700",
  "payments": [
    {
      "id": "204264682781298701",
      "status": "AUTHORIZED",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "savingRequested": true,
        "isSaved": true,
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
      }
    }
  ]
}

Keep the returned token with the corresponding customer and settlement account. Do not infer saving success from the payment status or from the presence of masked card details.

Receive the result by webhook

Payment webhooks can include the same saving fields. The following event excerpt illustrates a payment notification after a purchase has completed and the card has been saved:

{
  "transactionType": "PAYMENT",
  "transactionId": "204264682781298701",
  "intentId": "204264682781298700",
  "status": "CAPTURED",
  "isStoredCredential": false,
  "paymentInstrument": {
    "paymentMethodName": "BankCardRU",
    "savingRequested": true,
    "isSaved": true,
    "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
  }
}

See Webhooks for delivery and handling rules.

Save a card without a purchase

Zero amount authorisation

For BankCardRU, authorise an amount of zero with savePaymentInstrument: true. This verifies and saves the card without reserving a purchase amount.

{
  "clientReferenceId": "card-binding-1001",
  "payments": [
    {
      "payer": {
        "merchantPayerReference": "12345"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "incomingDetails": {
          "number": "4462603043025620",
          "expiryMonth": "12",
          "expiryYear": "2028",
          "cvv": "123",
          "holderName": "TEST CUSTOMER",
          "redirectUrl": "https://merchant.example/cards/return",
          "failureUrl": "https://merchant.example/cards/failure"
        }
      },
      "submittedAmount": {
        "value": 0,
        "currency": "RUB"
      },
      "authCurrencyCode": "RUB",
      "savePaymentInstrument": true,
      "webhookUrl": "https://merchant.example/webhooks/payments"
    }
  ]
}

{
  "intentId": "204264682781298730",
  "payments": [
    {
      "id": "204264682781298731",
      "status": "ACCEPTED",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "savingRequested": true
      },
      "additionalData": {
        "details": {
          "url": "https://checkout.example/verification/card-binding-1001"
        }
      }
    }
  ],
  "paymentCreationErrors": []
}

Open the returned URL and complete the authorisation flow, then retrieve the saving result using this operation's Intent or payment ID. A successful zero amount authorisation uses the normal AUTHORIZED status. Check paymentInstrument.isSaved and paymentInstrument.paymentInstrumentToken separately; authorisation success does not guarantee saving success.

Authorisation with a nonzero amount

You can also save the card using a temporary authorisation for a nonzero amount supported by your account. Use the same saving request with a nonzero amount and a new clientReferenceId.

{
  "status": "CANCELLED"
}

Success

See Cancel Authorized Amount for the cancellation endpoint and conditions.

When saving does not succeed

A payment can succeed while saving the card fails. For example, an otherwise successful payment may contain this result excerpt:

{
  "paymentInstrument": {
    "savingRequested": true,
    "isSaved": false,
    "notSavedReason": "LIMIT_REACHED"
  }
}

For H2H, the default limit is five usable saved cards per customer within a settlement account. The integration team can configure the limit from 1 to 100. It is shared across payment methods. Deleted cards and cards recognised as invalid do not consume a place in this limit.

Reusing and managing a saved card

Saving a card that is already saved for the same customer and settlement account returns the existing token. Saving the card again after deleting its token produces a new token.

After deletion, reading the original saving payment can show isSaved: false. A historical payment response is not proof that its token is still usable; retrieve the saved card to check its current state.

The token has no fixed expiry period of its own. It may stop being usable if it is deleted or the underlying card becomes unavailable. A saved card's ACTIVE status does not guarantee that a payment will be approved; validity also depends on the issuing bank and payment method.

Cards saved through Hosted Checkout can be retrieved and used through the API for the same settlement account and merchantPayerReference, with H2H tokenization enabled and a supported payment method. The same saved-card collection is available to Checkout when its saving feature is enabled. You do not need to collect the card details again solely because the integration channel changes.

Continue with Payments with Saved Cards or Manage Saved Cards.