Справочник методов

Адрес, поля ответа и отказы каждой выпущенной ручки API.

Справочник собирается из схем сервера, а стенд сверяет с ними отказы, адреса и ответы работающего сервера там, где их можно вызвать без провайдера.

Общее для всех ручек

Проверить ключ

GET/api/v1/meс 12.11.2026

Возвращает мерчанта, контур и открытую часть ключа, которым сделан запрос. Ничего не меняет. С этого запроса начинают интеграцию: он показывает, что ключ принят и к какому контуру относится.

  • Секрет ключа в ответе не возвращается никогда.
  • Названия, которым администратор пометил ключ у себя в консоли, в ответе нет.

Запрос

curl -sS https://api.paydex.co.uk/api/v1/me \
  -H "Authorization: Bearer $PAYDEX_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.paydex.co.uk/api/v1/services \
  -H "Authorization: Bearer $PAYDEX_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.paydex.co.uk/api/v1/payments \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
400validation_failed

Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. details.issues называет поля.

Исправить тело по таблице полей.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

Значение не прошло проверку: details.field называет поле, details.rule правило.

  • reference_shape: reference пуст, длиннее 128 знаков, с пробелами по краям, управляющими или невидимыми знаками.
  • external_ref_shape: То же у customer.id.
  • country_code: customer.country не присвоенный код ISO 3166-1 из двух заглавных букв.
  • return_url: returnUrl не https (в тестовом контуре можно http), без имени узла, с именем пользователя или паролем либо длиннее 1024 знаков.
  • return_url_not_allowed: У установки есть страница оплаты, а источник returnUrl не в списке разрешённых источников мерчанта: его вносит администратор.
  • metadata_shape: metadata не объект JSON, длиннее 4096 знаков в записи, глубже 16 уровней или с числом, которое JSON не держит точно.
  • reserved_key: В теле есть ключ __proto__.
  • fields_on_page_conflict: Переданы и fields, и fieldsOnPage: true.
  • idempotency_key_shape: Заголовок Idempotency-Key пуст, длиннее 128 знаков или с пробелами и знаками вне видимых ASCII.
  • unknown_field: В fields ключ, которого у сервиса нет.
  • field_not_accepted: Поле есть у сервиса, но приём его не принимает.
  • required: Нет поля, которое сервис требует.
  • field_shape: Значение поля пусто, с пробелами по краям, управляющими или невидимыми знаками; имя плательщика без единой буквы.
  • field_too_long: Значение длиннее maxLength поля сервиса.
  • field_kind: Значение не того вида, что требует kind поля сервиса.
  • field_pattern: Значение не проходит выражение pattern поля сервиса.
  • callback_url_invalid: callbackUrl не адрес, длиннее 2048 знаков, с именем пользователя или паролем, фрагментом, пробелом или управляющим знаком либо с портом не из 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl не https (в тестовом контуре можно http).
  • callback_url_internal: callbackUrl ведёт во внутреннюю или служебную сеть: адрес-число частной или служебной сети, localhost, имя без точки или служебный домен (.local, .internal, .lan, .localdomain, .home.arpa).

Исправить значение, которое называет details.field.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference: 1 to 128 characters without leading or trailing spaces, control or invisible characters",
    "details": {
      "field": "reference",
      "rule": "reference_shape"
    }
  }
}
400bad_amount

amountMinor не строка с целым положительным числом до 15 цифр: например «12.50» или «0».

Передать сумму строкой в минорных единицах: «1250», а не «12.50».

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
400bad_amount

Сумма по форме верна, но сервис её не принимает.

  • amount_out_of_range: Сумма вне границ сервиса; details.minMinor и details.maxMinor называют границы.
  • amount_not_above_fee: Сумма не больше комиссии сервиса: мерчант не получил бы ничего.

Передать сумму в границах сервиса и больше его комиссии.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is outside the service limits",
    "details": {
      "field": "amountMinor",
      "rule": "amount_out_of_range",
      "minMinor": "100",
      "maxMinor": "10000000"
    }
  }
}
403forbiddenlive_intake_closed

