# 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:

  1. Your system creates an invoice → receives paymentId.
  2. Redirects the customer to https://secure-app.mandarin.io/payment/{paymentId}.
  3. The customer chooses a method and pays or submits an application.
  4. Mandarin sends a webhook on every invoice change.
  5. 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)