RU: Bank Card - Disbursements

📘
"paymentMethodName": "DisbursementBankCardRUS"

Send funds to a recipient's bank card issued in Russia. The recipient is identified by the card number. Depending on your integration, you may also need to provide identification details of the individual sending the funds.

Requirements

The same paymentMethodName is used for both sets of requirements.

Requirement	Basic requirements	Additional sender identification
Recipient's card number	Required	Required
Amount and currency objects	Required	Required
`disbursements[].payer`	Not required	Required
Sender's name	Not required	One complete name pair is required
Sender's phone number and date of birth	Not required	Required
Sender's identity document	Not required	Required; see the field table below

Basic requirements apply to integrations enabled for disbursements without sender identification details. The payer object is not required for this scenario.

Additional sender identification applies to integrations that require details of the individual sending the funds, including person-to-person and own-account remittances. Supply the real sender's details in payer for every disbursement.

📘
Your account manager confirms which requirements apply to your integration. The presence or absence of payer does not select a different processing scenario. If sender identification is required, omitting payer does not switch the request to the basic scenario.

Payment method features and limits

Feature	DisbursementBankCardRUS
Country	Russia
`paymentMethodName`	`DisbursementBankCardRUS`
Disbursement currency	RUB
Payments	No
Disbursements	Yes
Minimum and maximum amount per transaction	Defined for your integration
Sender limits	Per-transaction and monthly limits may apply when sender identification is required
Merchant-initiated refunds	No
Chargebacks	No

Your account manager confirms the applicable data requirements, supported documents and issuing countries, amount limits, and available source currencies during onboarding. Adding identification details does not automatically change the limits configured for your integration.

Disbursement workflow

The workflow applies to both sets of requirements. The sender is the individual sending the funds when sender identification applies; the merchant integrates with Carusell, and the recipient holds the destination card. The sender and recipient may be the same person.

Save your clientReferenceId and create an intent containing a disbursements array. Provide the recipient's card number, amount and currency objects, a webhook URL, and sender details when required for your integration.
Check the creation response for both created disbursements and disbursementCreationErrors. Store intentId and each created disbursement's ID. ACCEPTED means the disbursement was accepted for processing; it does not confirm credit to the recipient.
Carusell submits created disbursements to the processing partner and sends status updates to each disbursement's webhook URL. Match transactionId to the stored disbursement ID and acknowledge the webhook with HTTP 2xx.
If the creation response or a webhook is missing, retrieve the existing intent by clientReferenceId or intentId. Resolve the original outcome before submitting another payout; see the Recovery tab under Status Updates.

Card processing and status updates are asynchronous, as shown in parallel below. See Status Updates for the meaning of each status and the rules for subsequent returns.

sequenceDiagram
    autonumber
    actor S as Sender (Payer)
    participant M as Merchant
    participant C as Carusell
    participant P as Processing Partner
    actor R as Recipient (Payee)

    opt Transfer requested by an individual
        S->>M: Request a transfer
    end

    Note over M,C: Use DisbursementBankCardRUS.<br/>Provide the recipient's card number and amounts.<br/>Include payer details when required for your integration.

    M->>C: POST /processing/api/v1/intents
    C->>C: Validate request and required sender details<br/>Check route, limits and available balance

    alt Request rejected
        C-->>M: Error response
    else Intent created
        C-->>M: intentId, created disbursements and their IDs<br/>Statuses and any disbursementCreationErrors

        Note over M,C: Check the outcome for each requested disbursement.<br/>ACCEPTED does not confirm credit to the recipient.

        loop For each created disbursement
            C->>P: Submit the disbursement

            par Recipient card processing
                opt Payout approved
                    P->>R: Attempt to credit the recipient's card
                end
            and Status updates
                loop While the outcome is pending
                    C->>P: Request processing status
                    P-->>C: Current status and result
                    opt Status updated
                        C->>M: Status update to disbursements[].webhookUrl<br/>transactionId and status
                        M-->>C: HTTP 2xx acknowledgement
                    end
                end
            end

            Note over M,C: Reconcile updates using the same disbursement ID.<br/>Follow the status and return-handling rules on this page.
        end
    end

    opt Creation response or webhook is missing
        M->>C: GET intent by clientReferenceId or intentId
        C-->>M: Intent details, disbursement statuses<br/>and any creation errors
        Note over M,C: Resolve the original outcome before submitting another payout.
    end

Create an Intent

Use POST /processing/api/v1/intents.

The API Reference describes common request fields, authentication, and response objects. The sections below describe requirements specific to this payment method.

All example identities, card numbers, and transaction identifiers on this page are illustrative.

Recipient card details

Path: disbursements[].payeePaymentInstrument.incomingDetails

