PAYSTAR / ДОКУМЕНТАЦИЯ ДЛЯ РАЗРАБОТЧИКОВ

Выплаты

Создайте вывод средств с полями и учётными данными, назначенными вашему pipeline выплат.

[01]

Создать выплату H2H

Используйте учётные данные pipeline выплат. Обязательные дополнительные поля, доступные валюты и лимиты зависят от профиля.

POSThttps://secure.paystar.uk/api/v1/integration/withdrawal-order/

Файлы в разделе загрузок: OpenAPI JSON · YAML · Коллекция Postman · Окружение Postman.

Справочные файлы: Дополнительные поля · Валюты · Ошибки и особенности обработки.

Спецификация запроса

Поле	Обязательность	Тип и значение
`amount`	Обязательно	`number` Сумма в основных единицах валюты. Нормативный тип — JSON number; числовые строки в кавычках сохраняются для обратной совместимости. Обычные запросы и показанные примеры используют два знака после запятой. Минимумы/максимумы конкретного сценария задаются в маршрутизации. exclusiveMinimum: 0 Amount
`currency`	Обязательно	`string` Ключ валюты в виде строки, без проверки длины или шаблона написания. Можно передать значения вроде USDT_TRC20; это не гарантирует, что значение известно или включено. При создании платежа PayStar сначала ищет точное переданное значение во внутреннем справочнике валют, затем ищет маршрут по условиям pipeline. Используйте ключ валюты, предоставленный для вашей интеграции. Фиат обычно использует коды ISO 4217 alpha-3; криптовалюта может использовать ключ актива/сети. Обязательность поля и бизнес-ошибки отдельных операций не меняются. CurrencyCode
`externalTransactionId`	Обязательно	`string` Уникальный идентификатор, созданный мерчантом, для проверки статуса и безопасного решения о повторе запроса. minLength: 1 ExternalTransactionId
`callbackUrl`	Необязательно	`string · uri`
`additionalFields`	Необязательно	`array of object` Обязательный набор ключей настраивается для мерчанта и сценария. Уточните его у менеджера PayStar.

Пример запроса выплаты на карту

В разделе загрузок откройте общую Коллекция Postman и выберите Create Payout — approved destination fixture required. Используйте окружение для конкретного профиля.

cURLВыделите текст для копирования

curl --request POST \
  --url 'https://secure.paystar.uk/api/v1/integration/withdrawal-order/' \
  --header 'Authorization: Bearer <PAYSTAR_PAYOUT_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100.00,
  "currency": "RUB",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "additionalFields": [
    {
      "key": "cardNumber",
      "value": "<APPROVED_TEST_FIXTURE>"
    }
  ]
}'

Ответ о принятии

Поле	Обязательность	Тип и значение
`externalId`	Обязательно	`string`
`orderStatus`	Обязательно	`string · Created`

JSONВыделите текст для копирования

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Created"
}

Неуспешный ответТиповые тела JSON

Это типовые примеры для данного сценария, а не полный список ошибок API; требования конкретного профиля сохраняются. Коды HTTP для этих примеров подтверждены владельцем API. Для ответов без тела пример JSON не приводится.

HTTP 200 · Заявка создана, обработка неуспешнаЗаявка создана

Запрос создал заявку, но обработка завершилась неуспешно. Сохраните PayStar externalId и исходный ID заявки мерчанта. Это не отказ без создания заявки.

HTTP: 200

JSON · тело ответа HTTP 200Выделите текст для копирования

{
  "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "orderStatus": "Failed"
}

HTTP 200 означает создание заявки, а не успешный платёж. Это тело использует orderStatus, а не status, и не содержит платёжных реквизитов или URL формы. Проверьте orderStatus и сохраните оба идентификатора заявки.

HTTP 423 · Нет подходящего канала или маршрутаНовая заявка не создана

Валюта, сумма или другие параметры запроса не соответствуют доступным условиям маршрутизации этого pipeline. Заявка не создаётся.

HTTP: 423

JSON · тело ответа HTTP 423Выделите текст для копирования

{
  "label": "TEMPORARY_ERROR",
  "message": "TEMPORARY_ERROR",
  "statusDescrption": "0000-2",
  "externalTransactionId": null,
  "code": "1.2.4.3"
}

