📘

This payment method is supported in two integration scenarios: Host-to-Host and Hosted Checkout.

• For Hosted Checkout, please refer to the dedicated page.
• For Host-to-Host integration, please follow the guide below.

📓

Please use the following paymentMethodName value when creating the Intent and when completing the payment object.

"paymentMethodName": "BankCardKZ"

Payment Method Features

Workflow: Payment & Refund

Download in high resolution

Possible Payment Scenarios:

📘

Auto-Capture or Cancellation

To enable automatic capture or cancellation, you must inform our integration team in advance so they can configure the auto-trigger and define the required timer on their side

List of used API Requests:

Intent Creation Request/Response

{
  "clientReferenceId": "1234",
  "payments": [
    {
      "payer": {
        "phone": "+XXXXXXXXXXX"
      },
      "paymentInstrument": {
        "paymentMethodName": "BankCardKZ",
        "incomingDetails": {
          "number": "4111111111111111",
          "expiryMonth": "12",
          "expiryYear": "2028",
          "cvv": "123",
          "holderName": "JOHN DOE",
          "redirectUrl": "https://merchant.example.com/payment/success",
          "failureUrl": "https://merchant.example.com/payment/failure",
          "account": "string"
        }
      },
      "submittedAmount": {
        "value": 100.05,
        "currency": "USD"
      },
      "authCurrencyCode": "RUB",
      "description": "Vertex - INTENT 1234",
      "webhookUrl": "webhookUrl"
    }
  ],
  "description": "Vertex - INTENT 1234",
  "merchant": {
    "name": "Mustermann",
    "website": "website.io"
  }
}

Capture / Cancel Payment

🕑

IMPROTANT

The timeframe between the authorization and capture / cancellation must not exceed 5 days

• To capture or cancel the payment transaction and release funds on the payer’s account, you must send a Payment Update request.
• Use the following endpoint: Update Payment status and specify the action you wish to perform:
  • status = CAPTURED - to capture the authorised amount.
  • status = CANCELLED - to cancel the authorisation and release the reserved funds
• After receiving your request, we will initiate the capture process and send you a standard webhook with the updated transaction status.

Refunds

📘

Refunds cannot exceed the total value of confirmed transactions for the current day.

To initiate the refund (full or partial) to the payer's original payment instrument, you must send a separate Refund request.

Use the following endpoint: Create Refund and specify the following parameters:

{
  "paymentId": 204264682781298700,
  "partial": false,
  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}

{
  "paymentId": 204264682781298700,
  "partial": true,

  // For a partial refund, specify ONLY ONE of the following:
  // - paymentSubmittedAmount (original/submitted currency)
  // - paymentAuthAmount (authorised/settlement currency)
  
  // This is required when FX conversion was involved in the payment
  // (e.g. KZT -> RUB). The refund will be calculated using the SAME
  // exchange rate as the original payment.
  //
  // Choose the object based on the currency in which you want to
  // define the refund amount, and populate only that object.
    
    


// Option 1: Submitted currency (inactive example)
//    "paymentSubmittedAmount": {
//    "value": 100.05,
//    "currency": "KZT"
//  },
    
    
// Option 2: Authorised currency (active example)
	"paymentAuthAmount": {
    "value": 100.05,
    "currency": "RUB"
  },

  "reason": "Customer requested a refund",
  "webhookUrl": "webhookUrl"
}

After the creation of the refund request you must wait for the callback, that will provide you with the latest transaction status

Webhooks

🔗

More about Payment Webhooks on the dedicated page

You will receive the webhooks on each status change of any transaction you created.

Testing in Sandbox

The bank card emulator simulates the full H2H payment lifecycle in the sandbox environment. Use the test cards below to reproduce specific authorisation and completion outcomes.

⚠️

Use the listed test cards only. Any card not on this list will be accepted at the Intent creation step, but authorisation will fail. Cards from the list are the only ones guaranteed to drive the emulator through a complete flow.

What the H2H emulator covers

• Available in the sandbox environment only.
• The flow (Frictionless or Challenge) and the outcome at each stage are determined by the PAN only. Expiry date, CVV, and cardholder name do not affect emulator logic — any values that pass validation are accepted.
• Amount and currency do not affect emulator behaviour.
• Completion behaviour (capture or cancellation, automatic or manual) depends on the Settlement Account + payment method configuration. See Completion below.

Authorisation flows

Regardless of the flow, the payer must briefly land on a Carusell-hosted page so we can collect device metadata for fraud checks. The client redirects the payer to the URL returned in the Intent creation response. After metadata collection, the payer is routed according to the flow determined by the PAN:

• Frictionless — the payer is redirected back to the merchant storefront via redirectUrl, and the authorisation result is delivered via webhook.
• Challenge — the payer is presented with a 3DS OTP form before being redirected back to the merchant.

Frictionless flow

No 3DS challenge is shown. After metadata collection, the payer returns to the merchant storefront and the authorisation result arrives via webhook.

Test cards

Name	PAN	Authorisation
FF_Card_1	4462603043025620	Success
FF_Card_2	4462603040971339	Success
FF_Card_3	4462603042343024	Failure

Completion: capture or cancellation

After a successful authorisation, the payment must be completed — either captured (funds taken) or cancelled (authorisation released). Whether this happens automatically or requires a client request is configured per Settlement Account and payment method.

Emulator behaviour

The completion outcome is determined by the same PAN used for authorisation. The emulator returns the same outcome regardless of action (capture or cancellation) or trigger (automatic or manual).