# Unified payment form API
Before you start, create a payment link and an API key. All requests and responses are in JSON, UTF-8 encoding.
Typical scenario:
- Your system creates an invoice → receives
paymentId. - Redirects the customer to
https://secure-app.mandarin.io/payment/{paymentId}. - The customer chooses a method and pays or submits an application.
- Mandarin sends a webhook on every invoice change.
- Your system verifies the result with a status request and fulfills the order.
# Invoice creation
POST https://secure-app.mandarin.io/api/v1/public/invoices/
All parameters except payment_options_id are optional: anything not passed is taken from the payment link settings.
# Request parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
payment_options_id | string (UUID) | Yes | Payment link ID. Determines the company, design, and invoice settings |
order | object | No | Order and customer data |
order.id | string | No | Order number in your system. If the order block is passed without id, the number is generated automatically (UUID). Returned in the invoice status as order_id |
order.email | string | No | Customer email. If not passed, the customer enters it on the page |
order.phone | string | No | Customer phone: +79001234567 or 79001234567. If not passed, the customer enters it on the page |
cart | object | No | Cart. If not passed, the payment link cart is used |
cart.items | array | Yes, if cart is passed | Cart items, at least one |
cart.items[].description | string | Yes | Name of the product or service — shown to the customer and included in the receipt |
cart.items[].total_price | number | Yes | Item cost in rubles, with a dot as the decimal separator |
cart.items[].vat | string | Yes | VAT rate, see values |
cart.items[].quantity | integer | No | Quantity, 1 by default |
cart.items[].price | number | No | Unit price. If passed, price × quantity = total_price must hold |
cart.items[].calculation_method | string | No | Calculation method for the receipt, see values |
cart.items[].payment_subject | string | No | Payment subject for the receipt, for example SERVICE, COMMODITY |
cart.total_price | number | No | Total amount for verification: if passed, it must match the sum of total_price of all items |
cart.fiscal_receipt_is_required | boolean | No | Generate a receipt under 54-FZ. false by default |
payment_method_types | array of string | No | Payment methods for this invoice: rus_card, int_card, credit, sber, dolki. If not passed — all methods enabled on the link. An empty array is not allowed |
payment_method_options | object | No | Payment method settings |
payment_method_options.credit.terms | array of string | No | Loan and installment terms in months, for example ["6", "12", "24"]. See Installments and loans |
urls | object | No | Redirect URLs. Must be valid URLs |
urls.success_redirect | string | No | Where to return the customer after a successful payment |
urls.fail_redirect | string | No | Where to return the customer after a failed payment |
urls.conditions | string | No | Link to your offer or terms of sale |
custom_values | array | No | Additional fields shown to the customer on the invoice page |
custom_values[].name | string | Yes | Field name, for example "Contract number". key can be passed instead of name |
custom_values[].value | string | Yes | Field value |
assistance_is_required | boolean | No | The customer needs help with the installment application. false by default. See Installments and loans |
# VAT rates
None (no VAT), Vat0, Vat5, Vat7, Vat10, Vat20, Vat22.
# Calculation method
| Value | Description |
|---|---|
PREPAY_FULL | Full prepayment before the transfer of the payment subject |
PREPAY_PARTIAL | Partial prepayment before the transfer of the payment subject |
AVANS | Advance payment |
FULL_PAY | Full payment, including the advance, at the time of transfer of the payment subject |
PARTIAL_SETTLEMENT_AND_CREDIT | Partial payment at the time of transfer with subsequent payment on credit |
TRANSFER_ON_CREDIT | Transfer without payment with subsequent payment on credit |
CREDIT_PAYMENT | Loan payment after the transfer of the payment subject |
# Request example
curl --request POST \
--url 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": "ORDER-000123",
"email": "client@example.com",
"phone": "+79001234567"
},
"cart": {
"fiscal_receipt_is_required": true,
"total_price": 120000.00,
"items": [
{
"description": "Data Analyst course",
"quantity": 1,
"price": 120000.00,
"total_price": 120000.00,
"vat": "None",
"calculation_method": "FULL_PAY",
"payment_subject": "SERVICE"
}
]
},
"payment_method_types": ["rus_card", "credit", "dolki"],
"payment_method_options": {
"credit": { "terms": ["6", "12", "24"] }
},
"urls": {
"success_redirect": "https://example.com/order/123/success",
"fail_redirect": "https://example.com/order/123/fail",
"conditions": "https://example.com/oferta"
},
"custom_values": [
{ "name": "Contract number", "value": "D-2026-0042" }
]
}'
# Response
Invoice created (201 Created)
{
"success": true,
"paymentId": "8762f870-1790-4aaf-a8a3-994c548836fd",
"message": "Invoice created successfully"
}
paymentId is the invoice ID. Save it: it is used to request the status, and it is also sent in the webhook as invoice_id.
Parameter error (400 Bad Request) — the body indicates the field with the error:
{
"payment_method_types": ["Unknown payment method types: dolki"]
}
| Error | Cause |
|---|---|
Unknown payment method types: ... | The method is not configured on the payment link |
If provided, must contain at least one method | An empty payment_method_types was passed |
Provided total_price does not match sum of items total_price | cart.total_price does not equal the sum of the items |
Total price does not match price * quantity | In an item, price × quantity ≠ total_price |
Access denied or invalid client_id | The link belongs to another company |
No active payment settings found for client_id | Invoices are not set up for the company in the personal account |
Authorization error (401 Unauthorized) — invalid or inactive API key, or the integration is disabled on the link.
# Redirecting the customer
https://secure-app.mandarin.io/payment/{paymentId}
The link can be opened in a browser or sent via a messenger or SMS. To open a specific method right away, add it to the end of the URL — see Payment methods.
# Invoice status
GET https://secure-app.mandarin.io/api/v1/public/invoices/{invoice_id}/check-state/
Returns the current invoice status and all its operations. The same object is sent in the webhook.
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 (200 OK) — an invoice for 120,000 RUB: the first card payment attempt failed, then the customer took out an installment plan:
{
"invoice_id": "8762f870-1790-4aaf-a8a3-994c548836fd",
"created_at": "2026-11-10T10:15:00+00:00",
"order_id": "ORDER-000123",
"amount": "120000.00",
"currency": "RUB",
"invoice_status": "paid",
"total_paid": "120000.00",
"remaining_amount": "0.00",
"payment_breakdown": [
{
"method": "card",
"method_type": "cash",
"amount": "0.00",
"timestamp": "2026-11-10T10:16:12+00:00",
"status": "failed",
"id": "f4107e90f98447978036383f6754325e",
"additional_id": "23290726",
"settlement_amount": null
},
{
"method": "credit",
"method_type": "credit",
"amount": "120000.00",
"timestamp": "2026-11-10T10:21:40+00:00",
"status": "success",
"id": "A1B2C3D4-E5F6-47A8-9B0C-1D2E3F4A5B6C",
"additional_id": "884201",
"settlement_amount": "106800.00",
"payment_method_metadata": {
"loan_term": 12
}
}
],
"customer": {
"email": "client@example.com",
"phone": "+79001234567"
}
}
Invoice not found (404 Not Found) — invalid ID, or the invoice was created from another link and the request was made with this link's key.
# Response fields
| Field | Description |
|---|---|
invoice_id | Invoice ID (paymentId) |
created_at | Invoice creation date, ISO 8601 |
order_id | Order number |
amount | Invoice amount |
currency | Currency, RUB |
invoice_status | Invoice status, see Statuses |
total_paid | How much has been paid by all operations |
remaining_amount | How much remains to be paid |
payment_breakdown | All invoice operations in order of creation, including failed ones |
payment_breakdown[].method | Method: card, card2, credit, sber, dolki |
payment_breakdown[].method_type | Type: cash — cards and SBP, credit — loans and installments, bnpl — Sber and Dolki |
payment_breakdown[].amount | Paid by this operation. For Dolki, it increases as the parts are paid |
payment_breakdown[].timestamp | Operation creation time |
payment_breakdown[].status | Operation status, see Statuses |
payment_breakdown[].id | Operation ID. What this ID is for each method is described on the payment methods pages |
payment_breakdown[].additional_id | Additional ID: for cards — ID in processing, for loans — bank offer ID |
payment_breakdown[].settlement_amount | Amount to be transferred to you, net of the fee. Cards — after the fee is calculated, null until then. Loans — according to the selected offer. Dolki — amount minus 7%. Sber — null |
payment_breakdown[].payment_method_metadata.loan_term | Loans only: term in months |
customer.email, customer.phone | Customer contacts |
# Statuses
# Invoice statuses
| Status | Meaning |
|---|---|
pending | The invoice has been created, no payments yet |
partially_paid | Part of the amount has been paid: for example, the first Dolki part or part by card |
paid | The invoice has been paid in full. Only this status means that the order can be fulfilled |
cancelled | The invoice was closed without payment. Currently, invoices with only the loan method enabled are closed this way if the banks finally decline |
# Operation statuses
| Status | Meaning |
|---|---|
processing | Payment, application review, or signing is in progress; for Dolki — parts are being paid on schedule |
success | The payment succeeded, the loan was signed, or Dolki were fully repaid |
failed | Declined by the bank or payment system, cancelled by the customer, or the application was rejected |
How statuses change for each method is described on the pages for cards, installments, Sber, and Dolki.
NOTE!
Decide whether to fulfill the order based on the invoice's invoice_status, not the status of an individual operation. One invoice can be closed with several operations, and failed attempts remain in payment_breakdown.
# Transaction list
GET https://secure-app.mandarin.io/api/v1/public/invoice-transactions/
An end-to-end list of operations for the payment link's invoices — for reconciliation and export to an accounting system. Only operations for invoices of the link the API key is tied to are returned.
# Parameters
| Parameter | Description |
|---|---|
invoice_id | Operations of a single invoice |
type, type__in | Method: card, sbp, credit, sber, dolki. Several — comma-separated: type__in=card,credit |
method_type, method_type__in | Type: cash, credit, bnpl |
status, status__in | Operation status, for example success, failed |
date_from, date_to | Period by operation creation date, ISO 8601 |
customer_email, customer_phone | Customer contacts, exact match |
limit_to | Page size, 10 by default |
cursor | Cursor of the next or previous page from the response |
curl --request GET \
--url 'https://secure-app.mandarin.io/api/v1/public/invoice-transactions/?type__in=credit,dolki&date_from=2026-11-01T00:00:00Z&limit_to=50' \
--header 'X-API-Key: {{api_key}}'
Response (200 OK)
{
"cursor": {
"count": 1,
"prev": null,
"total": 1,
"next": null
},
"transactions": [
{
"method": "dolki",
"method_type": "bnpl",
"amount": "30000.00",
"timestamp": "2026-11-05T08:02:11+00:00",
"status": "processing",
"id": "7c1e4b0a-3d2f-4e5a-9b8c-0f1e2d3c4b5a",
"additional_id": "51234",
"settlement_amount": "27900.00",
"invoice_id": "0b6f3a1e-8c2d-4f7a-9e1b-2c3d4e5f6a7b",
"payment_link_id": "2d28e8bf-0d60-45ca-b8b4-172820086117",
"order_id": "ORDER-000119",
"customer": {
"email": "client@example.com",
"phone": "+79001234567"
}
}
]
}
Operation fields are the same as in payment_breakdown, plus the invoice context: invoice_id, payment_link_id, order_id, customer. For loans, metadata.credit_term is added — the term in months. For Sber — metadata.order_amount: the application amount while it is being processed and amount is 0.
# Webhooks
If callbacks are enabled on the payment link, Mandarin sends a POST request to the specified URL. The body is JSON, the same as the invoice status response.
# When it is sent
- when the invoice is created (
invoice_status: pending); - on every invoice status change;
- on every change of the paid amount — for example, after the next Dolki part is paid;
- when an operation completes successfully or unsuccessfully — even if the invoice status has not changed (for example, the customer was declined a loan and went on to pay by card).
Repeated deliveries of the same event are possible. Process webhooks idempotently: rely on invoice_id, invoice_status, and total_paid, not on the fact of the notification itself.
# Webhook response
Respond with any 2xx code within 10 seconds. If the response is different or there is no response, Mandarin retries the delivery: after 1 minute, then with the interval doubling (2, 4, 8 minutes, etc.), up to 10 retries in total.
SECURITY
The webhook is not signed. Before fulfilling the order, confirm the status with a check-state request using your API key.
# Refunds
| Method | How to refund |
|---|---|
| Cards | In the personal account or via the payment cancellation API, see Bank cards |
| Loans and installments | Through Mandarin's support based on the customer's request, see Installments and loans |
| SBP, Sber, Dolki | Contact your manager or the Support Service (opens new window) |