Платёж создаётся боевым ключом, а боевой приём закрыт. Проверяется раньше тела запроса.

Создавать платежи тестовым ключом.

Пример ответа
POST /api/v1/payments

HTTP/1.1 403

{
  "error": {
    "code": "forbidden",
    "message": "Live payment intake is closed: the test environment is open",
    "details": {
      "rule": "live_intake_closed"
    }
  }
}
409conflict

Сервисом из запроса платёж сейчас не создать.

  • service_unavailable: Сервиса нет в списке сервисов ключа, или он перестал быть доступен.
  • service_not_payin: Сервис не для приёма платежа.
  • card_data_not_accepted: Сервис требует данные карты, а приём их не принимает.
  • service_field_unsupported: Сервис требует поле, которое приём не принимает; details.field называет его.

Взять сервис из свежего списка сервисов.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "Service unavailable: GET /api/v1/services lists the available services",
    "details": {
      "rule": "service_unavailable"
    }
  }
}
409conflictpayment_reference_exists

Платёж с таким reference в контуре уже создан; details.paymentId называет его.

Прочитать этот платёж, а не создавать новый.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A payment with this order reference has already been created",
    "details": {
      "rule": "payment_reference_exists",
      "paymentId": "pr_8k3m2q7w9x4t6v5n2b8c4d"
    }
  }
}
409conflictrequest_in_progress

Запрос с этим ключом повтора ещё выполняется.

Повторить через несколько секунд с тем же ключом и тем же телом.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

Ключ повтора уже использован другим запросом: с другим телом или другой операцией.

Повтор отправляет тот же запрос; новая операция получает новый ключ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
409conflictidempotency_key_unverifiable

Ключ повтора записан так, что сверить с ним тело на нашей стороне нечем.

Сообщить поддержке ключ повтора и время запроса.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The idempotency key was recorded under an encryption key that is not available here: the request cannot be checked",
    "details": {
      "rule": "idempotency_key_unverifiable"
    }
  }
}
409conflict

Параллельный запрос в тот же миг изменил те же данные, например клиента. Платёж не создан; details.requestId называет запрос.

Повторить тот же запрос.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The operation conflicts with the current state of the data",
    "details": {
      "requestId": "00000000-0000-4000-8000-000000000000"
    }
  }
}
409keyring_unavailable

На нашей стороне недоступны ключи шифрования, которыми записываются ключ повтора и данные плательщика. Запрос не исполнен.

Повторить позже. Если повторяется, сообщить поддержке время запроса.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "keyring_unavailable",
    "message": "The test environment encryption keys are not loaded",
    "details": {
      "environment": "TEST"
    }
  }
}
422identifier_invalid

Данные плательщика не прошли проверку, например контрольную сумму налогового номера. details.field называет поле, details.kind вид данных, details.rule проверку; значения в ответе нет.

Исправить значение поля.

Пример ответа
POST /api/v1/payments

HTTP/1.1 422

{
  "error": {
    "code": "identifier_invalid",
    "message": "Identifier failed validation",
    "details": {
      "field": "fields.payer.tax_id",
      "kind": "TAX_ID",
      "rule": "cpf_checksum"
    }
  }
}
409conflict

Поля плательщика страницей оплаты сейчас не собрать.

  • pay_page_unavailable: Страницы оплаты нет, а у сервиса есть поля плательщика.
  • fields_on_page_ttl_too_short: Срок платежа мерчанта короче пяти минут: плательщик не успеет заполнить поля.

Собрать поля своей формой и передать в fields.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payment page is not enabled for this installation: send the payer fields in fields",
    "details": {
      "rule": "pay_page_unavailable"
    }
  }
}
409conflictcallback_secret_missing

Передан callbackUrl, а у контура ключа нет секрета подписи уведомлений: подписать уведомления нечем. Ключ повтора у платежа отпускается, у возврата и выплаты отказ записывается на ключ, как их другие отказы после ключа.