Field	Basic requirements	Additional sender identification	Type	Description	Example
`number`	Required	Required	String	Full recipient card number. Send as a string of digits without spaces or separators.	`4111111111111111`

Set disbursements[].payeePaymentInstrument.paymentMethodName to DisbursementBankCardRUS.

Amounts

Paths: disbursements[].submittedAmount and disbursements[].authAmount

Field	Basic requirements	Additional sender identification	Description
`submittedAmount.currency`	Required	Required	Required source currency, enabled for your integration.
`submittedAmount.value`	Conditional	Conditional	Amount to send in the source currency. Leave `null` when specifying the exact amount to be credited in `authAmount.value`.
`authAmount.currency`	Required	Required	Required target currency. Use `RUB` for this method.
`authAmount.value`	Conditional	Conditional	Amount to be credited to the recipient in RUB. Leave `null` when specifying the source amount in `submittedAmount.value`.

Include both submittedAmount and authAmount, each with a currency.

Choose one option:

Set the amount to send: enter submittedAmount.value and leave authAmount.value as null.
Set the amount to receive: enter authAmount.value and leave submittedAmount.value as null.

The amount must be greater than zero.

Amounts are expressed in the named currency: 1500.00 with RUB means 1,500 rubles.

For currency conversion scenarios, see Amount Fields: submittedAmount and authAmount.

Sender identification

Path: disbursements[].payer

payer is an object. It is conditional for this payment method and required when additional sender identification applies.

The fields below describe the individual sending the funds, who may be different from the recipient. Do not populate them with the merchant company's details or a shared default person.

For additional sender identification, supply at least one complete name pair: firstNameLocal with lastNameLocal, or firstNameEng with lastNameEng. The Name Pair Selection rules below determine which pair is used. The idSeries field is required for a Russian internal passport.

Field	Basic requirements	Additional sender identification	Type	Description
`firstNameLocal`	Not required	Conditional	String	Sender's first/given name in a non-Latin script, as shown in the identity document. Supply together with `lastNameLocal`.
`lastNameLocal`	Not required	Conditional	String	Sender's surname/family name in a non-Latin script, as shown in the identity document. Supply together with `firstNameLocal`.
`firstNameEng`	Not required	Conditional	String	Sender's first/given name in Latin script, as shown in the identity document, regardless of the document's language. Supply together with `lastNameEng`.
`lastNameEng`	Not required	Conditional	String	Sender's surname/family name in Latin script, as shown in the identity document, regardless of the document's language. Supply together with `firstNameEng`.
`phone`	Not required	Required	String	International phone number containing digits only, including the country code. Do not include `+`, spaces, or separators. Example: `77000000000`.
`dateOfBirth`	Not required	Required	String, date	Sender's date of birth in `YYYY-MM-DD` format. Example: `1990-05-17`.
`idType`	Not required	Required	String	Identity document type. Use a value from the document type table below.
`idNumber`	Not required	Required	String	Document number. Preserve letters and leading zeros. For a Russian internal passport (`idType = PASSPORT`, `idIssueCountry = RU`), send the number without the series and supply the series separately in `idSeries`.
`idIssueDate`	Not required	Required	String, date	Document issue date in `YYYY-MM-DD` format. Example: `2020-11-03`.
`idIssueCountry`	Not required	Required	String	Document issuing country, using an uppercase ISO 3166-1 alpha-2 code, such as `KZ` or `RU`. This is not the sender's country of residence or the recipient's country.
`idSeries`	Not required	Conditional	String	Required for a Russian internal passport: `idType = PASSPORT` and `idIssueCountry = RU`. For this method, supply this field only for that document type and issuing country. Send the series separately from `idNumber` and preserve leading zeros.
`currentAddress`	Not required	Not required	Object	Not required for the sender identification scenario described on this page.

Dates contain a calendar date only. Do not append a time or timezone.

Document expiry date and issuing authority code are not required for this scenario.

Name Pair Selection

Populate at least one complete pair:

firstNameLocal and lastNameLocal for names written in a non-Latin script.
firstNameEng and lastNameEng for names written in Latin script, in any language.

The Eng suffix identifies the API fields for Latin-script names. It does not mean that names should be translated into English. Use the spelling printed in the identity document.

The platform selects the name as follows:

If the Local pair is complete, it is used.
Otherwise, the complete Eng pair is used.
If neither pair is complete, the sender details are incomplete.

First and last names from different pairs are not combined. A missing, null, empty, or whitespace-only value does not complete a pair.

⚠️
If all four name fields are populated, the Local pair takes priority. It will be used for sender identification during processing. Incorrect or inconsistent Local values can affect verification and the disbursement result, including a decline, even when the Eng pair is correct. Populate the pair you intend to use with the sender's name exactly as it appears in the document.

