Справочник методов
Адрес, поля ответа и отказы каждой выпущенной ручки API.
Справочник собирается из схем сервера, а стенд сверяет с ними отказы, адреса и ответы работающего сервера там, где их можно вызвать без провайдера.
Общее для всех ручек
- Базовый адрес:
https://api.thetarget.cc. - Вход по ключу API: Авторизация.
- Форма отказа и общие отказы: Формат ошибок.
- Предел частоты и запрет кеширования: Ограничения.
Проверить ключ
GET/api/v1/meс 12.11.2026
Возвращает мерчанта, контур и открытую часть ключа, которым сделан запрос. Ничего не меняет. С этого запроса начинают интеграцию: он показывает, что ключ принят и к какому контуру относится.
- Секрет ключа в ответе не возвращается никогда.
- Названия, которым администратор пометил ключ у себя в консоли, в ответе нет.
Запрос
curl -sS https://api.thetarget.cc/api/v1/me \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
merchant | объект | всегда | Мерчант, которому выдан ключ. |
merchant.code | строка | всегда | Код мерчанта. Задаётся при заведении и не меняется. |
merchant.name | строка | всегда | Название мерчанта, как оно записано у нас. |
environment | строкаLIVE TEST | всегда | Контур ключа. Все запросы этим ключом исполняются в этом контуре. |
key | объект | всегда | Ключ, которым сделан запрос. |
key.keyId | строка | всегда | Открытая часть ключа. Не секрет: по ней ключ называют в переписке с поддержкой. |
key.expiresAt | строка, момент времени ISO 8601или null | всегда | Когда ключ перестанет приниматься, время UTC. null: срок не задан. |
{
"merchant": {
"code": "example-shop",
"name": "Example Shop"
},
"environment": "TEST",
"key": {
"keyId": "ak_test_examplekey000001",
"expiresAt": "2027-02-10T00:00:00.000Z"
}
}Отказы
Своих отказов у ручки нет, возможны только общие для всех ручек.
Список сервисов
GET/api/v1/servicesс 12.11.2026
Возвращает сервисы, которыми мерчант может принять платёж в контуре ключа: способ оплаты, валюту, границы суммы, поля плательщика и комиссию. Ничего не меняет.
- В список попадают только сервисы, готовые к работе целиком. Сервис, которому чего-то не хватает на нашей стороне, в ответе отсутствует, а не помечен.
- Список зависит от контура ключа: у тестового и боевого ключа одного мерчанта он может различаться.
- Суммы приходят строками в минорных единицах валюты сервиса. Чтобы показать сумму человеку, её делят на
minorUnit. - Список меняется, когда администратор включает или выключает сервис. Хранить его у себя дольше нескольких минут не стоит.
Запрос
curl -sS https://api.thetarget.cc/api/v1/services \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
environment | строкаLIVE TEST | всегда | Контур ключа. Список собран для него. |
items | массив объектов | всегда | Сервисы мерчанта, готовые к работе прямо сейчас; для приёма платежа годятся только PAYIN. Может быть пустым. |
items[].code | строка | всегда | Код сервиса. Им сервис называют при создании платежа. |
items[].direction | строкаPAYIN PAYOUT | всегда | Направление денег: PAYIN приём, PAYOUT выплата. |
items[].method | объект | всегда | Способ оплаты. |
items[].method.code | строка | всегда | Код способа оплаты. |
items[].method.name | строка | всегда | Название способа оплаты для показа человеку. |
items[].currency | строка | всегда | Валюта сервиса: в ней задаются сумма платежа, границы и твёрдая комиссия. |
items[].network | строкаили null | всегда | Сеть, если у валюты их несколько (криптовалюты). null: сети нет. |
items[].flow | строкаDIRECT REDIRECT REQUISITE HOSTED_FIELDS | всегда | Как проходит оплата: DIRECT данные плательщика передаёт сервер мерчанта, REDIRECT плательщик уходит на страницу провайдера, REQUISITE плательщику выдаётся реквизит (QR, код, счёт), HOSTED_FIELDS плательщик заполняет готовую форму провайдера. |
items[].minorUnit | целое число | всегда | Сколько минорных единиц в одной единице валюты: 100 у BRL, 1 у JPY. |
items[].amount | объект | всегда | Границы суммы. |
items[].amount.minMinor | строкаили null | всегда | Наименьшая сумма платежа в минорных единицах. null: нижней границы нет. |
items[].amount.maxMinor | строкаили null | всегда | Наибольшая сумма платежа в минорных единицах. null: верхней границы нет. |
items[].fields | массив объектов | всегда | Поля плательщика, которые сервис принимает. Порядок тот же, что на форме оплаты. |
items[].fields[].key | строка | всегда | Имя поля. Этим именем поле передаётся при создании платежа. |
items[].fields[].kind | строкаTEXT DIGITS EMAIL PHONE DATE COUNTRY | всегда | Вид значения: TEXT строка, DIGITS только цифры, EMAIL почта, PHONE телефон в формате E.164, DATE дата ГГГГ-ММ-ДД, COUNTRY страна двумя буквами ISO 3166-1. |
items[].fields[].required | логическое | всегда | Обязательно ли поле для этого сервиса. |
items[].fields[].pattern | строкаили null | всегда | Регулярное выражение, которому значение должно соответствовать целиком. null: проверки выражением нет. |
items[].fields[].maxLength | целое число | всегда | Наибольшая длина значения в знаках. |
items[].fee | объект | всегда | Комиссия с мерчанта за платёж этим сервисом. |
items[].fee.type | строкаPERCENT FIXED | всегда | Вид комиссии: PERCENT процент от суммы, FIXED твёрдая сумма. |
items[].fee.percent | строкаили null | всегда | Процент строкой с четырьмя знаками после точки: «1.9000». Заполнен при PERCENT, иначе null. |
items[].fee.amountMinor | строкаили null | всегда | Твёрдая сумма в минорных единицах валюты сервиса. Заполнена при FIXED, иначе null. |
{
"environment": "TEST",
"items": [
{
"code": "pix_brl_requisite",
"direction": "PAYIN",
"method": {
"code": "PIX",
"name": "Pix"
},
"currency": "BRL",
"network": null,
"flow": "REQUISITE",
"minorUnit": 100,
"amount": {
"minMinor": "100",
"maxMinor": "10000000"
},
"fields": [
{
"key": "payer.tax_id",
"kind": "DIGITS",
"required": true,
"pattern": "^(\\d{11}|\\d{14})$",
"maxLength": 14
},
{
"key": "payer.name",
"kind": "TEXT",
"required": false,
"pattern": null,
"maxLength": 128
}
],
"fee": {
"type": "PERCENT",
"percent": "1.9000",
"amountMinor": null
}
},
{
"code": "pix_brl_redirect",
"direction": "PAYIN",
"method": {
"code": "PIX",
"name": "Pix"
},
"currency": "BRL",
"network": null,
"flow": "REDIRECT",
"minorUnit": 100,
"amount": {
"minMinor": "100",
"maxMinor": "10000000"
},
"fields": [
{
"key": "payer.tax_id",
"kind": "DIGITS",
"required": true,
"pattern": "^(\\d{11}|\\d{14})$",
"maxLength": 14
},
{
"key": "payer.name",
"kind": "TEXT",
"required": false,
"pattern": null,
"maxLength": 128
}
],
"fee": {
"type": "PERCENT",
"percent": "1.9000",
"amountMinor": null
}
},
{
"code": "boleto_brl_requisite",
"direction": "PAYIN",
"method": {
"code": "BOLETO",
"name": "Boleto bancário"
},
"currency": "BRL",
"network": null,
"flow": "REQUISITE",
"minorUnit": 100,
"amount": {
"minMinor": "500",
"maxMinor": "1000000"
},
"fields": [
{
"key": "payer.tax_id",
"kind": "DIGITS",
"required": true,
"pattern": "^(\\d{11}|\\d{14})$",
"maxLength": 14
},
{
"key": "payer.name",
"kind": "TEXT",
"required": true,
"pattern": null,
"maxLength": 128
},
{
"key": "payer.email",
"kind": "EMAIL",
"required": false,
"pattern": null,
"maxLength": 254
}
],
"fee": {
"type": "FIXED",
"percent": null,
"amountMinor": "250"
}
}
]
}Отказы
Своих отказов у ручки нет, возможны только общие для всех ручек.
Создать платёж
POST/api/v1/paymentsс 13.11.2026
Создаёт платёж и проводит первую попытку у провайдера: сразу, а при fieldsOnPage после того, как плательщик отправит поля на странице оплаты. В ответе платёж: номер, статус и куда отправить плательщика.
- Заголовок
Idempotency-Keyделает повтор безопасным: Повтор запроса. - Новый платёж получает 201. Повтор получает тот же платёж в нынешнем виде, код 200 или 201 и заголовок
Idempotency-Replayed: true. - Боевой приём закрыт: боевым ключом платёж не создаётся, отказ 403 с правилом
live_intake_closed.
Запрос
curl -sS -X POST https://api.thetarget.cc/api/v1/payments \
-H "Authorization: Bearer $TARGET_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 5f0c2b9e-8d41-4a7c-9e2f-3b6d1a4c8e07" \
-d '{
"reference": "order-1001",
"service": "pix_brl_redirect",
"amountMinor": "1250",
"customer": {
"id": "player-42",
"country": "BR"
},
"fields": {
"payer.tax_id": "12345678909",
"payer.name": "Maria Silva"
},
"returnUrl": "https://shop.example/return/order-1001",
"metadata": {
"cartId": "c-77"
}
}'Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
| Поле | Вид | Обязательно | Что это |
|---|---|---|---|
reference | строка | да | Номер заказа у вас: от 1 до 128 знаков, без пробелов по краям и невидимых знаков. Второй платёж с тем же номером в контуре не создаётся. |
service | строка | да | Код сервиса из списка сервисов. Сервис задаёт валюту, способ оплаты и поля плательщика. |
amountMinor | строка | да | Сумма строкой: целое число минорных единиц валюты сервиса, до 15 цифр. Число JSON вместо строки это отказ. |
customer | объект | да | Клиент, который платит. |
customer.id | строка | да | Номер клиента у вас: от 1 до 128 знаков, без пробелов по краям и невидимых знаков. |
customer.country | строка | нет | Страна клиента: код ISO 3166-1 из двух заглавных букв (GB, а не UK). |
fields | объект с произвольными ключами | нет | Поля плательщика по ключам из списка сервисов, например payer.tax_id. Поле, которого у сервиса нет, это отказ. |
returnUrl | строка | нет | Куда вернуть плательщика после оплаты: https до 1024 знаков, без имени пользователя и пароля; при странице оплаты источник из списка мерчанта. В тестовом контуре можно и http: Страница оплаты. |
callbackUrl | строка | нет | Адрес уведомлений этого объекта (callback_url Corefy): уведомления о нём уходят сюда вместо адреса контура, подписанные секретом контура. https до 2048 знаков, в тестовом контуре можно http; полное имя узла в интернете; порт по умолчанию, 443, 8443, 80 или 8080; без имени пользователя и пароля. Нужен секрет контура: Адрес в запросе. |
fieldsOnPage | логическое | нет | true: поля плательщика собирает страница оплаты, fields тогда не передаётся. Платёж ждёт полей в CREATED, первая попытка начинается, когда плательщик их отправит. Заблокированный клиент сразу получает REJECTED: Страница оплаты. |
metadata | объект с произвольными ключами | нет | Ваши метки: объект JSON до 4096 знаков в записи и до 16 уровней вложенности. Возвращаются в ответе как есть. В тестовом контуре поле sandbox задаёт исход платежа: Тестовые данные. |
Ответ 201
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер платежа: pr_ и 22 знака. По нему платёж читают. |
reference | строка | всегда | Номер заказа, присланный при создании. |
service | строкаили null | всегда | Код сервиса, которым создан платёж. |
environment | строкаTEST LIVE | всегда | Контур платежа: контур ключа, которым он создан. |
status | строкаCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | всегда | Статус платежа: Статусы платежа. |
reason | строкаили null | всегда | Причина статуса кодом; null, когда называть нечего: Причины. |
inReview | логическое | всегда | Исход ещё решается на нашей стороне: доспросом провайдера или человеком. Пока true, по платежу не зачисляют. |
amountMinor | строка | всегда | Запрошенная сумма строкой, в минорных единицах валюты платежа. |
currency | строка | всегда | Валюта платежа: валюта сервиса. |
network | строкаили null | всегда | Сеть, если у валюты их несколько. null: сети нет. |
paidMinor | строкаили null | всегда | Сумма, которую подтвердил провайдер, в минорных единицах валюты платежа. Зачисляют её и только при SUCCEEDED. null: денег не подтверждено. |
feeMinor | строкаили null | всегда | Комиссия с мерчанта за платёж в минорных единицах валюты платежа, посчитанная при создании. |
refundedMinor | строка | всегда | Сколько возвращено плательщику успешными возвратами, в минорных единицах валюты платежа. Статус платежа от возвратов не меняется: Возвраты. |
action | объектили null | всегда | Что сделать плательщику; есть, только пока платёж его ждёт: Что показать плательщику. null: показывать нечего, ждать по статусу. |
action.type | строкаredirect requisite | всегда | redirect: отправить плательщика по адресу url; requisite: показать реквизит. |
action.url | строка | не всегда | Куда отправить плательщика: страница провайдера или, при fieldsOnPage, страница оплаты. Только при redirect. |
action.requisite | объект | не всегда | Реквизит для оплаты. Только при requisite: Реквизит. |
action.requisite.presentation | строкаqr transfer voucher | всегда | Как показать: qr код для сканирования и копирования, transfer перевод по реквизитам, voucher номер для оплаты в кассе. |
action.requisite.payload | строка | всегда | Главная строка реквизита: содержимое кода, номер счёта или ваучера. |
action.requisite.fields | объект с произвольными ключами | всегда | Подписи для экрана в порядке показа: ключ заглавными это имя счёта (CLABE, IBAN, ALIAS), строчные code, account, holder, bank, reference. Может быть пустым. |
action.requisite.payAmountMinor | строка | всегда | Сколько перевести, в минорных единицах payCurrency. |
action.requisite.payCurrency | строка | всегда | Валюта суммы к оплате. При конвертации она не равна валюте платежа. |
action.requisite.payAmountChanged | логическое | всегда | true: провайдер попросил сумму, отличную от суммы платежа; плательщику пишут «переведите ровно эту сумму». |
action.expiresAt | строкаили null | не всегда | До какого момента действует реквизит, время UTC. null: срок не назван. Только при requisite. |
customer | объект | всегда | Клиент, который платит. |
customer.id | строка | всегда | Номер клиента, присланный при создании. |
returnUrl | строкаили null | всегда | Адрес возврата плательщика в той записи, в какой его понял сервер. null: не задан. |
callbackUrl | строкаили null | всегда | Адрес уведомлений платежа в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда платёж создан, время UTC. |
expiresAt | строка, момент времени ISO 8601или null | всегда | Срок оплаты, время UTC: Срок оплаты. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда платёж получил финальный статус, время UTC. null: ещё не получил. |
pageUrl | строкаили null | всегда | Ссылка на страницу оплаты этого платежа: туда можно отправить плательщика вместо своей формы. null: страницы нет или срок ссылки вышел: Страница оплаты. |
{
"id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "order-1001",
"service": "pix_brl_redirect",
"environment": "TEST",
"status": "AWAITING_CUSTOMER",
"reason": null,
"inReview": false,
"amountMinor": "1250",
"currency": "BRL",
"network": null,
"paidMinor": null,
"feeMinor": "24",
"refundedMinor": "0",
"action": {
"type": "redirect",
"url": "https://pay.provider.example/checkout/7Hq2xW"
},
"customer": {
"id": "player-42"
},
"returnUrl": "https://shop.example/return/order-1001",
"callbackUrl": null,
"metadata": {
"cartId": "c-77"
},
"createdAt": "2026-11-13T09:15:02.481Z",
"expiresAt": "2026-11-13T09:45:02.481Z",
"finalizedAt": null,
"pageUrl": "https://pay.example/#u30M8e5ErKC8wPc5t3uTXxOuwv1Tf1wp3t2IPdQpuoNsmxnLlntWPZ2Ws0E"
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | validation_failed | Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. Исправить тело по таблице полей. |
Пример ответа | ||
| 400 | validation_failed | Значение не прошло проверку:
Исправить значение, которое называет |
Пример ответа | ||
| 400 | bad_amount |
Передать сумму строкой в минорных единицах: «1250», а не «12.50». |
Пример ответа | ||
| 400 | bad_amount | Сумма по форме верна, но сервис её не принимает.
Передать сумму в границах сервиса и больше его комиссии. |
Пример ответа | ||
| 403 | forbiddenlive_intake_closed | Платёж создаётся боевым ключом, а боевой приём закрыт. Проверяется раньше тела запроса. Создавать платежи тестовым ключом. |
Пример ответа | ||
| 409 | conflict | Сервисом из запроса платёж сейчас не создать.
Взять сервис из свежего списка сервисов. |
Пример ответа | ||
| 409 | conflictpayment_reference_exists | Платёж с таким Прочитать этот платёж, а не создавать новый. |
Пример ответа | ||
| 409 | conflictrequest_in_progress | Запрос с этим ключом повтора ещё выполняется. Повторить через несколько секунд с тем же ключом и тем же телом. |
Пример ответа | ||
| 409 | conflictidempotency_key_reused | Ключ повтора уже использован другим запросом: с другим телом или другой операцией. Повтор отправляет тот же запрос; новая операция получает новый ключ. |
Пример ответа | ||
| 409 | conflictidempotency_key_unverifiable | Ключ повтора записан так, что сверить с ним тело на нашей стороне нечем. Сообщить поддержке ключ повтора и время запроса. |
Пример ответа | ||
| 409 | conflict | Параллельный запрос в тот же миг изменил те же данные, например клиента. Платёж не создан; Повторить тот же запрос. |
Пример ответа | ||
| 409 | keyring_unavailable | На нашей стороне недоступны ключи шифрования, которыми записываются ключ повтора и данные плательщика. Запрос не исполнен. Повторить позже. Если повторяется, сообщить поддержке время запроса. |
Пример ответа | ||
| 422 | identifier_invalid | Данные плательщика не прошли проверку, например контрольную сумму налогового номера. Исправить значение поля. |
Пример ответа | ||
| 409 | conflict | Поля плательщика страницей оплаты сейчас не собрать.
Собрать поля своей формой и передать в |
Пример ответа | ||
| 409 | conflictcallback_secret_missing | Передан Выпустить секрет: |
Пример ответа | ||
| 503 | dependency_unavailable | Приём временно не работает; платёж не создан.
Повторить позже с тем же ключом повтора. |
Пример ответа | ||
Найти платёж по номеру заказа
GET/api/v1/paymentsс 17.11.2026
Возвращает платёж с этим номером заказа в контуре ключа: ноль или одна запись. Так находят платёж, ответ на создание которого не дошёл, а ключа повтора не было.
- Без
referenceадрес отвечает отказом 501: списка платежей нет. - Предел частоты общий с чтением платежа по номеру.
Запрос
curl -sS 'https://api.thetarget.cc/api/v1/payments?reference=order-1001' \
-H "Authorization: Bearer $TARGET_API_KEY"| Поле | Вид | Обязательно | Что это |
|---|---|---|---|
reference | строка | да | Номер заказа, как он передан при создании, закодированный как часть адреса: знаки +, &, # и пробел иначе меняют номер. Без параметра адрес отвечает отказом 501. |
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
items | массив объектов | всегда | Платёж с этим номером заказа, ноль или один. Пусто: в контуре ключа такого заказа нет. |
items[].id | строка | всегда | Номер платежа: pr_ и 22 знака. По нему платёж читают. |
items[].reference | строка | всегда | Номер заказа, присланный при создании. |
items[].service | строкаили null | всегда | Код сервиса, которым создан платёж. |
items[].environment | строкаTEST LIVE | всегда | Контур платежа: контур ключа, которым он создан. |
items[].status | строкаCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | всегда | Статус платежа: Статусы платежа. |
items[].reason | строкаили null | всегда | Причина статуса кодом; null, когда называть нечего: Причины. |
items[].inReview | логическое | всегда | Исход ещё решается на нашей стороне: доспросом провайдера или человеком. Пока true, по платежу не зачисляют. |
items[].amountMinor | строка | всегда | Запрошенная сумма строкой, в минорных единицах валюты платежа. |
items[].currency | строка | всегда | Валюта платежа: валюта сервиса. |
items[].network | строкаили null | всегда | Сеть, если у валюты их несколько. null: сети нет. |
items[].paidMinor | строкаили null | всегда | Сумма, которую подтвердил провайдер, в минорных единицах валюты платежа. Зачисляют её и только при SUCCEEDED. null: денег не подтверждено. |
items[].feeMinor | строкаили null | всегда | Комиссия с мерчанта за платёж в минорных единицах валюты платежа, посчитанная при создании. |
items[].refundedMinor | строка | всегда | Сколько возвращено плательщику успешными возвратами, в минорных единицах валюты платежа. Статус платежа от возвратов не меняется: Возвраты. |
items[].action | объектили null | всегда | Что сделать плательщику; есть, только пока платёж его ждёт: Что показать плательщику. null: показывать нечего, ждать по статусу. |
items[].action.type | строкаredirect requisite | всегда | redirect: отправить плательщика по адресу url; requisite: показать реквизит. |
items[].action.url | строка | не всегда | Куда отправить плательщика: страница провайдера или, при fieldsOnPage, страница оплаты. Только при redirect. |
items[].action.requisite | объект | не всегда | Реквизит для оплаты. Только при requisite: Реквизит. |
items[].action.requisite.presentation | строкаqr transfer voucher | всегда | Как показать: qr код для сканирования и копирования, transfer перевод по реквизитам, voucher номер для оплаты в кассе. |
items[].action.requisite.payload | строка | всегда | Главная строка реквизита: содержимое кода, номер счёта или ваучера. |
items[].action.requisite.fields | объект с произвольными ключами | всегда | Подписи для экрана в порядке показа: ключ заглавными это имя счёта (CLABE, IBAN, ALIAS), строчные code, account, holder, bank, reference. Может быть пустым. |
items[].action.requisite.payAmountMinor | строка | всегда | Сколько перевести, в минорных единицах payCurrency. |
items[].action.requisite.payCurrency | строка | всегда | Валюта суммы к оплате. При конвертации она не равна валюте платежа. |
items[].action.requisite.payAmountChanged | логическое | всегда | true: провайдер попросил сумму, отличную от суммы платежа; плательщику пишут «переведите ровно эту сумму». |
items[].action.expiresAt | строкаили null | не всегда | До какого момента действует реквизит, время UTC. null: срок не назван. Только при requisite. |
items[].customer | объект | всегда | Клиент, который платит. |
items[].customer.id | строка | всегда | Номер клиента, присланный при создании. |
items[].returnUrl | строкаили null | всегда | Адрес возврата плательщика в той записи, в какой его понял сервер. null: не задан. |
items[].callbackUrl | строкаили null | всегда | Адрес уведомлений платежа в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
items[].metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
items[].createdAt | строка, момент времени ISO 8601 | всегда | Когда платёж создан, время UTC. |
items[].expiresAt | строка, момент времени ISO 8601или null | всегда | Срок оплаты, время UTC: Срок оплаты. |
items[].finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда платёж получил финальный статус, время UTC. null: ещё не получил. |
items[].pageUrl | строкаили null | всегда | Ссылка на страницу оплаты этого платежа: туда можно отправить плательщика вместо своей формы. null: страницы нет или срок ссылки вышел: Страница оплаты. |
{
"items": [
{
"id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "order-1001",
"service": "pix_brl_redirect",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "1250",
"currency": "BRL",
"network": null,
"paidMinor": "1250",
"feeMinor": "24",
"refundedMinor": "500",
"action": null,
"customer": {
"id": "player-42"
},
"returnUrl": "https://shop.example/return/order-1001",
"callbackUrl": null,
"metadata": {
"cartId": "c-77"
},
"createdAt": "2026-11-13T09:15:02.481Z",
"expiresAt": "2026-11-13T09:45:02.481Z",
"finalizedAt": "2026-11-13T09:17:40.112Z",
"pageUrl": null
}
]
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | validation_failed |
Передать один номер заказа. |
Пример ответа | ||
| 400 | validation_failedreference_shape | Номер заказа пуст, длиннее 128 знаков, с пробелами по краям, управляющими или невидимыми знаками. Проверить номер и закодировать его как часть адреса. |
Пример ответа | ||
| 501 | not_implemented | Запрос без Читать платёж по номеру или по номеру заказа. |
Пример ответа | ||
Прочитать платёж
GET/api/v1/payments/:idс 13.11.2026
Возвращает платёж по его номеру в контуре ключа. Ничего не меняет. Так узнают исход платежа, если уведомление не пришло, и сверяют его перед зачислением.
- Чужой платёж, платёж другого контура и номер не по форме дают один и тот же ответ 404.
- У чтения свой предел частоты, отдельный от создания: Ограничения.
Запрос
curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер платежа: pr_ и 22 знака. По нему платёж читают. |
reference | строка | всегда | Номер заказа, присланный при создании. |
service | строкаили null | всегда | Код сервиса, которым создан платёж. |
environment | строкаTEST LIVE | всегда | Контур платежа: контур ключа, которым он создан. |
status | строкаCREATED PROCESSING AWAITING_CUSTOMER SUCCEEDED PARTIALLY_PAID OVERPAID FAILED CANCELLED EXPIRED REJECTED | всегда | Статус платежа: Статусы платежа. |
reason | строкаили null | всегда | Причина статуса кодом; null, когда называть нечего: Причины. |
inReview | логическое | всегда | Исход ещё решается на нашей стороне: доспросом провайдера или человеком. Пока true, по платежу не зачисляют. |
amountMinor | строка | всегда | Запрошенная сумма строкой, в минорных единицах валюты платежа. |
currency | строка | всегда | Валюта платежа: валюта сервиса. |
network | строкаили null | всегда | Сеть, если у валюты их несколько. null: сети нет. |
paidMinor | строкаили null | всегда | Сумма, которую подтвердил провайдер, в минорных единицах валюты платежа. Зачисляют её и только при SUCCEEDED. null: денег не подтверждено. |
feeMinor | строкаили null | всегда | Комиссия с мерчанта за платёж в минорных единицах валюты платежа, посчитанная при создании. |
refundedMinor | строка | всегда | Сколько возвращено плательщику успешными возвратами, в минорных единицах валюты платежа. Статус платежа от возвратов не меняется: Возвраты. |
action | объектили null | всегда | Что сделать плательщику; есть, только пока платёж его ждёт: Что показать плательщику. null: показывать нечего, ждать по статусу. |
action.type | строкаredirect requisite | всегда | redirect: отправить плательщика по адресу url; requisite: показать реквизит. |
action.url | строка | не всегда | Куда отправить плательщика: страница провайдера или, при fieldsOnPage, страница оплаты. Только при redirect. |
action.requisite | объект | не всегда | Реквизит для оплаты. Только при requisite: Реквизит. |
action.requisite.presentation | строкаqr transfer voucher | всегда | Как показать: qr код для сканирования и копирования, transfer перевод по реквизитам, voucher номер для оплаты в кассе. |
action.requisite.payload | строка | всегда | Главная строка реквизита: содержимое кода, номер счёта или ваучера. |
action.requisite.fields | объект с произвольными ключами | всегда | Подписи для экрана в порядке показа: ключ заглавными это имя счёта (CLABE, IBAN, ALIAS), строчные code, account, holder, bank, reference. Может быть пустым. |
action.requisite.payAmountMinor | строка | всегда | Сколько перевести, в минорных единицах payCurrency. |
action.requisite.payCurrency | строка | всегда | Валюта суммы к оплате. При конвертации она не равна валюте платежа. |
action.requisite.payAmountChanged | логическое | всегда | true: провайдер попросил сумму, отличную от суммы платежа; плательщику пишут «переведите ровно эту сумму». |
action.expiresAt | строкаили null | не всегда | До какого момента действует реквизит, время UTC. null: срок не назван. Только при requisite. |
customer | объект | всегда | Клиент, который платит. |
customer.id | строка | всегда | Номер клиента, присланный при создании. |
returnUrl | строкаили null | всегда | Адрес возврата плательщика в той записи, в какой его понял сервер. null: не задан. |
callbackUrl | строкаили null | всегда | Адрес уведомлений платежа в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда платёж создан, время UTC. |
expiresAt | строка, момент времени ISO 8601или null | всегда | Срок оплаты, время UTC: Срок оплаты. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда платёж получил финальный статус, время UTC. null: ещё не получил. |
pageUrl | строкаили null | всегда | Ссылка на страницу оплаты этого платежа: туда можно отправить плательщика вместо своей формы. null: страницы нет или срок ссылки вышел: Страница оплаты. |
{
"id": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "order-1001",
"service": "pix_brl_redirect",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "1250",
"currency": "BRL",
"network": null,
"paidMinor": "1250",
"feeMinor": "24",
"refundedMinor": "500",
"action": null,
"customer": {
"id": "player-42"
},
"returnUrl": "https://shop.example/return/order-1001",
"callbackUrl": null,
"metadata": {
"cartId": "c-77"
},
"createdAt": "2026-11-13T09:15:02.481Z",
"expiresAt": "2026-11-13T09:45:02.481Z",
"finalizedAt": "2026-11-13T09:17:40.112Z",
"pageUrl": null
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 404 | not_found | Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет. Проверить номер и ключ. |
Пример ответа | ||
| 400 | validation_failed | Номер в адресе с негодной кодировкой: после Передавать номер так, как его вернул ответ создания. |
Пример ответа | ||
Создать возврат
POST/api/v1/payments/:id/refundsс 17.11.2026
Возвращает плательщику деньги успешного платежа, целиком или частью. В ответе возврат: номер, статус и признак разбора.
- Заголовок
Idempotency-Keyобязателен. Отказ 409 с правилом, кромеrequest_in_progressиrefund_in_progress, занимает ключ: повтор с тем же ключом получает тот же отказ. - Отказ ключа API, мерчанта или контура при верном секрете (401
api_key_disabled,api_key_revoked,api_key_expired, 403merchant_not_active,environment_closed) тоже занимает ключ повтора: повтор с тем же ключом получает тот же отказ иIdempotency-Replayed: true, даже когда ключ API включат или мерчанта откроют. Отозванный или просроченный ключ API занимает ключ повтора только сутки после конца ключа; позже его 401 ключ не занимает, а записанное по тому же телу он ещё получает повтором. - Записан ли 401 на ключ повтора, по первому ответу не видно: повторите тот же запрос с тем же ключом повтора действующим ключом API. Записанный отказ придёт с
Idempotency-Replayed: true, иначе запрос исполнится. - Ответ 503
dependency_unavailableэто не отказ: возврат мог быть заведён. Повторите тот же запрос с тем же ключом повтора. - Новый возврат получает 201. Повтор получает тот же возврат в нынешнем виде и заголовок
Idempotency-Replayed: true. - Порядок и пределы: Возвраты.
Запрос
curl -sS -X POST https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
-H "Authorization: Bearer $TARGET_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 0b8e4f3a-6c21-4d7e-9a15-2f4c8b7d1e90" \
-d '{
"reference": "refund-1001-1",
"amountMinor": "500",
"description": "Partial refund, ticket T-5521",
"metadata": {
"ticket": "T-5521"
}
}'Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
| Поле | Вид | Обязательно | Что это |
|---|---|---|---|
reference | строка | да | Номер возврата у вас: от 1 до 128 знаков, без пробелов по краям и невидимых знаков. Уникален у мерчанта в контуре: второй возврат с тем же номером не заводится. |
amountMinor | строка | да | Сумма возврата строкой: целое число минорных единиц валюты платежа, до 15 цифр, не больше остатка к возврату. |
description | строка | нет | Пояснение для сотрудников, до 255 знаков. Плательщику не показывается. |
metadata | объект с произвольными ключами | нет | Ваши метки: объект JSON, как у платежа. Возвращаются в ответе как есть. |
callbackUrl | строка | нет | Адрес уведомлений этого объекта (callback_url Corefy): уведомления о нём уходят сюда вместо адреса контура, подписанные секретом контура. https до 2048 знаков, в тестовом контуре можно http; полное имя узла в интернете; порт по умолчанию, 443, 8443, 80 или 8080; без имени пользователя и пароля. Нужен секрет контура: Адрес в запросе. |
Ответ 201
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер возврата: rf_ и 22 знака. |
payment | строка | всегда | Номер платежа, деньги которого возвращаются. |
reference | строка | всегда | Номер возврата, присланный при создании. |
environment | строкаTEST LIVE | всегда | Контур возврата: контур платежа. |
status | строкаPENDING SUCCEEDED FAILED | всегда | PENDING возврат идёт или его исход неизвестен, SUCCEEDED деньги ушли, FAILED возврата не было. Незнакомый статус читайте как PENDING. |
reason | строкаили nullrefund_declined technical_failure operator_declined | всегда | Причина неуспеха: refund_declined провайдер отказал, technical_failure технический сбой, operator_declined отказал сотрудник. У остальных статусов null. |
inReview | логическое | всегда | Исход возврата под вопросом. У PENDING его называет доспрос провайдера или решение сотрудников, а если провайдер вернул другую сумму, исправление вручную; у FAILED и SUCCEEDED это поздний спорный ответ провайдера, и сам он не снимается. Пока true, тех же денег не возвращайте. |
amountMinor | строка | всегда | Сумма возврата в минорных единицах валюты платежа. |
currency | строка | всегда | Валюта возврата: валюта платежа. |
feeMinor | строка | всегда | Комиссия за возврат в минорных единицах валюты платежа, сверх суммы возврата. |
providerRefundId | строкаили null | всегда | Номер операции возврата у провайдера, если он его назвал: его называют в банке плательщика. |
description | строкаили null | всегда | Пояснение, присланное при создании. null: не задано. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
callbackUrl | строкаили null | всегда | Адрес уведомлений возврата в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда возврат создан, время UTC. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда возврат получил исход, время UTC. null: ещё не получил. |
{
"id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
"payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "refund-1001-1",
"environment": "TEST",
"status": "PENDING",
"reason": null,
"inReview": false,
"amountMinor": "500",
"currency": "BRL",
"feeMinor": "0",
"providerRefundId": null,
"description": "Partial refund, ticket T-5521",
"metadata": {
"ticket": "T-5521"
},
"callbackUrl": null,
"createdAt": "2026-11-14T10:02:11.904Z",
"finalizedAt": null
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | validation_failed | Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. Исправить тело по таблице полей. |
Пример ответа | ||
| 400 | validation_failed | Значение не прошло проверку:
Исправить значение, которое называет |
Пример ответа | ||
| 400 | bad_amount |
Передать сумму строкой в минорных единицах валюты платежа. |
Пример ответа | ||
| 404 | not_found | Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет. Проверить номер и ключ. |
Пример ответа | ||
| 409 | conflictrefund_reference_exists | Возврат с таким Прочитать этот возврат, а не заводить новый. |
Пример ответа | ||
| 409 | conflictrefund_in_progress | У платежа уже идёт возврат через провайдера. Прочитать возвраты платежа: если идущий и есть этот, второй не нужен. Иначе после его исхода повторить тот же запрос с тем же ключом. |
Пример ответа | ||
| 409 | conflict | Этот возврат невозможен.
Повтор с тем же ключом получит тот же отказ: исправленный запрос отправляют с новым ключом повтора. |
Пример ответа | ||
| 409 | conflictcallback_secret_missing | Передан Выпустить секрет: |
Пример ответа | ||
| 409 | conflictrequest_in_progress | Запрос с этим ключом повтора ещё выполняется. Повторить через несколько секунд с тем же ключом и тем же телом. |
Пример ответа | ||
| 409 | conflictidempotency_key_reused | Ключ повтора уже использован другим запросом: с другим телом или другой операцией. Повтор отправляет тот же запрос; новая операция получает новый ключ. |
Пример ответа | ||
| 503 | dependency_unavailable | Ответа по существу нет: это не отказ, возврат мог быть заведён или ещё заводится.
Повторить тот же запрос с тем же ключом повтора; возврат по этому ответу отказанным не считать. Заведён ли он, показывают возвраты платежа. Если ответ повторяется, сообщить поддержке ключ повтора и время запроса. |
Пример ответа | ||
Возвраты платежа
GET/api/v1/payments/:id/refundsс 17.11.2026
Возвращает все возвраты платежа, от новых к старым. Ничего не меняет.
- У чтения возвратов свой предел частоты, отдельный от создания.
Запрос
curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
items | массив объектов | всегда | Все возвраты платежа, от новых к старым. Пусто: возвратов нет. |
items[].id | строка | всегда | Номер возврата: rf_ и 22 знака. |
items[].payment | строка | всегда | Номер платежа, деньги которого возвращаются. |
items[].reference | строка | всегда | Номер возврата, присланный при создании. |
items[].environment | строкаTEST LIVE | всегда | Контур возврата: контур платежа. |
items[].status | строкаPENDING SUCCEEDED FAILED | всегда | PENDING возврат идёт или его исход неизвестен, SUCCEEDED деньги ушли, FAILED возврата не было. Незнакомый статус читайте как PENDING. |
items[].reason | строкаили nullrefund_declined technical_failure operator_declined | всегда | Причина неуспеха: refund_declined провайдер отказал, technical_failure технический сбой, operator_declined отказал сотрудник. У остальных статусов null. |
items[].inReview | логическое | всегда | Исход возврата под вопросом. У PENDING его называет доспрос провайдера или решение сотрудников, а если провайдер вернул другую сумму, исправление вручную; у FAILED и SUCCEEDED это поздний спорный ответ провайдера, и сам он не снимается. Пока true, тех же денег не возвращайте. |
items[].amountMinor | строка | всегда | Сумма возврата в минорных единицах валюты платежа. |
items[].currency | строка | всегда | Валюта возврата: валюта платежа. |
items[].feeMinor | строка | всегда | Комиссия за возврат в минорных единицах валюты платежа, сверх суммы возврата. |
items[].providerRefundId | строкаили null | всегда | Номер операции возврата у провайдера, если он его назвал: его называют в банке плательщика. |
items[].description | строкаили null | всегда | Пояснение, присланное при создании. null: не задано. |
items[].metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
items[].callbackUrl | строкаили null | всегда | Адрес уведомлений возврата в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
items[].createdAt | строка, момент времени ISO 8601 | всегда | Когда возврат создан, время UTC. |
items[].finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда возврат получил исход, время UTC. null: ещё не получил. |
{
"items": [
{
"id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
"payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "refund-1001-1",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "500",
"currency": "BRL",
"feeMinor": "0",
"providerRefundId": "RF-88213",
"description": "Partial refund, ticket T-5521",
"metadata": {
"ticket": "T-5521"
},
"callbackUrl": null,
"createdAt": "2026-11-14T10:02:11.904Z",
"finalizedAt": "2026-11-14T10:03:12.550Z"
}
]
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 404 | not_found | Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет. Проверить номер и ключ. |
Пример ответа | ||
| 400 | validation_failed | Номер в адресе с негодной кодировкой: после Передавать номер так, как его вернул ответ создания. |
Пример ответа | ||
Прочитать возврат
GET/api/v1/payments/:id/refunds/:refundIdс 17.11.2026
Возвращает один возврат платежа по его номеру. Ничего не меняет. Так узнают исход возврата, если уведомление не пришло.
- Номер возврата чужого платежа даёт тот же ответ 404, что и несуществующий.
Запрос
curl -sS https://api.thetarget.cc/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер возврата: rf_ и 22 знака. |
payment | строка | всегда | Номер платежа, деньги которого возвращаются. |
reference | строка | всегда | Номер возврата, присланный при создании. |
environment | строкаTEST LIVE | всегда | Контур возврата: контур платежа. |
status | строкаPENDING SUCCEEDED FAILED | всегда | PENDING возврат идёт или его исход неизвестен, SUCCEEDED деньги ушли, FAILED возврата не было. Незнакомый статус читайте как PENDING. |
reason | строкаили nullrefund_declined technical_failure operator_declined | всегда | Причина неуспеха: refund_declined провайдер отказал, technical_failure технический сбой, operator_declined отказал сотрудник. У остальных статусов null. |
inReview | логическое | всегда | Исход возврата под вопросом. У PENDING его называет доспрос провайдера или решение сотрудников, а если провайдер вернул другую сумму, исправление вручную; у FAILED и SUCCEEDED это поздний спорный ответ провайдера, и сам он не снимается. Пока true, тех же денег не возвращайте. |
amountMinor | строка | всегда | Сумма возврата в минорных единицах валюты платежа. |
currency | строка | всегда | Валюта возврата: валюта платежа. |
feeMinor | строка | всегда | Комиссия за возврат в минорных единицах валюты платежа, сверх суммы возврата. |
providerRefundId | строкаили null | всегда | Номер операции возврата у провайдера, если он его назвал: его называют в банке плательщика. |
description | строкаили null | всегда | Пояснение, присланное при создании. null: не задано. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
callbackUrl | строкаили null | всегда | Адрес уведомлений возврата в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда возврат создан, время UTC. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда возврат получил исход, время UTC. null: ещё не получил. |
{
"id": "rf_5n7q2w8x4k3m9t6v2b8c4d",
"payment": "pr_8k3m2q7w9x4t6v5n2b8c4d",
"reference": "refund-1001-1",
"environment": "TEST",
"status": "SUCCEEDED",
"reason": null,
"inReview": false,
"amountMinor": "500",
"currency": "BRL",
"feeMinor": "0",
"providerRefundId": "RF-88213",
"description": "Partial refund, ticket T-5521",
"metadata": {
"ticket": "T-5521"
},
"callbackUrl": null,
"createdAt": "2026-11-14T10:02:11.904Z",
"finalizedAt": "2026-11-14T10:03:12.550Z"
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 404 | not_found | Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет. Проверить номер и ключ. |
Пример ответа | ||
| 400 | validation_failed | Номер в адресе с негодной кодировкой: после Передавать номер так, как его вернул ответ создания. |
Пример ответа | ||
Завести выплату
POST/api/v1/payoutsс 17.11.2026
Заводит выплату игроку: ставит в резерв сумму с комиссией из доступного остатка мерчанта и решает модерацию. В ответе выплата: номер, статус и решение модерации. Реквизита и данных получателя в ответе нет.
- Заголовок
Idempotency-Keyобязателен. Отказ записывается на ключ повтора: повтор того же тела получает тот же отказ, даже когда причину уже устранили, а другое тело получает 409idempotency_key_reused; после исправления отправляйте запрос с новым ключом. Не записываются:request_in_progress; отказы, которые приходят раньше ключа повтора (401 без правила, когда ключа API нет или секрет не тот, вход не ключом API, предел частоты, лишний параметр адреса, размер и форма заголовка и тела; если этим ключом уже записано это же тело, вместо отказа формы придёт записанный ответ); отказ ключа API, кончившегося больше суток назад (считая от раннего из отзыва и срока): такой ключ только читает записанное, на другое тело ему 401; боевой ключ на сервере без связки боевого контура. Ответ 5xx и обрыв соединения это не отказ: выплата могла быть заведена, повторите тот же запрос с тем же ключом. - Новая выплата получает 201. Повтор получает ту же выплату в нынешнем виде и заголовок
Idempotency-Replayed: true. - Боевые выплаты пока закрыты, выплата пока не отправляется: одобренная стоит в
CREATED, её можно отменить.
Запрос
curl -sS -X POST https://api.thetarget.cc/api/v1/payouts \
-H "Authorization: Bearer $TARGET_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 7c1d9e42-3a5b-4f80-b6d2-91e4a0c58f17" \
-d '{
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"amountMinor": "15000",
"customer": {
"id": "player-1001",
"country": "BR"
},
"fields": {
"beneficiary.pix_key": "player1001@example.com",
"beneficiary.tax_id": "52998224725"
},
"metadata": {
"withdrawalId": "W-2001"
}
}'Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
| Поле | Вид | Обязательно | Что это |
|---|---|---|---|
reference | строка | да | Номер вывода у вас: от 1 до 128 знаков, без пробелов по краям и невидимых знаков. Вторая выплата с тем же номером в контуре не заводится. |
service | строка | да | Код сервиса выплаты из списка сервисов (direction = PAYOUT). Сервис задаёт валюту, способ и поля получателя. |
amountMinor | строка | да | Сколько получит игрок, строкой: целое число минорных единиц валюты сервиса, до 15 цифр. Комиссия берётся сверх этой суммы. |
customer | объект | да | Клиент, которому выплата. |
customer.id | строка | да | Номер клиента у вас: от 1 до 128 знаков, без пробелов по краям и невидимых знаков. |
customer.country | строка | нет | Страна клиента: код ISO 3166-1 из двух заглавных букв (GB, а не UK). |
fields | объект с произвольными ключами | да | Реквизит и данные получателя по ключам из списка сервисов: beneficiary.pix_key, beneficiary.clabe, beneficiary.iban, beneficiary.name, beneficiary.tax_id. Реквизит, куда платим, ровно один. Страна счёта это первые две буквы IBAN. В ответе их нет. |
metadata | объект с произвольными ключами | нет | Ваши метки: объект JSON до 4096 знаков в записи и до 16 уровней вложенности. Возвращаются в ответе как есть. |
callbackUrl | строка | нет | Адрес уведомлений этого объекта (callback_url Corefy): уведомления о нём уходят сюда вместо адреса контура, подписанные секретом контура. https до 2048 знаков, в тестовом контуре можно http; полное имя узла в интернете; порт по умолчанию, 443, 8443, 80 или 8080; без имени пользователя и пароля. Нужен секрет контура: Адрес в запросе. |
Ответ 201
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер выплаты: po_ и 22 знака. По нему выплату читают и отменяют. |
reference | строка | всегда | Номер вывода, присланный при создании. |
service | строка | всегда | Код сервиса, которым заведена выплата. |
environment | строкаTEST LIVE | всегда | Контур выплаты: контур ключа, которым она заведена. |
status | строкаCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | всегда | CREATED заведена и ждёт решения или отправки, PROCESSING отправлена, SUCCEEDED деньги ушли, FAILED не ушли, REJECTED отклонена, CANCELLED отменена до отправки. Незнакомый статус читайте как PROCESSING. |
reason | строкаили nullcustomer_blocked rejected_by_operator cancelled_by_merchant | всегда | Причина закрытия: customer_blocked клиент или реквизит заблокирован, rejected_by_operator отклонил сотрудник, cancelled_by_merchant отменили вы. У остальных null. |
approval | строкаPENDING APPROVED REJECTED WITHDRAWN | всегда | Решение модерации: APPROVED одобрена, PENDING ждёт сотрудника, REJECTED отклонена, WITHDRAWN снята вашей отменой. |
inReview | логическое | всегда | Исход выплаты решается на нашей стороне. Пока true, не возвращайте игроку баланс и не считайте выплату прошедшей. |
amountMinor | строка | всегда | Сколько получит игрок, в минорных единицах валюты выплаты. |
currency | строка | всегда | Валюта выплаты: валюта сервиса. |
feeMinor | строка | всегда | Комиссия за выплату в минорных единицах валюты выплаты, сверх суммы. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
callbackUrl | строкаили null | всегда | Адрес уведомлений выплаты в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура, если он есть. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда выплата заведена, время UTC. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда выплата закрылась, время UTC. null: ещё нет. |
{
"id": "po_3m8q2w7k9x4t6v5n2b8c4d",
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"environment": "TEST",
"status": "CREATED",
"reason": null,
"approval": "APPROVED",
"inReview": false,
"amountMinor": "15000",
"currency": "BRL",
"feeMinor": "250",
"metadata": {
"withdrawalId": "W-2001"
},
"callbackUrl": null,
"createdAt": "2026-11-17T09:41:07.312Z",
"finalizedAt": null
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | validation_failed | Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. Исправить тело по таблице полей. |
Пример ответа | ||
| 400 | validation_failed | Заголовок или значение не прошли проверку:
Исправить значение, которое называет |
Пример ответа | ||
| 400 | bad_amount |
Передать сумму строкой в минорных единицах: «1250», а не «12.50». |
Пример ответа | ||
| 400 | bad_amountamount_out_of_range | Сумма по форме верна, но вне границ сервиса; Передать сумму в границах сервиса с новым ключом повтора. |
Пример ответа | ||
| 403 | forbidden | Боевую выплату сейчас не завести. Проверяется после формы заголовка и тела.
Заводить выплаты тестовым ключом. |
Пример ответа | ||
| 409 | conflict | Сервисом из запроса выплату сейчас не завести. Отказ занимает ключ повтора.
Взять сервис выплаты из свежего списка сервисов и отправить запрос с новым ключом повтора. |
Пример ответа | ||
| 409 | conflictpayout_reference_exists | Выплата с таким Прочитать эту выплату, а не заводить новую. |
Пример ответа | ||
| 409 | conflictinsufficient_balance | На счёте мерчанта не хватает доступных денег на сумму с комиссией. Отказ занимает ключ повтора: повтор с тем же ключом получит его же. Пополнить доступный остаток; новый вывод отправлять с новым ключом повтора. |
Пример ответа | ||
| 422 | identifier_invalid | Реквизит или данные получателя не прошли проверку, например контрольную сумму налогового номера или IBAN. Исправить значение поля и отправить запрос с новым ключом повтора. |
Пример ответа | ||
| 409 | conflictcallback_secret_missing | Передан Выпустить секрет: |
Пример ответа | ||
| 409 | conflictrequest_in_progress | Запрос с этим ключом повтора ещё выполняется. Повторить через несколько секунд с тем же ключом и тем же телом. |
Пример ответа | ||
| 409 | conflictidempotency_key_reused | Ключ повтора уже использован другим запросом: с другим телом или другой операцией. Повтор отправляет тот же запрос; новая операция получает новый ключ. |
Пример ответа | ||
| 503 | dependency_unavailable | Ответа по существу нет: выплата не заведена или заведена, и ответ о ней не дошёл. Это не отказ.
Не возвращать игроку баланс. Повторить тот же запрос с тем же ключом повтора: повтор отдаст выплату, если она заведена. |
Пример ответа | ||
Прочитать выплату
GET/api/v1/payouts/:idс 17.11.2026
Возвращает выплату по её номеру. Ничего не меняет.
- Номер чужой выплаты даёт тот же ответ 404, что и несуществующий.
Запрос
curl -sS https://api.thetarget.cc/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер выплаты: po_ и 22 знака. По нему выплату читают и отменяют. |
reference | строка | всегда | Номер вывода, присланный при создании. |
service | строка | всегда | Код сервиса, которым заведена выплата. |
environment | строкаTEST LIVE | всегда | Контур выплаты: контур ключа, которым она заведена. |
status | строкаCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | всегда | CREATED заведена и ждёт решения или отправки, PROCESSING отправлена, SUCCEEDED деньги ушли, FAILED не ушли, REJECTED отклонена, CANCELLED отменена до отправки. Незнакомый статус читайте как PROCESSING. |
reason | строкаили nullcustomer_blocked rejected_by_operator cancelled_by_merchant | всегда | Причина закрытия: customer_blocked клиент или реквизит заблокирован, rejected_by_operator отклонил сотрудник, cancelled_by_merchant отменили вы. У остальных null. |
approval | строкаPENDING APPROVED REJECTED WITHDRAWN | всегда | Решение модерации: APPROVED одобрена, PENDING ждёт сотрудника, REJECTED отклонена, WITHDRAWN снята вашей отменой. |
inReview | логическое | всегда | Исход выплаты решается на нашей стороне. Пока true, не возвращайте игроку баланс и не считайте выплату прошедшей. |
amountMinor | строка | всегда | Сколько получит игрок, в минорных единицах валюты выплаты. |
currency | строка | всегда | Валюта выплаты: валюта сервиса. |
feeMinor | строка | всегда | Комиссия за выплату в минорных единицах валюты выплаты, сверх суммы. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
callbackUrl | строкаили null | всегда | Адрес уведомлений выплаты в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура, если он есть. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда выплата заведена, время UTC. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда выплата закрылась, время UTC. null: ещё нет. |
{
"id": "po_3m8q2w7k9x4t6v5n2b8c4d",
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"environment": "TEST",
"status": "CREATED",
"reason": null,
"approval": "APPROVED",
"inReview": false,
"amountMinor": "15000",
"currency": "BRL",
"feeMinor": "250",
"metadata": {
"withdrawalId": "W-2001"
},
"callbackUrl": null,
"createdAt": "2026-11-17T09:41:07.312Z",
"finalizedAt": null
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 404 | not_found | Выплаты с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. Проверить номер и ключ. |
Пример ответа | ||
| 400 | validation_failed | Номер в адресе с негодной кодировкой: после Передавать номер так, как его вернул ответ создания. |
Пример ответа | ||
Отменить выплату
POST/api/v1/payouts/:id/cancelс 17.11.2026
Отменяет выплату, пока она не отправлена, и возвращает резерв в доступный остаток. В ответе выплата в статусе CANCELLED.
- Повтор отмены отменённой выплаты отдаёт её же.
Запрос
curl -sS -X POST https://api.thetarget.cc/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 200
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
id | строка | всегда | Номер выплаты: po_ и 22 знака. По нему выплату читают и отменяют. |
reference | строка | всегда | Номер вывода, присланный при создании. |
service | строка | всегда | Код сервиса, которым заведена выплата. |
environment | строкаTEST LIVE | всегда | Контур выплаты: контур ключа, которым она заведена. |
status | строкаCREATED PROCESSING SUCCEEDED FAILED REJECTED CANCELLED | всегда | CREATED заведена и ждёт решения или отправки, PROCESSING отправлена, SUCCEEDED деньги ушли, FAILED не ушли, REJECTED отклонена, CANCELLED отменена до отправки. Незнакомый статус читайте как PROCESSING. |
reason | строкаили nullcustomer_blocked rejected_by_operator cancelled_by_merchant | всегда | Причина закрытия: customer_blocked клиент или реквизит заблокирован, rejected_by_operator отклонил сотрудник, cancelled_by_merchant отменили вы. У остальных null. |
approval | строкаPENDING APPROVED REJECTED WITHDRAWN | всегда | Решение модерации: APPROVED одобрена, PENDING ждёт сотрудника, REJECTED отклонена, WITHDRAWN снята вашей отменой. |
inReview | логическое | всегда | Исход выплаты решается на нашей стороне. Пока true, не возвращайте игроку баланс и не считайте выплату прошедшей. |
amountMinor | строка | всегда | Сколько получит игрок, в минорных единицах валюты выплаты. |
currency | строка | всегда | Валюта выплаты: валюта сервиса. |
feeMinor | строка | всегда | Комиссия за выплату в минорных единицах валюты выплаты, сверх суммы. |
metadata | любое значение | всегда | Ваши метки, как они пришли при создании. |
callbackUrl | строкаили null | всегда | Адрес уведомлений выплаты в той записи, в какой его понял сервер. null: не задан, уведомления идут на адрес контура, если он есть. |
createdAt | строка, момент времени ISO 8601 | всегда | Когда выплата заведена, время UTC. |
finalizedAt | строка, момент времени ISO 8601или null | всегда | Когда выплата закрылась, время UTC. null: ещё нет. |
{
"id": "po_3m8q2w7k9x4t6v5n2b8c4d",
"reference": "withdrawal-2001",
"service": "payout_pix_brl_direct",
"environment": "TEST",
"status": "CANCELLED",
"reason": "cancelled_by_merchant",
"approval": "APPROVED",
"inReview": false,
"amountMinor": "15000",
"currency": "BRL",
"feeMinor": "250",
"metadata": {
"withdrawalId": "W-2001"
},
"callbackUrl": null,
"createdAt": "2026-11-17T09:41:07.312Z",
"finalizedAt": "2026-11-17T09:43:52.018Z"
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 404 | not_found | Выплаты с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. Проверить номер и ключ. |
Пример ответа | ||
| 409 | conflictpayout_not_cancellable | Выплату уже не отменить: она отправлена или закрыта; Прочитать выплату и дождаться её исхода. |
Пример ответа | ||
| 400 | validation_failed | Номер в адресе с негодной кодировкой: после Передавать номер так, как его вернул ответ создания. |
Пример ответа | ||
Выпустить секрет подписи уведомлений
POST/api/v1/notifications/secretс 17.11.2026
Выпускает секрет подписи уведомлений контура ключа, если его ещё нет. Он нужен, чтобы передавать callbackUrl в запросах и проверять подпись уведомлений. Секрет показывается один раз.
- Тела нет. Контур задаёт ключ API.
- Секрет уже есть: 409
notify_secret_exists. Сменить его ключом API нельзя: меняют в кабинете мерчанта или у администратора. - Ответ не кешируется. Храните секрет как пароль, рядом с ключом API.
- Свой предел частоты: 10 запросов в минуту с одного адреса.
Запрос
curl -sS -X POST https://api.thetarget.cc/api/v1/notifications/secret \
-H "Authorization: Bearer $TARGET_API_KEY"Параметров в адресе нет. Параметр с незнакомым именем отклоняется.
Тела у запроса нет.
Ответ 201
| Поле | Вид | В ответе | Что это |
|---|---|---|---|
secret | строка | всегда | Секрет подписи уведомлений вида whsec_…: им проверяют подпись по Standard Webhooks. Показывается один раз. |
environment | строкаTEST LIVE | всегда | Контур секрета: контур ключа API. |
createdAt | строка | всегда | Когда секрет выпущен, время UTC. |
{
"secret": "whsec_<base64 of 32 bytes>",
"environment": "TEST",
"createdAt": "2026-11-17T10:00:00.000Z"
}Отказы
Сверх общих отказов:
| HTTP | Код и правило | Когда приходит и что делать |
|---|---|---|
| 400 | validation_failed | Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. Исправить тело по таблице полей. |
Пример ответа | ||
| 409 | conflictnotify_secret_exists | У контура ключа секрет подписи уже есть: его выпустили этой ручкой, в кабинете мерчанта или администратор вместе с адресом контура. Повторно секрет не показывается. Взять секрет там, где его выпустили. Потерянный секрет меняют в кабинете мерчанта (страница «Уведомления», с кодом из приложения) или у администратора; ключом API его не сменить. |
Пример ответа | ||
| 409 | conflictkeyring_not_loaded | На нашей стороне не загружены ключи, из которых выводится секрет подписи этого контура. Секрет не выпущен. Повторить позже. Если повторяется, сообщить поддержке время запроса. |
Пример ответа | ||