Выпустить секрет: POST /api/v1/notifications/secret, или попросить адрес контура у администратора. Потом повторить запрос; у возврата и выплаты с новым ключом повтора: прежний ключ хранит этот отказ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
503dependency_unavailable

Приём временно не работает; платёж не создан.

  • transition_policy_missing: Приём не настроен на нашей стороне.
  • transition_policy_incomplete: Приём не может отправить попытку провайдеру.
  • transaction_timeout: Приём не уложился в срок на нашей стороне.

Повторить позже с тем же ключом повтора.

Пример ответа
POST /api/v1/payments

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "Payment intake is not working: it is not configured on our side",
    "details": {
      "rule": "transition_policy_missing"
    }
  }
}

Найти платёж по номеру заказа

GET/api/v1/paymentsс 17.11.2026

Возвращает платёж с этим номером заказа в контуре ключа: ноль или одна запись. Так находят платёж, ответ на создание которого не дошёл, а ключа повтора не было.

  • Без reference адрес отвечает отказом 501: списка платежей нет.
  • Предел частоты общий с чтением платежа по номеру.

Запрос

curl -sS 'https://api.paydex.co.uk/api/v1/payments?reference=order-1001' \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
400validation_failed

reference передан дважды или списком.

Передать один номер заказа.

Пример ответа
GET /api/v1/payments?reference=order-1001&reference=order-1002

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference must be sent once, as a string",
    "details": {
      "field": "reference"
    }
  }
}
400validation_failedreference_shape

Номер заказа пуст, длиннее 128 знаков, с пробелами по краям, управляющими или невидимыми знаками.

Проверить номер и закодировать его как часть адреса.

Пример ответа
GET /api/v1/payments?reference=%20order-1001

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Order reference: 1 to 128 characters without leading or trailing spaces, control or invisible characters",
    "details": {
      "field": "reference",
      "rule": "reference_shape"
    }
  }
}
501not_implemented

Запрос без reference: списка платежей нет.

Читать платёж по номеру или по номеру заказа.

Пример ответа
GET /api/v1/payments

HTTP/1.1 501

{
  "error": {
    "code": "not_implemented",
    "message": "The payment list is not open yet. Read a payment by its ID: GET /api/v1/payments/{id}, or by its order reference: GET /api/v1/payments?reference={reference}, with the reference encoded as part of the URL (otherwise + & # and spaces change it)."
  }
}

Прочитать платёж

GET/api/v1/payments/:idс 13.11.2026

Возвращает платёж по его номеру в контуре ключа. Ничего не меняет. Так узнают исход платежа, если уведомление не пришло, и сверяют его перед зачислением.

  • Чужой платёж, платёж другого контура и номер не по форме дают один и тот же ответ 404.
  • У чтения свой предел частоты, отдельный от создания: Ограничения.

Запрос

curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
404not_found

Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

Номер в адресе с негодной кодировкой: после % не две шестнадцатеричные цифры, или байты не складываются в UTF-8.

Передавать номер так, как его вернул ответ создания.

Пример ответа
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Создать возврат

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, 403 merchant_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.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
400validation_failed

Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. details.issues называет поля.

Исправить тело по таблице полей.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

Значение не прошло проверку: details.field называет поле, details.rule правило.

  • idempotency_key_required: Нет заголовка Idempotency-Key: у возврата он обязателен.
  • idempotency_key_shape: Заголовок Idempotency-Key пуст, длиннее 128 знаков или с пробелами и знаками вне видимых ASCII.
  • reference_shape: reference возврата пуст, длиннее 128 знаков, с пробелами по краям, управляющими или невидимыми знаками.
  • description_shape: description пуст, длиннее 255 знаков или с управляющими и невидимыми знаками.
  • metadata_shape: metadata не объект JSON, длиннее 4096 знаков в записи, глубже 16 уровней или с числом, которое JSON не держит точно.
  • reserved_key: В теле есть ключ __proto__.
  • callback_url_invalid: callbackUrl не адрес, длиннее 2048 знаков, с именем пользователя или паролем, фрагментом, пробелом или управляющим знаком либо с портом не из 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl не https (в тестовом контуре можно http).
  • callback_url_internal: callbackUrl ведёт во внутреннюю или служебную сеть: адрес-число частной или служебной сети, localhost, имя без точки или служебный домен (.local, .internal, .lan, .localdomain, .home.arpa).

