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

In the personal account, open Links («Ссылки») → New link («Новая ссылка») and fill out three tabs:

  1. 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.
  2. 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.
  3. 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:

  1. Enable acceptance via the API.
  2. Create an API key and give it to your developer. The key works only for this link.
  3. Copy the link ID — this is the value of the payment_options_id parameter. 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.