Транзакции

Сделка является основным объектом 4pay.online APIКаждый платеж, выплата и возврат - это транзакция.

База URL: https://4pay.online/api/v1/transactions

Создать транзакцию

POST /api/v1/transactions

Запрашивающий орган

{
  "params": {
    "type": "payment",
    "amount": "1000",
    "currency": "USD",
    "txid": "order-12345",
    "env": "test",
    "hosted": true,
    "returnUrl": "https://yoursite.com/success",
    "failUrl": "https://yoursite.com/fail"
  }
}

Параметры

Полное поле	Тип	Требуемый	Описание
`type`	string	✅	Тип сделки: `payment`, `payout`
`amount`	string	✅	Сумма в наименьшей валютной единице, в виде десятичной строки (`"1000"` = 10.00 USD)
`currency`	string	✅	ISO 4217 Код валюты`USD`, `EUR`, `USDT`, …)
`txid`	string	—	Ваш заказ IDСвободная форма; уникальная на одного партнераПозволяет импотенцию — см. ниже
`returnUrl`	string	—	Где плательщик приземляется после оплаты. Требуется для оплаты сервер-сервер; опционально для размещенных платежей и выплат
`failUrl`	string	—	Там, где плательщик приземляется после неудачи. `returnUrl`
`env`	string	✅	`prod` or `test`Должно быть внутри `params` см. ниже
`hosted`	boolean	—	`true` Отправляет плательщика на размещенную страницу. Нет никакого дефолта - см. ниже. `show_widget` Старый псевдоним для того же самого
`description`	string	—	Описание платежа, показанное плательщику
`customer`	object	—	Информация о плательщике: `{ email, phone, name }`
`lang`	string	—	UI Язык: `en`, `ru`, `ar`, `es`, …
`merchant_meta`	object	—	Ваши непрозрачные данные, возвращенные на считываниях и в веб-хуках без изменений

Ответ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "created",
  "type": "payment",
  "env": "test",
  "txid": "order-12345",
  "amount": "1000",
  "currency": "USD",
  "started": "2026-09-03 11:18:30.101839 Etc/UTC",
  "widget_url": "https://pay.4pay.online?id=550e8400-...&org_id=...&token=eyJhbGciOi..."
}

Перенаправить пользователя на widget_url Чтобы завершить платеж. token in it is a JWT действительный для о 15 минуты — быстро перенаправить и создать новую транзакцию, а не хранить URL.

опасность

hosted Нет никакого дефолта

Творение без hosted: true (or show_widget: true) рассматривается как сервер-сервер: Платформа ожидает детали карты в money_storageИ без них ответы 201 Created с "status": "rejected" и "error_description": "unexpected card"Ничего в этом HTTP статус Сказали, что в оплате было отказано.

Оплата сервер-сервер дополнительно требует оба returnUrl и failUrl; без них Он был создан и немедленно отвергнут. return_url/fail_url params not specified.

Таймштампы не являются ISO 8601

started и finished Возвращаясь как 2026-09-03 11:18:30.101839 Etc/UTC Пространство, где T принадлежит, шесть дробных цифр, названная зона. new Date(...) JavaScript возвращает недействительный дата; datetime.fromisoformat в Python поднимает; PHP считывает значение zoneless в собственном сервере Таймзона. SDK Правильно разбирается во всех трех.

Императивность

txid Любую струну вы выбираете, и она уникальна. на одного партнераПовторяя а Создать запрос с помощью a txid То, что уже существует, не создает второй Транзакция - вы получаете существующий обратно, снова с 201 и а location Два партнера в одной организации могут повторно использовать одно и то же txid Не сталкиваясь.

Транзакция, созданная без txid Идемпотенция отсутствует вообще: повторная попытка После тайм-аута производится вторая транзакция, а значит и второй платеж. Отправить a txid Все, что связано с деньгами.

Ограничения

Полное поле	Ограничение
`txid`	Up to 255 В более длинном значении отказано с `422`Не ошибка базы данных
`txid`	Случайно-чувствительный и хранимый точно так же, как отправленный - `ORDER-abc` и `order-abc` Это две разные сделки
`amount`	Он должен быть больше нуля. `"0"` Отрицательное значение обоих отрицается. `422`
`amount`	Произвольно-точная десятичная струна — 18-цифровое значение (1 ETH в Вей) принимается в качестве

предупреждать

Импотенция игнорирует все, кроме txid

Повторяя творение с тем же txid но различный amount Вновь возвращает оригинал транзакция, неизмененная, при ее первоначальной сумме. Новая сумма не применяется и никакой ошибки нет. Поднятый — прочитайте ответ вместо того, чтобы предполагать последний amount Вступил в силу.

окружающая среда

Отправить env внутри params. A ?env= параметр запроса выбирает окружающей среды листинг или поиск в поиске; он не устанавливает среду Создается транзакция. Запрос на создание выполняется только ?env=test производит производство Сделка. Когда оплата Вместо этого нужно что-то от плательщика среднего потока, действие приходит в auth_params - Смотри. Универсальный протокол транзакций.

Получить транзакцию

GET /api/v1/transactions/:id

curl https://4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

Ответ

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "charged",
  "txid": "order-12345",
  "amount": "1000",
  "amount_with_fee": "1050",
  "amount_dest": "950",
  "currency": "USD",
  "currency_dest": "USD",
  "started": "2026-03-01T10:00:00Z",
  "finished": "2026-03-01T10:05:00Z"
}

Количество полей

