# Setup and authorization
An API integration is always tied to a payment link. The link sets the default settings for all invoices you create through it: page design, payment methods, installment terms, receipts, and redirects. Some of these settings can be overridden in the request for a specific invoice.
# Step 1. Create a payment link
In the personal account, open Links («Ссылки») → New link («Новая ссылка») and fill out three tabs:
- Cart and visual design («Корзина и визуальное оформление») — title, description, logo, link to your offer. You can leave the cart empty if you will pass the items via the API.
- Payment methods («Способы оплаты») — enable all methods that may be needed in invoices created from this link. In the API, you can select a subset of them for a specific invoice, but not a method that is not configured on the link. For cards and loans, select a project; for loans, also select products and terms.
- Completion and integration («Завершение и интеграция») — becomes available after the link is created. Redirects and integration are configured here.
A detailed guide to setting up the link is available in the knowledge base (opens new window).
# Step 2. Enable integration and create an API key
On the Completion and integration tab, in the API integration («Интеграция через API») block:
- Enable acceptance via the API.
- Create an API key and give it to your developer. The key works only for this link.
- Copy the link ID — this is the value of the
payment_options_idparameter. It is shown in the link page URL:https://secure-app.mandarin.io/dashboard/invoices/links/2d28e8bf-0d60-45ca-b8b4-172820086117→2d28e8bf-0d60-45ca-b8b4-172820086117
NOTE!
If the integration is disabled on the link or the key is deactivated, requests are rejected with a 401 error.
# Step 3. Set up the webhook
In the same block, enable Send callbacks (Webhook) («Отправлять колбэки (Webhook)») and specify your handler URL. Notifications about every invoice change will be sent to it. The format and retry rules are described in Webhooks.
# Endpoints
| Method | URL |
|---|---|
| Invoice creation | POST https://secure-app.mandarin.io/api/v1/public/invoices/ |
| Invoice status | GET https://secure-app.mandarin.io/api/v1/public/invoices/{invoice_id}/check-state/ |
| Transaction list | GET https://secure-app.mandarin.io/api/v1/public/invoice-transactions/ |
| Customer payment page | https://secure-app.mandarin.io/payment/{invoice_id} |
# Authorization
Pass the payment link's API key in the X-API-Key header:
X-API-Key: 3f2b1c9e-4a7d-4e2b-9c1a-8d5e6f7a8b9c
The key grants access only to invoices of its own payment link: creating invoices from it, requesting their status, and the transaction list. Invoices of your company's other links are not visible with this key.
SECURITY
Store the API key only on the server. Do not pass it to a browser or mobile app.
← Shares (Dolki) API →