Пополнения — документация API

[01]

Один endpoint, разные профили

P2P и ECOM H2H могут использовать один хост, но их спецификации различаются. Выбирайте сценарий, назначенный вашему pipeline: одно имя хоста не определяет правильную схему запроса.

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

Отдельные профили готовой карточной формы и оплаты по токену используют init.paystar.uk и token.paystar.uk соответственно. Используйте хост, назначенный вашей интеграции.

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

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

Общая коллекция Postman содержит шаблоны P2P, готовой формы H2C и пополнения по токену, а также отдельно названный запрос ECOM H2H на том же secure-endpoint пополнения. Шаблоны ECOM H2H/H2C от владельца API показывают обезличенные тела запросов и используют отдельные учётные данные. Это примеры, а не полные спецификации профилей или готовые тестовые карточные данные.

Общие поля запроса

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

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

HTTP	Значение
`200`	Заявка на пополнение создана. Проверьте orderStatus: HTTP 200 может содержать результат обработки Failed и не означает успешный платёж.
`400`	Запрос не прошёл проверку, достигнут настроенный лимит или ID заявки мерчанта уже существует. Для этих типовых примеров владелец API подтвердил HTTP 400. Неизвестная валюта в Deposit H2H/H2C остаётся отдельным ответом HTTP 423 по CUR-002. BusinessError и обработка
`401`	Отсутствует или недействителен Bearer-токен пополнений.
`403`	Ключ действителен, но не имеет доступа к этой возможности пополнения.
`415`	Неподдерживаемый тип содержимого. Ошибка уровня фреймворка до бизнес-обработки PayStar.
`423`	Бизнес-ошибка: для неизвестной валюты Deposit H2H/H2C сохраняются statusDescrption 2-00100-2, code 1.2.4.9 и утверждённое владельцем API сообщение Currency value "{currencyKey}" is unknown. Отдельная общая ошибка маршрутизации использует HTTP 423, statusDescrption 0000-2 и code 1.2.4.3, что подтверждено в CREATE-HTTP-001. См. x-paystar-create-payload-examples и x-paystar-deposit-currency-errors. BusinessError и обработка
`500`	Внутренняя ошибка сервера. BusinessError и обработка

[02]

Пополнение P2P · H2H/H2C

Поля подтверждены владельцем APIЗафиксировано в тестовой среде · 7 сен 2026

При H2H-интеграции шлюза один запрос создания P2P возвращает и платёжные реквизиты, и URL платёжной формы PayStar. Мерчант может показать реквизиты на своей странице оплаты (H2H) или направить клиента на возвращённую форму PayStar (H2C), не создавая новую заявку и не меняя запрос.

Продолжайте использовать назначенный адрес secure.paystar.uk для этого endpoint. Этот выбор мерчанта отличается от профиля готовой карточной формы H2C ниже. Все три URL перенаправления обязательны; callbackUrl остаётся необязательным.

Поля запроса и cURL

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

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

additionalFields — массив объектов. Каждый объект содержит key (имя поля) и value (его значение). Используйте указанный для поля тип: string, number или boolean; null не является допустимым значением элемента.

В примере есть payeerIdentifier— ваш идентификатор плательщика/клиента. Он часто обязателен, но не для каждого терминала и может быть не единственным нужным полем. В новых примерах используется lowerCamelCase.

Структура массива: key и value

Поле Обязательность Тип и значение

Поле	Обязательность	Тип и значение
`key`	Обязательно	`string` Документированное стандартное написание — lowerCamelCase. minLength: 1
`value`	Обязательно	`string \| number \| boolean` Скалярное значение, зависящее от сценария. Наличие и значение не null — нормативные требования; форматы и диапазоны задаются схемой выбранного сценария. AdditionalFieldValue

key

Обязательно

string

Документированное стандартное написание — lowerCamelCase.

minLength: 1

value

Обязательно

string | number | boolean

Скалярное значение, зависящее от сценария. Наличие и значение не null — нормативные требования; форматы и диапазоны задаются схемой выбранного сценария.

AdditionalFieldValue

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

{
  "additionalFields": [
    {
      "key": "payeerIdentifier",
      "value": "Merch-Customer-12345"
    }
  ]
}