Document Types

When additional sender identification applies, use the following payer.idType values:

Value	Document
`ID_CARD`	National identity card.
`PASSPORT`	Internal or domestic passport.
`INTERNATIONAL_PASSPORT`	Passport for international travel.
`RESIDENCE_PERMIT`	Residence permit.

These values form the platform's public document type vocabulary. Supported combinations of document type and issuing country are confirmed for your integration during onboarding.

For a Russian internal passport, provide both idSeries and idNumber as separate strings.

The example requests a disbursement of 1,500 RUB without currency conversion. Sender identification is not required for this integration.

{
  "clientReferenceId": "ru-card-basic-000001",
  "disbursements": [
    {
      "webhookUrl": "https://merchant.example/webhooks/disbursements",
      "payeePaymentInstrument": {
        "paymentMethodName": "DisbursementBankCardRUS",
        "incomingDetails": {
          "number": "4111111111111111"
        }
      },
      "submittedAmount": {
        "value": null,
        "currency": "RUB"
      },
      "authAmount": {
        "value": 1500.00,
        "currency": "RUB"
      }
    }
  ]
}

The example uses the complete Eng pair for a document whose name is written in Latin script. The payer object is supplied for this disbursement.

{
  "clientReferenceId": "ru-card-identified-000001",
  "disbursements": [
    {
      "webhookUrl": "https://merchant.example/webhooks/disbursements",
      "payeePaymentInstrument": {
        "paymentMethodName": "DisbursementBankCardRUS",
        "incomingDetails": {
          "number": "4111111111111111"
        }
      },
      "payer": {
        "firstNameEng": "ASLAN",
        "lastNameEng": "SERIKOV",
        "phone": "77000000000",
        "dateOfBirth": "1990-05-17",
        "idType": "INTERNATIONAL_PASSPORT",
        "idNumber": "N12345678",
        "idIssueDate": "2020-11-03",
        "idIssueCountry": "KZ"
      },
      "submittedAmount": {
        "value": null,
        "currency": "RUB"
      },
      "authAmount": {
        "value": 1500.00,
        "currency": "RUB"
      }
    }
  ]
}

Russian internal passport: payer example

A sender with a Russian internal passport may instead be represented by the following payer object, where that document is supported for your integration:

{
  "firstNameLocal": "Иван",
  "lastNameLocal": "Иванов",
  "phone": "79000000000",
  "dateOfBirth": "1990-05-17",
  "idType": "PASSPORT",
  "idNumber": "123456",
  "idSeries": "4510",
  "idIssueDate": "2020-11-03",
  "idIssueCountry": "RU"
}

The response contains the intent ID, the created disbursements, and their current statuses. Keep your original clientReferenceId and store the returned intentId and disbursements[].id values. Use each disbursement ID to correlate subsequent status notifications.

An ACCEPTED status means the disbursement has been accepted for processing. It does not confirm that the recipient has been credited.

The following is a shortened, illustrative response for the basic request above. The card number is masked in storedDetails.

{
  "intentId": "24148546870213835",
  "payments": [],
  "disbursements": [
    {
      "id": "241485668832161722",
      "submittedAmount": {
        "value": 1500.00,
        "currency": "RUB"
      },
      "authAmount": {
        "value": 1500.00,
        "currency": "RUB"
      },
      "payeePaymentInstrument": {
        "id": "3525967789943272833",
        "storedDetails": {
          "maskedNumber": "411111******1111"
        }
      },
      "createdAt": 1793260800.0,
      "status": "ACCEPTED"
    }
  ],
  "clientReferenceIntentId": "ru-card-basic-000001",
  "intentStatus": "CREATED"
}

Validation and declines

Check disbursementCreationErrors as well as the list of created disbursements. A successful HTTP response alone does not mean that every requested disbursement was created.

When sender identification is required, missing or incomplete mandatory payer details cause the disbursement to be rejected at creation. Validation messages identify the affected fields.

A disbursement may also be declined during processing, for example because an applicable sender limit is exceeded or the recipient card cannot receive the transfer.

Use the API Reference for error response structures and Webhooks: Example for status notification fields.

Status Updates

Set disbursements[].webhookUrl for each disbursement to receive transaction status updates. See Webhooks: Overview.

Status	Meaning
`ACCEPTED`	The platform accepted the disbursement for processing.
`DISBURSEMENT_REQUESTED`	Processing is in progress.
`PAID_OUT`	The disbursement is reported as successfully processed. For additional sender-identification integrations, see Processing time and returns below.
`DECLINED`	The disbursement was declined.
`ERROR`	A processing error was reported. Do not automatically resubmit the transfer. A later status update may correct the outcome to `PAID_OUT`; reconcile it against the same disbursement ID.