Исправить значение, которое называет details.field.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The Idempotency-Key header is required to create a refund: a retry without it would refund the money twice",
    "details": {
      "field": "Idempotency-Key",
      "rule": "idempotency_key_required"
    }
  }
}
400bad_amount

amountMinor не строка с целым положительным числом до 15 цифр.

Передать сумму строкой в минорных единицах валюты платежа.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
404not_found

Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
409conflictrefund_reference_exists

Возврат с таким reference в контуре уже заведён; details.refundId и details.paymentId называют его.

Прочитать этот возврат, а не заводить новый.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A refund with this reference already exists",
    "details": {
      "rule": "refund_reference_exists",
      "refundId": "rf_5n7q2w8x4k3m9t6v2b8c4d",
      "paymentId": "pr_8k3m2q7w9x4t6v5n2b8c4d"
    }
  }
}
409conflictrefund_in_progress

У платежа уже идёт возврат через провайдера.

Прочитать возвраты платежа: если идущий и есть этот, второй не нужен. Иначе после его исхода повторить тот же запрос с тем же ключом.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A refund of this payment is already in progress at the provider: wait for its outcome",
    "details": {
      "rule": "refund_in_progress"
    }
  }
}
409conflict

Этот возврат невозможен.

  • payment_not_refundable: Платёж не успешный, в разборе или создан не через API.
  • refund_exceeds_remaining: Сумма больше остатка к возврату; details.remainingMinor называет остаток.
  • refund_amount_too_small: Сумма так мала, что у провайдера в его валюте выходит ноль.
  • refund_limit_reached: У платежа уже 50 возвратов, кроме неуспешных, или 200 всего.
  • insufficient_balance: На счёте мерчанта не хватает доступных денег на возврат.

Повтор с тем же ключом получит тот же отказ: исправленный запрос отправляют с новым ключом повтора.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payment cannot be refunded: only a successful payment that is not under review can be refunded",
    "details": {
      "rule": "payment_not_refundable"
    }
  }
}
409conflictcallback_secret_missing

Передан callbackUrl, а у контура ключа нет секрета подписи уведомлений: подписать уведомления нечем. Ключ повтора у платежа отпускается, у возврата и выплаты отказ записывается на ключ, как их другие отказы после ключа.

Выпустить секрет: POST /api/v1/notifications/secret, или попросить адрес контура у администратора. Потом повторить запрос; у возврата и выплаты с новым ключом повтора: прежний ключ хранит этот отказ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
409conflictrequest_in_progress

Запрос с этим ключом повтора ещё выполняется.

Повторить через несколько секунд с тем же ключом и тем же телом.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

Ключ повтора уже использован другим запросом: с другим телом или другой операцией.

Повтор отправляет тот же запрос; новая операция получает новый ключ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
503dependency_unavailable

Ответа по существу нет: это не отказ, возврат мог быть заведён или ещё заводится.

  • transaction_timeout: Возврат не уложился в срок на нашей стороне и не заведён.
  • transaction_conflict: Запись возврата столкнулась на нашей стороне с параллельной; возврат не заведён.
  • idempotency_unrecorded: Исход запроса не удалось записать на ключ повтора, или первый запрос с этим ключом ещё уходит провайдеру.
  • keyring_unavailable: На нашей стороне недоступны ключи, которыми записывается ключ повтора; ключ не занят.
  • idempotency_key_unverifiable: Ключ повтора записан так, что сверить с ним тело на нашей стороне сейчас нечем; возврат мог быть заведён.

Повторить тот же запрос с тем же ключом повтора; возврат по этому ответу отказанным не считать. Заведён ли он, показывают возвраты платежа. Если ответ повторяется, сообщить поддержке ключ повтора и время запроса.