Открыть каталог дополнительных полей →

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

curl --request POST \
  --url 'https://secure.paystar.uk/api/v1/integration/deposit-order/' \
  --header 'Authorization: Bearer <PAYSTAR_P2P_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100.00,
  "currency": "RUB",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "callbackUrl": "https://merchant.example/paystar/callback",
  "processingRedirectUrl": "https://merchant.example/payment/processing",
  "failedRedirectUrl": "https://merchant.example/payment/failed",
  "successRedirectUrl": "https://merchant.example/payment/success",
  "additionalFields": [
    {
      "key": "payeerIdentifier",
      "value": "Merch-Customer-12345"
    }
  ]
}'

Ответ о принятии и следующий шаг

Поле Обязательность Тип и значение

externalId Обязательно string

orderStatus Обязательно string · Processing

paymentDetails

Обязательно

object

Для P2P с H2H-интеграцией шлюза платёжные реквизиты и URL формы PayStar возвращаются вместе (P2P-FORM-001, подтверждено владельцем API 2026-09-10).

P2PPaymentDetails

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "card": "<REDACTED_PAYMENT_DETAIL>",
    "fio": "<RECIPIENT_NAME>",
    "bank": "<BANK_NAME>",
    "formUrl": "https://p2p.paystar.uk/?EXAMPLE_ONLY"
  }
}

Покажите возвращённые платёжные реквизиты на своей странице оплаты или откройте возвращённый paymentDetails.formUrl для клиента. Корректный ответ о принятии P2P содержит этот URL со значением не null. Параметры запроса в примере условные: используйте полный URL из API и защищайте его одноразовые параметры. Сохраните оба ID и отслеживайте статус той же заявки.

Поля платёжных реквизитов

Сопоставляйте платёжные реквизиты с точным полем ответа, а не с ключом additionalFields запроса или видом значения. Регистр имён полей имеет значение.

Платёжный реквизит	Путь в ответе	Примечания к сопоставлению
Карта	`paymentDetails.card`	Существующее сопоставление карты; альтернативные реквизиты не обязательно находятся в card.
IBAN	`paymentDetails.iban`	Строка в примере владельца API.
Номер счёта	`paymentDetails.accountNumber`	Не `paymentDetails.bankAccount`. Сохраняйте строку и ведущие нули.
QR	`paymentDetails.qrUrl`	Владелец API описывает содержимое как Base64. Не считайте его HTTP URL по имени поля. Может сопровождать `accountNumber`.
Название метода	`paymentDetails.method`	Пример: `ArsCbu`. Это не полный enum и не уникальный признак типа ответа.
PhoneNumber	`paymentDetails.number`	Строка в примере владельца API, несмотря на имя `number`. Сохраняйте знак плюса; не используйте `phoneNumber` и не делайте вывод о числовом типе.

Пример ответа с номером телефона

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "fio": "<RECIPIENT_NAME>",
    "bank": "<BANK_NAME>",
    "number": "<RECIPIENT_PHONE_NUMBER>",
    "formUrl": "https://checkout.example/EXAMPLE_ONLY"
  }
}

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

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "fio": "<RECIPIENT_NAME>",
    "iban": "<IBAN>",
    "formUrl": "https://checkout.example/EXAMPLE_ONLY"
  }
}

Пример ответа с номером счёта

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "fio": "<RECIPIENT_NAME>",
    "method": "ArsCbu",
    "formUrl": "https://checkout.example/EXAMPLE_ONLY",
    "accountNumber": "<ACCOUNT_NUMBER>"
  }
}

Пример ответа с QR и номером счёта

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "qrUrl": "<BASE64_QR_DATA>",
    "fio": "<RECIPIENT_NAME>",
    "method": "ArsCbu",
    "formUrl": "https://checkout.example/EXAMPLE_ONLY",
    "accountNumber": "<ACCOUNT_NUMBER>"
  }
}

Справочник полей

