Payment Instrument Tokenization (Checkout)

How it works

In the hosted Checkout flow you make one API call — creating the payment intent. Everything else happens on the hosted form:

The shopper experience

Saving, selecting and removing cards happen on the hosted checkout. Below is what the shopper sees and can do.

List of Scenarios

Consent

• The "Save card for future payments" option controls whether the card is added to the shopper's saved cards for future payments.
• Its initial state is configured in the Checkout form template.
• When the option is off, the card is not added to the shopper's saved-card list.

Limit on saved cards

• By default, the saved-card limit is 5 cards per shopper within a settlement account, shared across payment methods.
• The limit is configured in the Checkout form template. Your integration manager can adjust it.
• When the limit is reached, the shopper can still pay with a new card without adding it to their saved cards.
• Removing an existing saved card can make room for another card.

Unavailable cards

• Expired cards remain visible in the shopper's saved-card list and are marked "Expired".
• They appear after cards whose expiry date has not passed and cannot be selected for payment.
• In the current hosted Checkout, the removal menu is also disabled for expired cards.

Enabling saved cards

Two things are required for a shopper to see and reuse their saved cards:

1. Feature enabled on the form template.

• Card saving is off by default and must be enabled in the Checkout form template.
• Ask your integration manager to enable it, configure the saved-card limit, and set the initial state of the "Save card for future payments" option.

2. Identify the shopper in the intent.

• Saved cards are tied to (settlement account + payer.merchantPayerReference).
• Pass a stable merchantPayerReference (the shopper's id in your system) when creating the intent.
• Use the same settlement account and reference on future intents so the shopper's saved cards appear automatically.
• If you omit the reference, cards cannot be added to the shopper's saved-card list or reused through that list.

Create the intent

POST https://sandbox.carusell.world/processing/api/v1/intents

curl --request POST \
  --url 'https://sandbox.carusell.world/processing/api/v1/intents' \
  --header 'content-type: application/json' \
  --header 'X-API-Key: <token>' \
  --data '{
    "clientReferenceId": "order_12345",
    "useCheckoutForm": true,
    "paymentIntent": {
      "submittedAmount": { "value": 17.07, "currency": "USD" },
      "description": "Order #12345",
      "webhookUrl": "https://merchant.com/webhook",
      "payer": {
        "merchantPayerReference": "CUST_12345",
        "email": "[email protected]"
      },
      "formDetails": {
        "template": "checkout-light",
        "displayedPaymentMethods": ["CARD", "SBP"],
        "backToStoreRedirectUrl": "https://merchant.com/checkout"
      }
    }
  }'

Key fields

Response — the intent contains the checkout session id and the hosted link to open:

{
  "intentId": "<intent_id>",
  "paymentIntent": {
    "intentSessionId": "is_01JVM1PZ0J7B1Y9J6R3X2M8KQF",
    "additionalData": {
      "url": "https://checkout.carusell.world/is_01JVM1PZ0J7B1Y9J6R3X2M8KQF"
    }
  }
}

Redirect the shopper to paymentIntent.additionalData.url.

Webhook

When the payment finishes, we call your webhookUrl. The webhook includes information about the card used. When saving is requested during Checkout, the paymentInstrument object also reports the saving result when it is available.

For a successful save request, paymentInstrument.isSaved is true and paymentInstrument.paymentInstrumentToken contains the saved payment instrument token with the pi_ prefix. This also covers a request to save a card that was already saved for the shopper.

Successful saving result

Example of a successful payment with a successful saving result, showing the relevant fields:

{
  "transactionType": "PAYMENT",
  "transactionId": "<payment_id>",
  "intentId": "<intent_id>",
  "status": "CAPTURED",
  "paymentInstrument": {
    "paymentMethodName": "BankCardRU",
    "savingRequested": true,
    "isSaved": true,
    "paymentInstrumentToken": "pi_****YCH4"
  }
}

The webhook returns the full token. It is masked here for illustration.

Fields

Paying with a saved card

For a payment made with a previously saved card, isStoredCredential is true.

Example showing the relevant fields:

{
  "isStoredCredential": true,
  "last4": "4242"
}

The payment can also return paymentInstrument.paymentInstrumentToken for the saved instrument it used, without reporting a new save.

Retrieving the saving result via API

The saving result and payment instrument token are also available through GET intent and GET payment.

The examples below show the relevant fields for a successful payment with a successful saving result. The API returns the full token; tokens are masked here for illustration.

GET intent

GET /processing/api/v1/intents/{intentId}

{
  "id": "<intent_id>",
  "intentStatus": "FINALIZED",
  "payments": [
    {
      "id": "<payment_id>",
      "status": "CAPTURED",
      "paymentInstrument": {
        "savingRequested": true,
        "isSaved": true,
        "paymentInstrumentToken": "pi_****YCH4"
      }
    }
  ]
}

GET payment

GET /processing/api/v1/payments/{paymentId}

{
  "id": "<payment_id>",
  "status": "CAPTURED",
  "paymentInstrument": {
    "paymentMethodName": "BankCardRU",
    "savingRequested": true,
    "isSaved": true,
    "paymentInstrumentToken": "pi_****YCH4"
  }
}