Mandarin

# Quick start

# Ready module for payments

If you need to make payments to bank cards, but API integration is not yet ready or you do not plan to implement it, then you can create a ready-made module for payments to cards in your Mandarin personal account and make payments from any device: computer, smartphone , tablet. In this case, you can set individual limits for each module and control all operations online.

Instructions on how to configure the module. (opens new window)

# Bulk payouts

This integration method allows you to organize mass payouts from the ready payout registry without programming or implementing the API payout service.

IMPORTANT!

For this type of payouts you need the full numbers of beneficiary cards!

To use it you need:

  1. Register a personal account in Mandarin. After registration your company will have a personal account. You can get information on the status of payments, edit your profile and company details, connect new projects and services, contact Mandarin Support Service (opens new window) and your personal manager.
  2. Submit documents and get approval from your partner bank.
  3. Open a payment account in the bank where you passed the approval process.
  4. Replenish the account for mass payments.
  5. Create a ready-made module for Mandarin mass payments in the Personal Account Modules section.
  6. Download an empty registry template from the module settings for mass payments. The fields in the registry depend on your personal account settings.
  7. Fill the register template with data and upload it to the system.
  8. After uploading, check if the number of transactions and amount, as well as card numbers match. If everything is correct, you can click "Start payouts".
  9. Check the results of payments in the interface, or save them to file.

IMPORTANT!

We recommend you to start with the test operations before you start the production operations.

Set of fields for bulk payouts to bank cards

Parameter Required Description and possible values
order_id Yes order number in your system. It must be unique among the successful transactions!
amount yes amount of payment.
card_number yes the full number of the recipient's card.
email Yes, if exists in registry template Recipient's Email in the settings. Format: user@example.com.
phone Yes, if exists in registry template Recipient's phone in Russian format: +79001234567.

If you have specified in the settings that the fields email and phone should be filled in by default, they don't exist in the registry template.

The format and alignment do not affect the processing of the registry.

# Unified payment form

# Entry Points

Production environment for request: https://secure-app.mandarin.io/api/v1/public/invoices/ (opens new window)

# Authorization

Each request must be authenticated using the X-Api-Key generated in the Personal Account as part of the payment link (under "Integration" - create a new API key). The key is added to the header in the format: Authorization: X-Api-Key: YOUR_API_KEY_VALUE

# Invoice Creation

The method used to create an invoice allows the client to pay through the standard Mandarin payment page. After creating an invoice, the API returns the paymentId, which is used to form the payment link.

Method: POST https://secure-app.mandarin.io/api/v1/public/invoices/

# Request Parameters

Parameter Required Type Description
payment_options_id Yes string Payment link ID from the Mandarin personal account. Defines the project and payment settings.
order No object Order data
order.id No string Internal order ID
order.email No string Client email. If not specified, it will be requested on the payment page
order.phone No string Client phone. If not specified, will be requested on the payment page
urls No object Redirect URLs
urls.success_redirect No string URL to redirect to after successful payment
urls.fail_redirect No string URL to redirect to after unsuccessful payment
urls.conditions No string Link to offer or terms of sale
cart Yes object Cart details
cart.fiscal_receipt_is_required Yes boolean Flag indicating whether a fiscal receipt should be generated
cart.total_price Yes number Total order amount in rubles. Must match the sum of all items
cart.items Yes array List of products or services
cart.items[].quantity Yes integer Product quantity
cart.items[].price Yes number Unit price (in rubles)
cart.items[].total_price Yes number Total item price
cart.items[].vat Yes string VAT rate (Vat0, Vat10, Vat20)
cart.items[].description Yes string Product/service name or description
cart.items[].calculation_method Yes string Calculation method (PREPAY_FULL, FULL_PAYMENT, etc.)
cart.items[].payment_subject Yes string Payment subject (SERVICE, COMMODITY, WORK, etc.)
payment_method_options No object Payment method settings
payment_method_options.credit.terms No array Installment terms (in months)
payment_method_types No array Allowed payment methods (rus_card, int_card, credit)

# What is payment_options_id and where to get it

payment_options_id is the ID of the payment link created in your Mandarin personal account. It determines the project and settings for the invoice.