Полное поле	Описание
`amount`	Первоначальная сумма сделки (что плательщик платит)
`amount_with_fee`	Сумма, включая плату за платформу
`amount_dest`	Выплата (после вычета суммы)

Перечень операций

GET /api/v1/transactions

curl "https://4pay.online/api/v1/transactions?status=charged&limit=50" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

Параметры запросов

Параметр	Тип	Описание
`status`	string	Фильтр по статусу
`type`	string	Фильтр по типу: `payment`, `payout`
`env`	string	`prod` or `test` Какую среду искать
`limit`	integer	Результаты на странице (по умолчанию): 20Максимум: 100)
`cursor`	string	`cursor_value` из предыдущего ответа - см. paging ниже
`started_from`, `started_to`	ISO 8601	Связанные со временем создания
`updated_from`, `updated_to`	ISO 8601	Связи с последним обновлением
`finished_from`, `finished_to`	ISO 8601	Границы по завершении
`amount_from`, `amount_to`	string	Связи по сумме, в незначительных единицах
`order_by`	string	`started` (неисправность) или `updated`
`rrn`	string	Справочный номер поиска
`link_id`	uuid	Платежи, произведенные по одной платежной ссылке

Все, чего нет в этом столе, отвергается. 422 Unexpected field в том числе page, offset, from, to и currencyВсе они выглядят правдоподобно, и ни один из них не существует.

Пейджинг

Ответы содержат a cursor Блокировать; пройти его cursor_value назад как cursor Чтобы получить следующую страницу.

{
  "data": [ … ],
  "cursor": { "cursor_field": "started", "cursor_value": "2026-09-03T11:20:45.377937Z" }
}

curl "https://4pay.online/api/v1/transactions?env=test&limit=50&cursor=2026-09-03T11:20:45.377937Z" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

Страница, чья cursor_value is null Это последний.

Две бесшумные ловушки в списке

start_cursor принимается, а затем игнорируемый если только end_cursor Приходит с ним (это пара) В оконном считывании. start_cursor Одиноко перечитывает первую страницу навсегда и выглядит точно Как будто «больше ничего нет».

txid Также принимается из ключа партнера и игнорируется, возвращая весь список, а не Один заказ. Держите платформу. id Вы получили звонок от создателя и прочли его обратно GET /api/v1/transactions/:id.

Совокупные сделки

Получите сводную статистику по нескольким транзакциям:

GET /api/v1/transactions/aggregate

curl "https://4pay.online/api/v1/transactions/aggregate?currency=USD&status=charged" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

Обновить транзакцию

Использовать PUT /api/v1/transactions/:id Выдать возврат или отменить транзакцию.

Возврат

curl -X PUT https://4pay.online/api/v1/transactions/550e8400-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "params": {
      "type": "refund",
      "amount": "500"
    }
  }'

Омить amount для полного возврата.

отменять

curl -X PUT https://4pay.online/api/v1/transactions/550e8400-... \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444" \
  -d '{
    "params": {
      "type": "cancel"
    }
  }'

Двухфазные платежи (Authorize + Capture)

Для провайдеров, которые поддерживают двухфазный режим, сначала создайте type: "payment" - средства удерживаются, но не захватываются.

POST /api/v1/transactions/commit/:id

curl -X POST https://4pay.online/api/v1/transactions/commit/550e8400-... \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: 00000000-1111-2222-3333-444444444444"

3DS / Дополнительная аутентификация

Когда транзакция требует дополнительной аутентификации3-D Безопасный, одноразовый пароль, подпись кошелька, его статус становится action_required и тот Транзакция несет в себе само действие auth_params - Нет, нет. action_required Осуществляйте действие, описанное в Спецификация протокола. Материал, который плательщик должен подписать или заполнить, поступает в additional_params_for_authС одной стороны expires_at После чего он должен быть Запросить еще раз. Представить результат:

POST /api/v1/transactions/additional_params_for_auth/:id

{
  "params": {
    "otp": "123456"
  }
}

Жизненный цикл транзакций

created
  └─► charging                     processing
        ├─► action_required        payer action needed, then back to charging
        ├─► charged           ✅   settled
        ├─► rejected          ❌   no routing, limits or anti-fraud
        └─► failed            ❌   provider error, or cancelled before settlement
  └─► cancelled                    cancelled before processing started

charged
  ├─► reversed                     a settled transaction was returned
  └─► refunded                     refund completed

charged, rejected, failed и reversed Все остальное значит, что все остальное - это конец. Сделка все еще находится в полете.

reversed Только последует charged Возвращение устоявшегося Сделка, а не отмена. Отмена до прибытия урегулирования failed.

Транзакции

Создать транзакцию​

Запрашивающий орган​

Параметры​

Ответ​

Императивность​

Ограничения​

окружающая среда​

Получить транзакцию​

Ответ​

Количество полей​

Перечень операций​

Параметры запросов​

Пейджинг​

Совокупные сделки​

Обновить транзакцию​

Возврат​

отменять​

Двухфазные платежи (Authorize + Capture)​

3DS / Дополнительная аутентификация​

Жизненный цикл транзакций​

Создать транзакцию

Запрашивающий орган

Параметры

Ответ

Императивность

Ограничения

окружающая среда

Получить транзакцию

Ответ

Количество полей

Перечень операций

Параметры запросов

Пейджинг

Совокупные сделки

Обновить транзакцию

Возврат

отменять

Двухфазные платежи (Authorize + Capture)

3DS / Дополнительная аутентификация

Жизненный цикл транзакций