Пример ответа
POST /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "The refund did not finish within the transaction time: no answer, retry the request with the same idempotency key",
    "details": {
      "rule": "transaction_timeout"
    }
  }
}

Возвраты платежа

GET/api/v1/payments/:id/refundsс 17.11.2026

Возвращает все возвраты платежа, от новых к старым. Ничего не меняет.

  • У чтения возвратов свой предел частоты, отдельный от создания.

Запрос

curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
404not_found

Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

Номер в адресе с негодной кодировкой: после % не две шестнадцатеричные цифры, или байты не складываются в UTF-8.

Передавать номер так, как его вернул ответ создания.

Пример ответа
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Прочитать возврат

GET/api/v1/payments/:id/refunds/:refundIdс 17.11.2026

Возвращает один возврат платежа по его номеру. Ничего не меняет. Так узнают исход возврата, если уведомление не пришло.

  • Номер возврата чужого платежа даёт тот же ответ 404, что и несуществующий.

Запрос

curl -sS https://api.paydex.co.uk/api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d/refunds/rf_5n7q2w8x4k3m9t6v2b8c4d \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
404not_found

Платежа или возврата с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура. У чтения возврата сообщение называет оба: правила, что из двух не нашлось, у ответа нет.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payments/pr_8k3m2q7w9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payment not found"
  }
}
400validation_failed

Номер в адресе с негодной кодировкой: после % не две шестнадцатеричные цифры, или байты не складываются в UTF-8.

Передавать номер так, как его вернул ответ создания.

Пример ответа
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Завести выплату

POST/api/v1/payoutsс 17.11.2026

Заводит выплату игроку: ставит в резерв сумму с комиссией из доступного остатка мерчанта и решает модерацию. В ответе выплата: номер, статус и решение модерации. Реквизита и данных получателя в ответе нет.

  • Заголовок Idempotency-Key обязателен. Отказ записывается на ключ повтора: повтор того же тела получает тот же отказ, даже когда причину уже устранили, а другое тело получает 409 idempotency_key_reused; после исправления отправляйте запрос с новым ключом. Не записываются: request_in_progress; отказы, которые приходят раньше ключа повтора (401 без правила, когда ключа API нет или секрет не тот, вход не ключом API, предел частоты, лишний параметр адреса, размер и форма заголовка и тела; если этим ключом уже записано это же тело, вместо отказа формы придёт записанный ответ); отказ ключа API, кончившегося больше суток назад (считая от раннего из отзыва и срока): такой ключ только читает записанное, на другое тело ему 401; боевой ключ на сервере без связки боевого контура. Ответ 5xx и обрыв соединения это не отказ: выплата могла быть заведена, повторите тот же запрос с тем же ключом.
  • Новая выплата получает 201. Повтор получает ту же выплату в нынешнем виде и заголовок Idempotency-Replayed: true.
  • Боевые выплаты пока закрыты, выплата пока не отправляется: одобренная стоит в CREATED, её можно отменить.

Запрос

curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
400validation_failed

Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. details.issues называет поля.

Исправить тело по таблице полей.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
400validation_failed