Status notifications may include intermediate statuses. Wait for the processing outcome rather than treating ACCEPTED as success.

Processing time and returns

For integrations requiring additional sender identification, allow up to three days for processing. A pending status alone is not a reason to submit another disbursement for the same transfer. If the status is still pending after that period, retrieve the latest status and contact support. The elapsed time alone does not establish that the disbursement failed.

For integrations requiring additional sender identification, a transfer reported as PAID_OUT may subsequently be returned if the recipient's card cannot be credited. This status does not guarantee final credit to the recipient. Do not assume that a return will generate an automatic status update. If the recipient reports non-receipt, contact support with the disbursement ID to investigate the transfer and any return.

The following is a shortened example. transactionId matches the disbursement ID from the creation response.

{
  "transactionType": "DISBURSEMENT",
  "transactionId": "241485668832161722",
  "status": "PAID_OUT"
}

These recovery steps apply to both the basic and additional sender-identification scenarios.

If the creation request times out or its response is lost, retrieve the intent using the original clientReferenceId:

GET /processing/api/v1/intents/by-client-reference/{clientReferenceId}

If you already know the intentId, retrieve the intent and its disbursements by ID:

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

Use the same settlement-account-id as in the creation request and the usual authentication headers. Check the returned disbursement statuses and disbursementCreationErrors before deciding what to do next.

A missing response or webhook does not mean that the payout failed. Do not create a new payout with a new reference while the original outcome is unknown. Repeating the creation request with the same reference can return HTTP 409; it does not guarantee a replay of the original successful response.

If lookup does not establish the outcome, contact support with the original clientReferenceId, settlement account, and any returned intent or disbursement IDs before submitting another payout for the same transfer.

Sandbox Testing

Use DisbursementBankCardRUS with your sandbox endpoint, credentials, and an account configured for this method's emulator. Your account manager must confirm that the emulator is enabled for your sandbox integration. The payment method name alone does not enable simulation.

Use the same card fields as in a live request: incomingDetails.number. No additional card fields are needed. The example exercises the basic scenario and omits payer.

📘
These scenarios simulate the payout outcome. A successful sandbox test does not verify the sender's identity or confirm that a particular identity document will be accepted during live processing.

For these two scenarios, use RUB for both currencies, leave submittedAmount.value as null, and send the exact numeric authAmount.value shown below.

`authAmount.value`	Simulated outcome
`100.02`	`PAID_OUT`
`100.03`	`DECLINED`

The result is selected by the amount, not by the card number. These examples do not test live issuer decisions or bank-specific decline reasons.

Use authAmount.value: 100.02 for this success example.

{
  "clientReferenceId": "ru-card-sandbox-success-000001",
  "disbursements": [
    {
      "webhookUrl": "https://merchant.example/webhooks/disbursements",
      "payeePaymentInstrument": {
        "paymentMethodName": "DisbursementBankCardRUS",
        "incomingDetails": {
          "number": "4111111111111111"
        }
      },
      "submittedAmount": {
        "value": null,
        "currency": "RUB"
      },
      "authAmount": {
        "value": 100.02,
        "currency": "RUB"
      }
    }
  ]
}

Declined payout: request changes

Repeat the success request with a new clientReferenceId, such as ru-card-sandbox-decline-000001, and set disbursements[0].authAmount.value to 100.03. Keep the same method name, card field, RUB currencies, and webhook location. The creation response has the same structure and contains a new disbursement ID.

The emulator uses the ordinary intent-creation response. Creation does not guarantee that the final outcome is already available in the synchronous HTTP response. The response and webhook examples in these tabs are shortened and illustrative. Use the actual returned disbursement ID to correlate them.

{
  "intentId": "24148546870213836",
  "disbursements": [
    {
      "id": "241485668832161723",
      "status": "ACCEPTED"
    }
  ],
  "clientReferenceIntentId": "ru-card-sandbox-success-000001",
  "intentStatus": "CREATED"
}

Correlate each notification with the disbursement ID returned for that request. These examples are shortened.

Success — 100.02

{
  "transactionType": "DISBURSEMENT",
  "transactionId": "241485668832161723",
  "status": "PAID_OUT"
}

Decline — 100.03

{
  "transactionType": "DISBURSEMENT",
  "transactionId": "241485668832161724",
  "status": "DECLINED"
}

Repeating sandbox tests

Repeated requests for the same amount and currency on the same settlement account may be blocked by duplicate protection before they reach the emulator, even when you change clientReferenceId or the card number. Check disbursementCreationErrors before waiting for an outcome webhook. Your account manager confirms the repeat interval configured for your sandbox account. Running the 100.02 scenario followed by the 100.03 scenario uses different amounts; repeating either scenario is subject to this protection.