HTTP 422 · Недостаточный балансНовая заявка не создана

Недостаточно средств для создания выплаты. Заявка не создаётся.

HTTP: 422

JSON · тело ответа HTTP 422Выделите текст для копирования

{
  "label": "TEMPORARY_ERROR",
  "message": "TEMPORARY_ERROR",
  "statusDescrption": "1-4010",
  "externalTransactionId": null,
  "code": "1.1.4.3"
}

Уточните у менеджера, о каком балансе идёт речь: само тело ответа не определяет счёт или кошелёк.

HTTP 400 · Достигнут настроенный лимитНовая заявка не создана

Достигнут настроенный лимит. Заявка не создаётся.

HTTP: 400

JSON · тело ответа HTTP 400Выделите текст для копирования

{
  "label": "LIMITS_ERROR",
  "message": "Limit id: aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa was reached",
  "statusDescrption": "0001-0",
  "externalTransactionId": null
}

ID лимита приведён для примера. В этом примере нет поля code; не определяйте ошибку по конкретному UUID или точному тексту сообщения.

HTTP 400 · Повтор ID заявки мерчантаНовая заявка не создана

Заявка с этим ID мерчанта уже существует. Отклонённая попытка не создаёт новую заявку.

HTTP: 400

JSON · тело ответа HTTP 400Выделите текст для копирования

{
  "label": "VALIDATION_ERROR",
  "message": "Order with this external_transaction_id already exist",
  "statusDescrption": "1-4007",
  "externalTransactionId": null,
  "code": "1.1.5.1"
}

Запросите существующую заявку по исходному externalTransactionId из вашего запроса, даже если в этой ошибке externalTransactionId равен null. Не меняйте ID для слепого повтора.

HTTP 400 · Отсутствует обязательный параметрНовая заявка не создана

Отсутствует поле, обязательное по настройке терминала. Заявка не создаётся.

HTTP: 400

JSON · тело ответа HTTP 400Выделите текст для копирования

{
  "label": "VALIDATION_ERROR",
  "message": "additionalField BankAccount not found in request data. Description: Beneficiary’s bank account number, e.g. 1234567890",
  "statusDescrption": "0000-0",
  "externalTransactionId": null,
  "code": "1.2.4.8"
}

BankAccount — пример настроенного требования, а не обязательное поле всех сценариев. Используйте список обязательных полей вашего терминала.

Неизвестная валюта → · HTTP-ответы и транспортные ошибки → · Скачать каталог ошибок и примеры тел ответов · JSON ↓

HTTP-результаты

HTTP	Значение
`200`	Заявка на выплату создана. Проверьте orderStatus: HTTP 200 может содержать результат обработки Failed и не означает успешный платёж.
`400`	Запрос не прошёл проверку, достигнут настроенный лимит или ID заявки мерчанта уже существует. Для этих типовых примеров владелец API подтвердил HTTP 400. Валюта не проверяется по длине или шаблону написания; этот ответ не задаёт маску alpha-3. BusinessError и обработка
`401`	Отсутствует или недействителен Bearer-токен выплат.
`403`	Ключ действителен, но не имеет доступа к этой возможности выплаты.
`415`	Неподдерживаемый тип содержимого. Ошибка уровня фреймворка до бизнес-обработки PayStar.
`422`	Недостаточно средств для создания выплаты. Заявка не создаётся. HTTP 422 подтверждён владельцем API в CREATE-HTTP-001; ошибка относится только к выплатам. BusinessError и обработка
`423`	Валюта, сумма или другие параметры запроса не соответствуют доступным условиям маршрутизации этого pipeline. Заявка не создаётся. HTTP 423 подтверждён владельцем API в CREATE-HTTP-001. BusinessError и обработка
`500`	Внутренняя ошибка сервера. BusinessError и обработка

[02]

Отслеживайте результат выплаты

Сохраните возвращённый ID PayStar и исходный ID мерчанта. Оба метода проверки статуса доступны в базовой версии.

Статус выплаты по ID мерчанта →
Статус выплаты по ID PayStar →

Текущие проверки выплат и расследование 422 →

Файлы в разделе загрузок: Статусы заявок · История платежей.

Нужны обязательные поля, валюты или лимиты для вашего pipeline?

Уточнить профиль у Егора ↗