# Quick start

Quick start is suitable for any online business that needs to start accepting payments and making payouts as quickly as possible. All tools are configured in the personal account — without development and without API integration.

# Payout form

The payout form is a ready-made tool in the Mandarin personal account for one-off and single payouts to bank cards without API integration.

It is suitable if you need to:

transfer money to cards for employees, contractors, or customers;
work from any device (computer, smartphone, tablet);
set limits and control operations in real time.

To get started:

Register a personal account (opens new window) with Mandarin.
Submit documents and complete approval with the partner bank.
Open a payout settlement account and fund it.
Create a payout form in the Payouts → By form section of the personal account.
Configure limits and form parameters.

After setup, you can manually enter recipient details and the amount and send a payout directly from the interface.

Detailed instructions for setting up the payout form (opens new window)

# Payouts by registry

Payouts by registry is a way to send money to cards in bulk using a pre-prepared file (registry). No API integration is required: you upload the file in the personal account, the system validates the data, and starts the payouts.

It is suitable if you need to:

pay rewards or bonuses to a large number of recipients at once;
use a familiar Excel/CSV format instead of programming;
control the total amount and number of operations before starting.

IMPORTANT!

Payouts by registry require recipients' full card numbers.

To get started:

Register a personal account (opens new window) with Mandarin.
Submit documents and complete approval with the partner bank.
Open a payout settlement account at the approved bank.
Fund the account for bulk payouts.
Create a bulk payout form in the Payouts → By form section of the personal account.

How to process a payout:

Download an empty registry template from the form settings. The set of fields depends on your company settings.
Fill in the template with recipient data and upload the file to the system.
Check the number of transactions, total amount, and card numbers.
If everything is correct, click Start payouts.
View the results in the interface or save the report to a file.

IMPORTANT!

Before production payouts, we recommend running test operations.

# Registry fields for payouts to bank cards

Parameter	Required	Description
`order_id`	Yes	Order number in your system. Must be unique among successful operations.
`amount`	Yes	Payout amount.
`card_number`	Yes	Recipient's full card number.
`email`	Yes, if the field is in the template	Recipient's email. Format: `user@example.com`.
`phone`	Yes, if the field is in the template	Recipient's phone in Russian format: `+79001234567`.

If the form settings specify that the email and phone fields are filled in by default, they are not included in the registry template.

Cell format and alignment in the file do not affect registry processing.

# Unified payment form

# Entry points

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

# Authorization

Requests are authenticated with an API key (X-Api-Key). The key is created in the personal account in the payment link settings (Integration section). For details, see Request authentication.

The examples below use the template --header 'X-Api-Key: '.

# Invoice creation

This method is used to create an invoice that the customer can pay through the standard Mandarin payment page. After the invoice is created successfully, the API returns a paymentId used to build 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 identifier
`order.email`	No	string	Customer email. If not specified, it will be requested on the payment page
`order.phone`	No	string	Customer phone. If not specified, it 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 failed payment
`urls.conditions`	No	string	Link to the offer or terms of sale
`cart`	Yes	object	Cart data
`cart.fiscal_receipt_is_required`	Yes	boolean	Flag indicating whether a fiscal receipt must 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 or 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 defines which project and settings will be used when creating an invoice.

How to get payment_options_id:

Go to the Invoices / Links section in the Mandarin personal account
Find the link you want to use for invoicing via the API
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
The value 2d28e8bf-0d60-45ca-b8b4-172820086117 is your payment_options_id

Request example

curl --location --request POST 'https://secure-app.mandarin.io/api/v1/public/invoices/' \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: {{api_key}}' \
--data-raw '{
"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": "Доставка",
     "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 the personal account used for the integration, 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 example

curl --request GET \
  --url https://secure-app.mandarin.io/api/v1/public/invoices/8762f870-1790-4aaf-a8a3-994c548836fd/check-state/ \
--header 'X-Api-Key: {{api_key}}'

Response example:

In both cases, the response structure is the same and looks as follows:

{
    "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` (in progress, 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 in detail (`card` — Russian card payments, `card2` — international payments, `sbp` — SBP payment, `credit` — credit/installment, `bnpl` — Shares)
payment_breakdown.method_type	Top-level abstraction — `cash` combines domestic and international 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 only — 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

# Shares (Dolki)

Shares (Dolki) is commercial installment without banks or MFIs. It helps businesses avoid losing customers when paying upfront is inconvenient or bank installment is unavailable.

The customer completes the purchase online, makes the first payment, and the remaining amount is charged on a schedule. For businesses, it is an additional tool that helps retain sales and expand payment scenarios.

Learn more (opens new window)

← Industry solutions Ready integrations →