Заголовок или значение не прошли проверку: details.field называет поле, details.rule правило. Отказ формы заголовка и тела приходит до ключа повтора и его не занимает; если этим ключом уже записано это же тело, придёт записанный ответ. Отказ сверки fields с полями сервиса (правила от destination_required до field_pattern) приходит после занятия ключа и записывается на него.

  • idempotency_key_required: Нет заголовка Idempotency-Key: у выплаты он обязателен.
  • idempotency_key_shape: Заголовок Idempotency-Key пуст, длиннее 128 знаков или с пробелами и знаками вне видимых ASCII.
  • reference_shape: reference пуст, длиннее 128 знаков, с пробелами по краям, управляющими или невидимыми знаками.
  • external_ref_shape: То же у customer.id.
  • country_code: customer.country не присвоенный код ISO 3166-1 из двух заглавных букв.
  • metadata_shape: metadata не объект JSON, длиннее 4096 знаков в записи, глубже 16 уровней или с числом, которое JSON не держит точно.
  • reserved_key: В теле есть ключ __proto__.
  • callback_url_invalid: callbackUrl не адрес, длиннее 2048 знаков, с именем пользователя или паролем, фрагментом, пробелом или управляющим знаком либо с портом не из 443, 8443, 80, 8080.
  • callback_url_scheme: callbackUrl не https (в тестовом контуре можно http).
  • callback_url_internal: callbackUrl ведёт во внутреннюю или служебную сеть: адрес-число частной или служебной сети, localhost, имя без точки или служебный домен (.local, .internal, .lan, .localdomain, .home.arpa).
  • destination_required: В fields не ровно один реквизит, куда платим.
  • unknown_field: В fields ключ, которого у сервиса нет.
  • field_not_accepted: Поле есть у сервиса, но выплата его не принимает.
  • required: Нет поля, которое сервис требует.
  • field_shape: Значение поля пусто, с пробелами по краям, управляющими или невидимыми знаками; имя получателя без единой буквы.
  • field_too_long: Значение длиннее maxLength поля сервиса.
  • field_kind: Значение не того вида, что требует kind поля сервиса.
  • field_pattern: Значение не проходит выражение pattern поля сервиса.

Исправить значение, которое называет details.field. После отказа сверки fields исправленный запрос отправлять с новым ключом повтора: со старым ключом то же тело получит записанный отказ, исправленное 409 idempotency_key_reused.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The Idempotency-Key header is required to create a payout: a retry without it would pay out the money twice",
    "details": {
      "field": "Idempotency-Key",
      "rule": "idempotency_key_required"
    }
  }
}
400bad_amount

amountMinor не строка с целым положительным числом до 15 цифр: например «12.50» или «0».

Передать сумму строкой в минорных единицах: «1250», а не «12.50».

Пример ответа
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is a string with a positive integer number of minor currency units, up to 15 digits",
    "details": {
      "field": "amountMinor"
    }
  }
}
400bad_amountamount_out_of_range

Сумма по форме верна, но вне границ сервиса; details.minMinor и details.maxMinor называют границы. Отказ занимает ключ повтора.

Передать сумму в границах сервиса с новым ключом повтора.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 400

{
  "error": {
    "code": "bad_amount",
    "message": "Amount is outside the service limits",
    "details": {
      "field": "amountMinor",
      "rule": "amount_out_of_range",
      "minMinor": "100",
      "maxMinor": "5000000"
    }
  }
}
403forbidden

Боевую выплату сейчас не завести. Проверяется после формы заголовка и тела.

  • live_payouts_closed: Выплата заводится боевым ключом, а боевые выплаты закрыты.
  • live_payouts_disabled: Боевые выплаты этому мерчанту не включены.

Заводить выплаты тестовым ключом.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 403

{
  "error": {
    "code": "forbidden",
    "message": "Live payouts are closed: the test environment is open",
    "details": {
      "rule": "live_payouts_closed"
    }
  }
}
409conflict

Сервисом из запроса выплату сейчас не завести. Отказ занимает ключ повтора.

  • service_unavailable: Сервиса нет в списке сервисов ключа, он перестал быть доступен или маршрут к нему только с конвертацией.
  • service_not_payout: Сервис не для выплаты.
  • service_field_unsupported: Сервис требует поле, которое выплата этой версии API ещё не принимает; details.field называет его.

Взять сервис выплаты из свежего списка сервисов и отправить запрос с новым ключом повтора.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "Service unavailable: GET /api/v1/services lists the available services",
    "details": {
      "rule": "service_unavailable"
    }
  }
}
409conflictpayout_reference_exists

Выплата с таким reference в контуре уже заведена; details.payoutId называет её.

Прочитать эту выплату, а не заводить новую.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A payout with this reference already exists",
    "details": {
      "rule": "payout_reference_exists",
      "payoutId": "po_3m8q2w7k9x4t6v5n2b8c4d"
    }
  }
}
409conflictinsufficient_balance

