# Unified Payment Form Integration
# Entry Points
Production environment for authorization: https://accounts.mandarinbank.com/ (opens new window) Production environment for requests: https://api.psp.io/ (opens new window)
# Request Authentication
Each request must be authenticated with an access token obtained in accordance with the OAuth 2.0 protocol for applications. The token is valid for 36,000 seconds (10 hours). If it expires, the token must be requested again.
Please contact Support (opens new window) to obtain your client_id and client_secret to obtain an access_token.
Request to obtain a token
Includes mandatory form-data parameters that are passed in the request body (the application.client_id and application.client_secret parameters are constant across applications and are stored client-side).
| Parameter | Description | Example |
|---|---|---|
| grant_type | Authorization grant (always equal to client_credentials). | client_credentials |
| client_id | Client ID (equal to the application.client_id value provided by Mandarin). | VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n |
| client_secret | The client secret key (equal to the application.client_secret value provided by Mandarin). | uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7 |
| scope | The requested scopes (access areas): for example, secure_app_client_payment_invoices.write - creating and editing invoices. You can request any list of scopes (separated by a space), and the response will return the list of requested scopes that can be provided for this application. | secure_app_client_payment_invoices.write |
Example request:
curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqUGP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=secure_app_client_payment_invoices.write'
Response:
| Parameter | Description | Example |
|---|---|---|
| access_token | Token (access key). | VnuxZiW14mXBedDeZO7d W7GBmzPxMn |
| expires_in | Token expiration date (in seconds). Always equal to 36,000 seconds (10 hours). | 36000 |
| token_type | Token type (always equal to Bearer). | Bearer |
| scope | Allowed scopes: for example, secure_app_client_payment_invoices.write - creating and editing invoices. You can request any list of scopes (separated by a space), and the response will return the list of requested scopes that can be provided for this application. | secure_app_client_payment_invoices.write |
{
"access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
"expires_in": 36000,
"token_type": "Bearer",
"scope": "scope=secure_app_client_payment_invoices.write"
}
Token Usage
Specified in the headers of each request, in the Authorization field, after the reserved word Bearer.
Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn
# Invoice Creation
This method is used to create an invoice that the client can pay through the standard Mandarin payment page. After successful invoice creation, the API returns a paymentId, which is used to generate a payment link.
Method: POST https://secure-app.mandarin.io/api/v1/public/invoices/
# Authorization
A Bearer token is used to call the method:
Authorization: Bearer {token}
# Request Parameters
| Parameter | Required | Type | Description |
|---|---|---|---|
payment_options_id | Yes | string | Payment link ID from your Mandarin account. Defines the project and payment settings. |
order | No | object | Order details |
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 number. If not specified, it will be requested on the payment page |
urls | No | object | Redirect URL |
urls.success_redirect | No | string | Redirect URL after successful payment |
urls.fail_redirect | No | string | Redirect URL 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 | 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 productsor services |
cart.items[].quantity | Yes | integer | Quantity of product units |
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 can I get it?
payment_options_id is the ID of the payment link created in your Mandarin account. It determines the project and settings for the invoice.
How to get payment_options_id:
- Go to the "Invoices / Links" section in your Mandarin account.
- Find the link you want to use for invoicing via the API.
- Open its settings – you'll 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-172820086117is yourpayment_options_id.
# Request example
curl --location 'https://secure-app.mandarin.io/api/v1/public/invoices/' \
--header 'Authorization: Bearer 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"]
}'
# Example of a successful response
{
"success": true,
"paymentId": "8762f870-1790-4aaf-a8a3-994c548836fd",
"message": "Invoice created successfully"
}
# 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