Поле	Обязательность	Тип и значение
`card`	Необязательно	`string \| null` Чувствительный платёжный реквизит; скрывайте его в сохраняемых материалах проверки.
`fio`	Необязательно	`string \| null`
`bank`	Необязательно	`string \| null`
`formUrl`	Обязательно	`string · uri` Обязательный URI платёжной формы PayStar со значением не null в корректном ответе о принятии P2P. Мерчант может использовать эту форму H2C вместо самостоятельного показа возвращённых реквизитов. Используйте полный возвращённый URL, а не условный запрос EXAMPLE_ONLY. Никогда не записывайте одноразовые токены из URL в логи.
`number`	Зависит от профиля · правила не подтверждены	`string in owner examples · constraints pending` Телефон получателя для оплаты в paymentDetails.number, а не phoneNumber или card. В примере владельца API это строка; сохраняйте знак плюса и значение в полученном виде. Нельзя выводить отсюда правила числового преобразования, E.164, длины, обязательности или допустимости null.
`iban`	Зависит от профиля · правила не подтверждены	`string in owner examples · constraints pending` IBAN для оплаты в paymentDetails.iban. Сохраняйте строковый тип. Подтверждён примером владельца API, но не является универсальным обязательным полем.
`accountNumber`	Зависит от профиля · правила не подтверждены	`string in owner examples · constraints pending` Номер счёта для оплаты в paymentDetails.accountNumber, а не bankAccount. Сохраняйте строку точно как получена, включая ведущие нули. Может присутствовать вместе с qrUrl, как в примере владельца API.
`qrUrl`	Зависит от профиля · правила не подтверждены	`string in owner examples · constraints pending` Содержимое QR в paymentDetails.qrUrl. Владелец API обозначает значение как Base64; несмотря на имя поля, HTTP URL не подтверждён. Фактические байты QR, MIME-тип и оболочка — чистый Base64 или data URI — не подтверждены.
`method`	Зависит от профиля · правила не подтверждены	`string in owner examples · constraints pending` Название метода в paymentDetails.method. ArsCbu — пример владельца API, а не полный enum или уникальный признак варианта ответа.

Проверить статус пополнения →

Неуспешный ответТиповые тела 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 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 ↓

[03]

Карточный эквайринг · ECOM H2H

Запрос и ответ от владельца APIПолную спецификацию профиля ещё нужно подтвердить

Прямой сбор карточных данных требует согласованной интеграции и границ соблюдения требований. В примере владельца API ниже карточные поля находятся внутри additionalFields; это не схема запроса P2P.

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

P2P и ECOM H2H используют POST https://secure.paystar.uk/api/v1/integration/deposit-order/. Это разные варианты сценария/профиля: используйте учётные данные, тело запроса и обработку ответа, назначенные выбранному профилю. Пример P2P не является шаблоном ECOM. В H2H-примере владельца API отсутствует завершающий слеш; это обновление не проверяет перенаправления или поведение алиасов.

В разделе загрузок откройте общую Коллекция Postman и выберите Create ECOM H2H Deposit — owner-provided template. Используйте окружение для конкретного профиля.

ECOM H2H — запрос и ответ владельца APIПредоставлено владельцем API · 10 сен 2026

Запрос Postman: Create ECOM H2H Deposit — owner-provided template. Точное написание ключей additionalFields из примера владельца API сохранено; общие указания по совместимости lowerCamelCase не меняются.

cURL · обезличенный пример владельца APIВыделите текст для копирования

curl --request POST \
  --url 'https://secure.paystar.uk/api/v1/integration/deposit-order' \
  --header 'Authorization: Bearer <PAYSTAR_ECOM_H2H_TOKEN>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
  "amount": 20.00,
  "currency": "AZN",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "failedRedirectUrl": "https://merchant.example/failed",
  "processingRedirectUrl": "https://merchant.example/processing",
  "successRedirectUrl": "https://merchant.example/success",
  "callbackUrl": "https://merchant.example/callback",
  "additionalFields": [
    {
      "key": "PayeerIdentifier",
      "value": "MERCHANT_CUSTOMER_ID"
    },
    {
      "key": "CardNumber",
      "value": "<APPROVED_CARD_NUMBER>"
    },
    {
      "key": "CardExpireYear",
      "value": "30"
    },
    {
      "key": "CardExpireMonth",
      "value": "06"
    },
    {
      "key": "CardCvv",
      "value": "<APPROVED_CARD_CVV>"
    },
    {
      "key": "CardHolder",
      "value": "<CARDHOLDER_NAME>"
    }
  ]
}'

