Интеграция API

Создание платежа

Инициирование новой транзакции

Создание платёжной ссылки

Для создания новой платёжной ссылки (выставления счета покупателю) отправьте HTTP POST-запрос. Поддерживается два эндпоинта в зависимости от используемого метода авторизации:

HTTP Запрос

1. По API-ключу (для взаимодействия сервер-сервер)

POST /merchant/v1/payment-links

2. По JWT-токену (для запросов из дашборда)

POST /api/v1/payment-links

Параметры запроса (JSON body)

Поле	Тип	Обязательное	Описание
`shop_id`	string (UUID)	Да	Идентификатор вашего магазина. Магазин должен быть в статусе `approved` (пройти модерацию).
`amount`	number \| string	Да	Сумма к оплате в рублях. Должна быть строго больше 0 и содержать не более 2 знаков после запятой. Допускается передавать как число, так и строку (например, `1000` или `"1000.00"`).
`order_id`	string	Нет	Ваш уникальный внешний ID заказа (будет передан обратно в вебхуке `payment.succeeded`).
`description`	string	Нет	Описание товара или услуги. Покупатель увидит его на платежной странице.
`expires_in_minutes`	integer	Нет	Срок жизни платёжной ссылки в минутах. Минимальное значение — `1`.

Пример запроса (API-ключ)

curl -X POST https://api.datagio.finance/merchant/v1/payment-links \
  -H "X-API-Key: pk_live_your_public_key" \
  -H "X-API-Secret: sk_live_your_secret_key" \
  -H "Content-Type: application/json" \
  -d '{
    "shop_id": "b79ffcef-5f6e-4adf-aa5f-e885b4d282d9",
    "amount": 1000,
    "order_id": "ORDER-12345",
    "description": "Оплата заказа №12345",
    "expires_in_minutes": 60
  }'

Ответ API (201 Created)

При успешном создании возвращается объект платёжной ссылки с добавленным полем checkout_url для перенаправления покупателя.

Поля ответа (JSON)

Поле	Тип	Описание
`id`	string (UUID)	Уникальный идентификатор созданной платёжной ссылки.
`shop_id`	string (UUID)	Идентификатор магазина.
`merchant_id`	string (UUID)	Идентификатор мерчанта (владельца магазина).
`order_id`	string \| null	Внешний ID заказа.
`description`	string \| null	Описание платежа.
`currency`	string	Валюта платежа (всегда `RUB`).
`amount`	string	Исходная сумма платежа, ₽ (всегда строка с 2 знаками после точки, например `"1000.00"`).
`fee_percent_bp`	integer	Размер комиссии платформы в базисных пунктах (100 = 1%).
`fee_payer`	string	Кто оплачивает комиссию: `merchant` (продавец), `client` (покупатель) или `split` (разделено).
`payer_amount`	string	Сумма, которую должен оплатить покупатель с учетом комиссии, ₽.
`merchant_credit`	string	Сумма к зачислению на баланс мерчанта после вычета комиссии, ₽.
`platform_revenue`	string	Доход платформы (комиссия) от этого платежа, ₽.
`status`	string	Статус ссылки: `pending` (ожидает оплаты), `paid` (оплачена), `expired` (истекла), `canceled` (отменена), `failed` (ошибка).
`checkout_url`	string (URI)	Ссылка на страницу оплаты (СБП, крипта) — перенаправьте покупателя на этот URL.
`expires_at`	string \| null	Время истечения срока действия ссылки (ISO 8601).
`paid_at`	string \| null	Время оплаты ссылки (ISO 8601).
`created_at`	string	Время создания ссылки (ISO 8601).
`updated_at`	string	Время последнего изменения статуса (ISO 8601).
`gateway_provider`	string \| null	Имя шлюза, который обрабатывает транзакцию (например, `paritypay`). Заполняется при выборе метода оплаты на странице.
`gateway_payment_id`	string \| null	ID платежа во внешней платежной системе.
`to_currency`	string \| null	Целевая валюта оплаты (например, `USDT`, `BTC`, `RUB`).
`network`	string \| null	Сеть блокчейна (для крипты) или `"СБП"` (для фиата).
`deposit_address`	string \| null	Адрес депозита крипты или ссылка СБП (НСПК).
`payer_currency`	string \| null	Валюта оплаты покупателя.
`payer_crypto_amount`	string \| null	Точная сумма к отправке в криптовалюте.
`qr`	string \| null	QR-код для оплаты (data URL в формате base64).

Пример ответа

{
  "id": "9c0526fe-0e45-423d-91ca-368e98b8ea96",
  "shop_id": "b79ffcef-5f6e-4adf-aa5f-e885b4d282d9",
  "merchant_id": "c80ffcef-5f6e-4adf-aa5f-e885b4d282d9",
  "order_id": "ORDER-12345",
  "description": "Оплата заказа №12345",
  "currency": "RUB",
  "amount": "1000.00",
  "fee_percent_bp": 100,
  "fee_payer": "merchant",
  "payer_amount": "1000.00",
  "merchant_credit": "990.00",
  "platform_revenue": "10.00",
  "status": "pending",
  "gateway_provider": null,
  "gateway_payment_id": null,
  "to_currency": null,
  "network": null,
  "deposit_address": null,
  "payer_currency": null,
  "payer_crypto_amount": null,
  "qr": null,
  "expires_at": "2026-07-23T18:50:53Z",
  "paid_at": null,
  "created_at": "2026-07-23T17:50:53Z",
  "updated_at": "2026-07-23T17:50:53Z",
  "checkout_url": "https://datagio.finance/checkout/9c0526fe-0e45-423d-91ca-368e98b8ea96"
}

Ошибки API

В случае ошибок при создании платёжной ссылки возвращаются следующие коды ответов:

400 Bad Request (validation_error): Неверные параметры запроса (например, не передан shop_id, или amount меньше или равен нулю, либо содержит больше двух знаков после запятой).
401 Unauthorized (unauthorized): Неверный API-ключ или JWT-токен.
403 Forbidden (forbidden): У вас нет доступа к указанному магазину (shop_id).
404 Not Found (not_found): Указанный магазин не существует.
422 Unprocessable Entity (shop_not_approved): Магазин еще не прошел модерацию и имеет статус, отличный от approved.

Пример тела ошибки

{
  "error": "shop_not_approved",
  "message": "shop is not approved"
}

Навигация

Разделы документации