H2H: Payments with Saved Cards

Create a payment using a saved paymentInstrumentToken instead of sending the card details again. Set tokenPaymentReason to identify whether the customer or the merchant initiates the payment.

To obtain a token, see Card Tokenization via API. To find a customer's saved cards, see Manage Saved Cards.

Choose CIT or MIT

MIT supports unscheduled card-on-file payments: your system initiates a charge when the relevant business event occurs. There is no additional MIT subtype parameter.

You can use the same eligible saved-card token for CIT and MIT, including tokens saved previously through the API or Hosted Checkout.

flowchart TD
    A[Saved card token] --> B{Who initiates the payment?}
    B -->|Customer| C[CIT request with a return URL]
    C --> D{Additional confirmation required?}
    D -->|Yes| E[Open the returned URL for the customer]
    D -->|No| F[Retrieve the result with GET or receive a webhook]
    E --> F
    B -->|Merchant system| G[MIT request without customer interaction]
    G --> F

Request requirements

Use POST /api/v1/intents, relative to your environment's processing base URL. See Access URLs and API Authentication.

Use the following headers for both CIT and MIT. The examples cover standard card payments. Include any additional fields required by your account, business category or the BankCardRU payment method.

Customer initiated payment (CIT)

Use CIT when the customer chooses to make a payment with their saved card. Include a return URL so the customer can return to your application after any required confirmation.

{
  "clientReferenceId": "order-1002",
  "payments": [
    {
      "payer": {
        "merchantPayerReference": "12345"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG",
        "tokenPaymentReason": "CIT",
        "incomingDetails": {
          "redirectUrl": "https://merchant.example/payment/return",
          "failureUrl": "https://merchant.example/payment/failure"
        }
      },
      "submittedAmount": {
        "value": 500,
        "currency": "RUB"
      },
      "authCurrencyCode": "RUB",
      "webhookUrl": "https://merchant.example/webhooks/payments"
    }
  ]
}

{
  "intentId": "204264682781298710",
  "payments": [
    {
      "id": "204264682781298711",
      "status": "ACCEPTED",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
      },
      "additionalData": {
        "details": {
          "url": "https://checkout.example/verification/session-1002"
        }
      }
    }
  ],
  "paymentCreationErrors": []
}

Open the returned URL in the customer's browser or web view and follow the BankCardRU authorisation flow. Retrieve the payment result or receive its webhook after the customer finishes.

Merchant initiated payment (MIT)

Use MIT when your system charges a previously saved card without the customer taking part. Supply the saved token and tokenPaymentReason: "MIT". The standard MIT request can omit incomingDetails, return URLs and threeDSContext.

{
  "clientReferenceId": "journey-1003",
  "payments": [
    {
      "payer": {
        "merchantPayerReference": "12345"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG",
        "tokenPaymentReason": "MIT"
      },
      "submittedAmount": {
        "value": 750,
        "currency": "RUB"
      },
      "authCurrencyCode": "RUB",
      "webhookUrl": "https://merchant.example/webhooks/payments"
    }
  ]
}

{
  "intentId": "204264682781298720",
  "payments": [
    {
      "id": "204264682781298721",
      "status": "AUTHORIZED",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
      }
    }
  ],
  "paymentCreationErrors": []
}

The initial response may contain an intermediate or an already available result.

Get the payment result

For either CIT or MIT, use GET /api/v1/intents/{intentId}, GET /api/v1/payments/{paymentId}, or payment webhooks. The normal payment status model applies. See Payment Overview.

{
  "id": "204264682781298720",
  "payments": [
    {
      "id": "204264682781298721",
      "status": "CAPTURED",
      "submittedAmount": {
        "value": 750,
        "currency": "RUB"
      },
      "authAmount": {
        "value": 750,
        "currency": "RUB"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
      }
    }
  ]
}

Payment webhook

The equivalent payment webhook uses transactionId for the payment identifier and includes isStoredCredential: true:

{
  "transactionType": "PAYMENT",
  "transactionId": "204264682781298721",
  "intentId": "204264682781298720",
  "status": "CAPTURED",
  "isStoredCredential": true,
  "paymentInstrument": {
    "paymentMethodName": "BankCardRU",
    "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
  }
}

These are response excerpts. A payment by a saved token does not request a new save, so its token can be returned without savingRequested or isSaved. See Webhooks for the standard notification contract.

Handle errors

Check the request result, payment creation result and payment status separately.

Errors relevant to saved cards

An instrument already recognised as invalid can also be rejected with payment status DECLINED and declineCode: "36" (Restricted card). Handle the payment status and decline details as well as platform error codes.

An existing token without a usable MIT payment capability produces a payment with status ERROR and CODE_PT0009. For example, a GET Intent response may contain this excerpt:

{
  "id": "204264682781298720",
  "payments": [
    {
      "id": "204264682781298721",
      "status": "ERROR",
      "processingStatusCode": "CODE_PT0009",
      "statusMessage": "Payment instrument is not available for merchant-initiated payments",
      "paymentInstrument": {
        "paymentMethodName": "BankCardRU",
        "paymentInstrumentToken": "pi_01J8ZC4M7QK3T5V9XB2NDR6HAG"
      }
    }
  ]
}

Bank declines use the normal payment decline fields. See Decline Reasons, Creation Errors and Processing Errors for the general error model.

Currency conversion and refunds

Token payments use the same amount and currency rules as other payments. Currency conversion remains available: submittedAmount and the resulting authAmount may be in different currencies. The examples use RUB for both to keep the token-specific fields clear.

Where the payment method supports refunds, refund a CIT or MIT payment through the normal refund API, referencing the original payment. A refund does not delete the saved-card token.

Test the integration

Use the test cards listed under BankCardRU Sandbox, an account with H2H tokenization enabled and the appropriate configuration for card binding. Keep sandbox tokens and credentials separate from production.

Cover the complete customer journey: save a card, retrieve its token, make a CIT payment, handle any required confirmation, make a MIT payment, handle an unsuccessful payment, delete the token and save the card again. For binding without a purchase, also cover zero amount authorisation and cancellation of a nonzero hold.