JSON · тело ответа владельца API; HTTP не указанВыделите текст для копирования

{
  "externalId": "aaaaaaaa-aaaa-4aaa-8aaa-aaaaaaaaaaaa",
  "orderStatus": "Processing",
  "paymentDetails": {
    "formUrl": "https://redirect.example/EXAMPLE_ONLY",
    "flowData": {
      "action": "https://gateway.example/redirect?token=EXAMPLE_ONLY",
      "method": "GET",
      "params": [
        {
          "name": "token",
          "value": "EXAMPLE_ONLY"
        }
      ],
      "metadata": {
        "description": "Redirect the user to complete payment",
        "type": "redirect"
      },
      "instruction": {
        "type": "query"
      }
    }
  }
}

Путь в ответе	Смысл и границы
`paymentDetails.formUrl`	Ссылка оплаты/перенаправления, возвращённая PayStar.
`paymentDetails.flowData.action`	URL действия шлюза; уже может содержать параметры запроса.
`paymentDetails.flowData.method`	GET в этом примере; не закрытый enum методов.
`paymentDetails.flowData.params`	Параметры имя/значение; в этом примере используется token.
`paymentDetails.flowData.metadata`	description и type поясняют действие в этом примере.
`paymentDetails.flowData.instruction.type`	query в этом примере; другие варианты инструкции не установлены.

В примере токен повторён в action и params. Сборка URL, приоритет перенаправлений и другие варианты flowData требуют подтверждения; не делайте вывод, что токен нужно добавлять дважды.

Пример задаёт поля и значения, а не полный список обязательных полей, схему ответа или соответствие кодам HTTP. При этом обновлении документации запросы и перенаправления не выполнялись.

Коллекция использует {{merchantOrderId}} напрямую как externalTransactionId. Для проверки статуса сохраните этот ID и передайте depositStatusToken с доступом к той же заявке. Прежняя переменная окружения ecomRequestBody остаётся пустой для совместимости импорта и больше не используется этим шаблоном.

Спецификацию профиля ещё нужно подтвердить

Пример не устанавливает универсальные обязательные поля, правила проверки карты и срока действия, HTTP-статус, все варианты ответов или приоритет formUrl и flowData. Уточните их для назначенного профиля. Значения карты/токена/перенаправления здесь — заглушки: не отправляйте их и не храните реальные PAN/CVV и одноразовые токены в коллекциях или выгрузках.

Спецификация ECOM и открытые вопросы тестовой среды →

Открытые вопросы ECOM в загрузках → — примеры владельца API доступны, но полная нормативная схема ECOM и готовые тестовые карточные данные не включены.

Неуспешный ответТиповые тела 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 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 ↓

[04]

Готовая платёжная форма · H2C

Документированный сценарийУспешный сценарий ещё не проверен

Карта вводится в готовой форме, а не на странице мерчанта. Это может уменьшить область применимости PCI DSS; фактические границы соответствия нужно подтвердить для интеграции.

POSThttps://init.paystar.uk/api/v1/integration/deposit-order/

ECOM H2C — запрос и ответ владельца APIПредоставлено владельцем API · 10 сен 2026

Запрос Postman: Create ECOM H2C Deposit — owner-provided template. Точное написание ключей additionalFields из примера владельца API сохранено; общие указания по совместимости lowerCamelCase не меняются.

cURL · обезличенный пример владельца APIВыделите текст для копирования

curl --request POST \
  --url 'https://init.paystar.uk/api/v1/integration/deposit-order/' \
  --header 'Authorization: Bearer <PAYSTAR_ECOM_H2C_TOKEN>' \
  --header 'Content-Type: application/json; charset=utf-8' \
  --data '{
  "amount": 50.00,
  "currency": "AZN",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "failedRedirectUrl": "https://merchant.example/failed",
  "processingRedirectUrl": "https://merchant.example/processing",
  "successRedirectUrl": "https://merchant.example/success",
  "callbackUrl": "https://merchant.example/callback",
  "additionalFields": [
    {
      "key": "PayeerIdentifier",
      "value": "MERCHANT_CUSTOMER_ID"
    }
  ]
}'