How to get payment_options_id:

  1. Go to the "Invoices / Links" section in your Mandarin personal account
  2. Find the link you want to use for invoicing via the API
  3. Open its settings — you will see the id parameter in the URL, for example:
    https://secure-app.mandarin.io/dashboard/invoices/links/2d28e8bf-0d60-45ca-b8b4-172820086117
  4. The value 2d28e8bf-0d60-45ca-b8b4-172820086117 is your payment_options_id

Request example

curl --location 'https://secure-app.mandarin.io/api/v1/public/invoices/' \
--header 'X-Api-Key: Nwii9xFAfHjAWkk6PPOFUmpheFe123' \
--header 'Content-Type: application/json' \
--data '{
"payment_options_id": "2d28e8bf-0d60-45ca-b8b4-172820086117",
"order": {
"id": "NewOrder_000000000001",
"email": "ya@ya.ru",
"phone": "79163025599"
},
"urls": {
"success_redirect": "https://google.com",
"fail_redirect": "https://ya.ru",
"conditions": "https://string"
},
"cart": {
"fiscal_receipt_is_required": true,
"total_price": 20000.00,
"items": [
{
"quantity": 2,
"price": 10000.00,
"vat": "Vat20",
"description": "Delivery",
"total_price": 20000.00,
"calculation_method": "PREPAY_FULL",
"payment_subject": "SERVICE"
}
]
},
"payment_method_options": {
"credit": {
"terms": ["3", "6", "12", "18", "24"]
}
},
"payment_method_types": ["rus_card", "credit", "int_card"]
}'

Successful response example

{
"success": true,
"paymentId": "8762f870-1790-4aaf-a8a3-994c548836fd",
"message": "Invoice created successfully"
}

# Invoice status check

You can check the status of a created invoice manually or automatically.

For automatic status updates, open the payment link settings in your Personal Account, enable Send callbacks (Webhook), and specify the URL where you want to receive invoice status change notifications.

To check the invoice status manually, use an API request and pass the invoice paymentId received when the invoice was created.

Request:

GET https://secure-app.mandarin.io/api/v1/public/invoices/{{paymentId}}/check-state/

Response example:

In both cases the response structure is the same:

{
    "invoice_id": "74576aa7-ba80-4ce0-80db-cd5603095746",
    "created_at": "2026-05-13T10:15:00+00:00",
    "order_id": "123456",
    "amount": "1000.00",
    "currency": "RUB",
    "invoice_status": "processing",
    "total_paid": "5000.00",
    "remaining_amount": "1000.00",
    "payment_breakdown": [
        {
            "method": "card",
            "method_type": "cash",
            "amount": "5000.00",
            "timestamp": "2026-05-13T10:15:00+00:00",
            "status": "success",
            "id": "f4107e90f98447978036383f6754325e",
            "additional_id": "23290726",
            "settlement_amount": "5000.00",
            "payment_method_metadata": {
                "loan_term": 12
            }
        }
    ],
    "customer": {
        "email": "test@mandarin.io",
        "phone": "79999999999"
    }
}

If callback delivery fails (non-2xx response code), the system retries with exponentially increasing intervals for up to 24 hours (the second attempt is after one minute).
There are up to 10 delivery attempts in total.

Field descriptions:

Value Description
invoice_id Invoice identifier, paymentId
order_id Order number
amount Total invoice amount
currency Currency
invoice_status Invoice statuses: processing, paid, partially_paid
total_paid Total amount paid so far
remaining_amount Remaining amount to pay
payment_breakdown Payment attempts array
payment_breakdown.method Payment method (card — Russian cards, card2 — international cards, sbp — SBP, credit — credit/installment, bnpl — BNPL)
payment_breakdown.method_type Top-level abstraction — cash combines domestic and international card payments
payment_breakdown.amount Payment amount
payment_breakdown.status Operation status: processing, approved, success, failed
payment_breakdown.id Application or operation ID in the API: application_id, order.id, secure_data.id
payment_breakdown.additional_id Application or payment ID in the payment gateway: offer_id, gw_id, tx.id
payment_breakdown.settlement_amount Amount to be credited to the company account excluding commission (Decimal or null)
payment_breakdown.payment_method_metadata For credit/installment — loan term in months
customer Customer data
customer.email Customer email
customer.phone Customer phone

# Next steps

After receiving the paymentId, redirect the user to the payment page:
https://secure-app.mandarin.io/payment/{paymentId}
Example:

https://secure-app.mandarin.io/payment/8762f870-1790-4aaf-a8a3-994c548836fd

← Ready integrations →