На счёте мерчанта не хватает доступных денег на сумму с комиссией. Отказ занимает ключ повтора: повтор с тем же ключом получит его же.

Пополнить доступный остаток; новый вывод отправлять с новым ключом повтора.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The merchant's available balance is not enough for the payout with its fee",
    "details": {
      "rule": "insufficient_balance"
    }
  }
}
422identifier_invalid

Реквизит или данные получателя не прошли проверку, например контрольную сумму налогового номера или IBAN. details.field называет поле, details.kind вид данных, details.rule проверку; значения в ответе нет. Отказ записан на ключ повтора.

Исправить значение поля и отправить запрос с новым ключом повтора.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 422

{
  "error": {
    "code": "identifier_invalid",
    "message": "Identifier failed validation",
    "details": {
      "field": "fields.beneficiary.pix_key",
      "kind": "PIX_KEY",
      "rule": "pix_key_unrecognized"
    }
  }
}
409conflictcallback_secret_missing

Передан callbackUrl, а у контура ключа нет секрета подписи уведомлений: подписать уведомления нечем. Ключ повтора у платежа отпускается, у возврата и выплаты отказ записывается на ключ, как их другие отказы после ключа.

Выпустить секрет: POST /api/v1/notifications/secret, или попросить адрес контура у администратора. Потом повторить запрос; у возврата и выплаты с новым ключом повтора: прежний ключ хранит этот отказ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "callbackUrl needs the notification signing secret of the environment: POST /api/v1/notifications/secret",
    "details": {
      "rule": "callback_secret_missing"
    }
  }
}
409conflictrequest_in_progress

Запрос с этим ключом повтора ещё выполняется.

Повторить через несколько секунд с тем же ключом и тем же телом.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "A request with this idempotency key is still running: retry later",
    "details": {
      "rule": "request_in_progress"
    }
  }
}
409conflictidempotency_key_reused

Ключ повтора уже использован другим запросом: с другим телом или другой операцией.

Повтор отправляет тот же запрос; новая операция получает новый ключ.

Пример ответа
POST /api/v1/payments

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "This idempotency key has already been used with another request",
    "details": {
      "rule": "idempotency_key_reused"
    }
  }
}
503dependency_unavailable

Ответа по существу нет: выплата не заведена или заведена, и ответ о ней не дошёл. Это не отказ.

  • idempotency_unrecorded: Ответ не удалось записать на ключ повтора.
  • transaction_timeout: Выплата не уложилась в срок на нашей стороне.
  • transaction_conflict: Параллельный запрос в тот же миг изменил те же данные.
  • keyring_unavailable: На нашей стороне недоступны ключи шифрования контура.
  • idempotency_key_unverifiable: Ключ повтора записан так, что сверить с ним тело на нашей стороне нечем.
  • idempotency_key_unreadable: Ключ повтора не удалось прочитать на нашей стороне, проверяя отказ формы тела.

Не возвращать игроку баланс. Повторить тот же запрос с тем же ключом повтора: повтор отдаст выплату, если она заведена.

Пример ответа
POST /api/v1/payouts

HTTP/1.1 503

{
  "error": {
    "code": "dependency_unavailable",
    "message": "No answer: retry the request with the same idempotency key",
    "details": {
      "rule": "idempotency_unrecorded"
    }
  }
}

Прочитать выплату

GET/api/v1/payouts/:idс 17.11.2026

Возвращает выплату по её номеру. Ничего не меняет.

  • Номер чужой выплаты даёт тот же ответ 404, что и несуществующий.

Запрос

curl -sS https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
404not_found

Выплаты с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payout not found"
  }
}
400validation_failed

Номер в адресе с негодной кодировкой: после % не две шестнадцатеричные цифры, или байты не складываются в UTF-8.

Передавать номер так, как его вернул ответ создания.

Пример ответа
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Отменить выплату

POST/api/v1/payouts/:id/cancelс 17.11.2026