JSON · тело ответа владельца API; HTTP не указанВыделите текст для копирования

{
  "externalId": "bbbbbbbb-bbbb-4bbb-8bbb-bbbbbbbbbbbb",
  "orderStatus": "Init",
  "formUrl": "https://checkout.example/EXAMPLE_ONLY"
}

Путь в ответе	Смысл и границы
`formUrl`	URL готовой платёжной формы на корневом уровне, а не paymentDetails.formUrl.
`orderStatus`	Init в этом примере владельца API.

В этом примере владельца API используется PayeerIdentifier. Другой ранее проверенный профиль готовой формы требовал FirstName; требования additionalFields по-прежнему зависят от терминала.

Пример задаёт поля и значения, а не полный список обязательных полей, схему ответа или соответствие кодам HTTP. При этом обновлении документации запросы и перенаправления не выполнялись.

Другой профиль готовой формы — пример запроса firstName

В разделе загрузок откройте общую Коллекция Postman и выберите Create Hosted H2C Deposit — illustrative configured firstName. Используйте окружение для конкретного профиля.

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

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

curl --request POST \
  --url 'https://init.paystar.uk/api/v1/integration/deposit-order/' \
  --header 'Authorization: Bearer <PAYSTAR_H2C_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100.00,
  "currency": "USD",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "additionalFields": [
    {
      "key": "firstName",
      "value": "Example"
    }
  ]
}'

Документированный ответ и переход клиента

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

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Init",
  "formUrl": "https://checkout.example/REPLACE_WITH_RETURNED_URL"
}

Откройте возвращённый URL для клиента, защитите одноразовые параметры и отслеживайте статус. Пример иллюстрирует схему, а не живой ответ H2C.

Неуспешный ответТиповые тела 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 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 ↓

[05]

Пополнение по токену

Документированный сценарийРабочее подключение ещё не подтверждено

Используйте PayStar cardStorageToken согласованного профиля оплаты по токену. Банковский cardToken не является его заменой.

POSThttps://token.paystar.uk/api/v1/integration/deposit-order/

Первый платёж → сохранённый токен → следующий платёж

Завершите подходящий первый платёж в назначенном сценарии.
Получите PayStar cardStorageToken через согласованные данные статуса/callback, если профиль это поддерживает.
Безопасно сохраните его с привязкой к правильному клиенту.
Передайте токен для следующего платежа и обработайте необходимое действие клиента.

Срок действия токена, условия повторного использования и шаг клиента требуют подтверждения профиля. Токенизация не гарантирует полностью автоматический платёж или отсутствие обязательств PCI.

Поля запроса и cURL

В разделе загрузок откройте общую Коллекция Postman и выберите Create Tokenized Deposit — onboarding pending. Используйте окружение для конкретного профиля.

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

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

curl --request POST \
  --url 'https://token.paystar.uk/api/v1/integration/deposit-order/' \
  --header 'Authorization: Bearer <PAYSTAR_TOKENIZED_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "amount": 100.00,
  "currency": "USD",
  "externalTransactionId": "UNIQUE_MERCHANT_ID",
  "additionalFields": [
    {
      "key": "cardStorageToken",
      "value": "<APPROVED_STORED_TOKEN>"
    }
  ]
}'

Документированный ответ

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

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

{
  "externalId": "<PAYSTAR_ORDER_ID>",
  "orderStatus": "Processing",
  "paymentDetails": {
    "formUrl": "https://checkout.example/REPLACE_WITH_RETURNED_URL"
  }
}

Отслеживайте результат через назначенный метод статуса →

Неуспешный ответТиповые тела 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 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 ↓

[06]

Отслеживайте результат пополнения

Сохраните исходный идентификатор мерчанта externalTransactionId и идентификатор PayStar externalId из ответа создания заявки. Используйте соответствующую проверку:

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

Используйте учётные данные и хост статуса вашего профиля пополнений. При подключении уточните поддержку готовой формы H2C и профиля оплаты по токену.

Опрос статуса и восстановление после создания с неизвестным результатом →

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