Отменяет выплату, пока она не отправлена, и возвращает резерв в доступный остаток. В ответе выплата в статусе CANCELLED.

  • Повтор отмены отменённой выплаты отдаёт её же.

Запрос

curl -sS -X POST https://api.paydex.co.uk/api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
404not_found

Выплаты с таким номером в контуре ключа нет: номер не по форме, чужой или другого контура.

Проверить номер и ключ.

Пример ответа
GET /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d

HTTP/1.1 404

{
  "error": {
    "code": "not_found",
    "message": "Payout not found"
  }
}
409conflictpayout_not_cancellable

Выплату уже не отменить: она отправлена или закрыта; details.status называет её статус.

Прочитать выплату и дождаться её исхода.

Пример ответа
POST /api/v1/payouts/po_3m8q2w7k9x4t6v5n2b8c4d/cancel

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The payout cannot be cancelled: it has already been sent or closed",
    "details": {
      "rule": "payout_not_cancellable",
      "status": "PROCESSING"
    }
  }
}
400validation_failed

Номер в адресе с негодной кодировкой: после % не две шестнадцатеричные цифры, или байты не складываются в UTF-8.

Передавать номер так, как его вернул ответ создания.

Пример ответа
GET /api/v1/payments/pr_%ZZ

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "The request path has an invalid encoding",
    "details": {
      "field": "path"
    }
  }
}

Выпустить секрет подписи уведомлений

POST/api/v1/notifications/secretс 17.11.2026

Выпускает секрет подписи уведомлений контура ключа, если его ещё нет. Он нужен, чтобы передавать callbackUrl в запросах и проверять подпись уведомлений. Секрет показывается один раз.

  • Тела нет. Контур задаёт ключ API.
  • Секрет уже есть: 409 notify_secret_exists. Сменить его ключом API нельзя: меняют в кабинете мерчанта или у администратора.
  • Ответ не кешируется. Храните секрет как пароль, рядом с ключом API.
  • Свой предел частоты: 10 запросов в минуту с одного адреса.

Запрос

curl -sS -X POST https://api.paydex.co.uk/api/v1/notifications/secret \
  -H "Authorization: Bearer $PAYDEX_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Код и правилоКогда приходит и что делать
400validation_failed

Тело не прошло проверку формы: лишнее поле, значение не того вида (например, сумма числом JSON, а не строкой) или нет обязательного поля. details.issues называет поля.

Исправить тело по таблице полей.

Пример ответа
POST /api/v1/payments

HTTP/1.1 400

{
  "error": {
    "code": "validation_failed",
    "message": "Request body failed validation",
    "details": {
      "issues": [
        {
          "field": "amountMinor",
          "message": "Expected string, received number"
        }
      ]
    }
  }
}
409conflictnotify_secret_exists

У контура ключа секрет подписи уже есть: его выпустили этой ручкой, в кабинете мерчанта или администратор вместе с адресом контура. Повторно секрет не показывается.

Взять секрет там, где его выпустили. Потерянный секрет меняют в кабинете мерчанта (страница «Уведомления», с кодом из приложения) или у администратора; ключом API его не сменить.

Пример ответа
POST /api/v1/notifications/secret

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The notification signing secret of this environment has already been issued and is shown only once: a new one is issued in the merchant cabinet or by the administrator",
    "details": {
      "rule": "notify_secret_exists"
    }
  }
}
409conflictkeyring_not_loaded

На нашей стороне не загружены ключи, из которых выводится секрет подписи этого контура. Секрет не выпущен.

Повторить позже. Если повторяется, сообщить поддержке время запроса.

Пример ответа
POST /api/v1/notifications/secret

HTTP/1.1 409

{
  "error": {
    "code": "conflict",
    "message": "The encryption keys of this environment are not loaded on the server: the signing secret cannot be derived, retry later",
    "details": {
      "rule": "keyring_not_loaded"
    }
  }
}

API v1 · собрано 18.11.2026 · выпуск f13e6bf

Справочник методов собирается из кода сервера: он не описывает адрес, которого нет.