Быстрый старт — ваш первый платеж 15 Минуты

Это руководство берет оплату из ничего, чтобы рассчитаться. Не требуется предварительного знания платформы.

Предпосылки

Ваш оператор выдает два значения вместе, и вам нужны оба:

an API ключ (Район партнеров) Настройки → API Ключи);
тот организация id Ключ живет внутри.

Плюс curlили любой HTTP Быстрее, чем раньше. SDK То же самое делают четыре Звонки в дюжине строк.

Песочница первый

Интегрировать против https://sandbox.4pay.online и переключай хозяина, когда будешь жить. Это та же платформа с смоделированными провайдерами — см. Песочница и тестирование.

Шаг вперед 1 Проверьте свою связь

curl https://sandbox.4pay.online/api/v1/health

{
  "core_status": "ok",
  "db_status": "ok",
  "appversion": "f0175d14",
  "env": "sandbox",
  "domain": "sandbox.4pay.online"
}

Готовность - это core_statusНе существует поля, называемого status.

Шаг вперед 2 - Создать платеж

curl -X POST https://sandbox.4pay.online/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -d '{
    "params": {
      "type": "payment",
      "amount": "1000",
      "currency": "USD",
      "txid": "order-12345",
      "env": "test",
      "hosted": true,
      "returnUrl": "https://yoursite.com/success",
      "failUrl": "https://yoursite.com/fail"
    }
  }'

опасность

hosted Нет дефолта — установите его

Оставить hosted Запрос был прочитан как сервер-серверПлатформа ищет карты Подробности, ничего не находит и отвечает 201 Created с "status": "rejected" и "error_description": "unexpected card"Это самая распространенная причина, по которой первый Интеграция производит транзакции, которые никогда не взимают плату.

Формат суммы

amount — строка, содержащая сумму в минимальных единицах валюты (центах, пенсах, копейках). "1000" = $10.00 USD. Строка необходима, поскольку активы с восемнадцатью десятичными знаками нельзя безопасно передать как JSON number: отправляйте "1000", а не 1000.

Ответ:

{
  "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.sandbox.4pay.online?id=550e8400-...&org_id=...&token=eyJhbGciOi..."
}

Перенаправить плательщика на widget_url - размещенная страница оплаты, где они вводят свою карту. Сервер никогда не касается данных карты, что удерживает вас от этого. PCI DSS масштаб.

Три вещи об этом ответе

widget_url истекает примерно в 15 минуты. Его token является недолговечным JWTПеренаправление Немедленно; никогда не храните URL Если плательщик вернется завтра, создайте Новая транзакция.

201 Created Это не значит принятый. Маршрутизация, ограничения и борьба с мошенничеством - все отказываются от оплаты Создавая его как rejectedПрочитайте. status В каждом ответе, а не только в HTTP Код.

Таймштампы не являются ISO 8601. started и finished Прибытие как 2026-09-03 11:18:30.101839 Etc/UTC Пространство вместо TБольшинство парсеров дат Верните недействительный день; некоторые молча читают его как местное время. SDK Справится с этим.

Шаг вперед 3 Проверьте статус транзакции

curl https://sandbox.4pay.online/api/v1/transactions/550e8400-e29b-41d4-a716-446655440000 \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID"

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

Статус сделки:

статус	Финал	Значение
`created`, `new`	no	Созданный, еще не раскрученный
`authorizing`	no	быть уполномоченным
`action_required`	no	Плательщик должен что-то делать.
`charging`	no	быть обработаны поставщиком
`charged`	да.	Устанавливается ⁇
`rejected`	да.	Отказано до или поставщиком - средства, выпущенные
`failed`	да.	Ошибка обработки или аннулирование до урегулирования - средства, выпущенные
`reversed`	да.	Оплаченный платеж был возвращен
`refunded`	no	Возврат завершен

Действуйте только в отношении окончательных статусов и относитесь к любому статусу, который вы не признаете. Нефинал — список не закрыт, рельсы несут свои промежуточные состояния. Модель полного статуса находится в Спецификация протокола.

Шаг вперед 4 Смотри, как все улаживается

В песочнице можно заряжать карту напрямую и смотреть весь жизненный цикл, без браузера:

curl -X POST https://sandbox.4pay.online/api/v1/transactions \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-organization-id: YOUR_ORGANIZATION_ID" \
  -d '{
    "params": {
      "type": "payment",
      "amount": "1000",
      "currency": "USD",
      "txid": "order-12346",
      "env": "test",
      "show_widget": false,
      "money_storage": {
        "cardnumber": "2201382000000013",
        "cvv": "PROVIDER_TEST_CVV",
        "cardholder": "IVAN IVANOV",
        "exp_year": "20",
        "exp_month": "12"
      },
      "returnUrl": "https://yoursite.com/success",
      "failUrl": "https://yoursite.com/fail"
    }
  }'

Он возвращается. chargingи достигает charged Самостоятельно в течение минуты. 3, or Возьмите веб-хук ниже.

Тестовая карта сопоставляется целиком

Номер, CVV, держатель и срок годности сравниваются как один кортеж. IVAN IVANOV В столицах, exp_year of "20" Любое различие дает rejected / unexpected cardПолный комплект карточек - это in Песочница и тестирование.

A сервер-сервер Оплата должна быть обеим returnUrl и failUrlБез них это Платформа создает транзакцию и сразу же отклоняет ее с помощью парамов return_url/fail_url Хостинговые платежи и выплаты в них не нуждаются.

Шаг вперед 5 - Получать уведомления Webhook

Вместо опроса, попросите вашего оператора установить notify_url В вашем терминале в Консоли администратора, вместе с секретом веб-хука. Это относится ко всем транзакции на этом терминале — нет поля уведомлений по запросу, и a notifyUrl В творчестве тело игнорируется.

Когда статус меняется, подписывается POST Приближается к этому URL:

{
  "event_id": "4d9d0e6c-1d0a-4a2e-9a2f-0c9a1b0e8f21",
  "timestamp": 1772668800,
  "type": "transaction.charged",
  "data": {
    "txid": "order-12345",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "charged",
    "amount": "1000",
    "amount_dest": "950"
  }
}

Проверяйте подпись, прежде чем доверять ей, и дублируйте на event_id - полные детали в Уэбхуки.

Куда пойти дальше

Я хочу...	Ссылка
Сделайте все это в дюжине строк кода.	SDK
Пусть AI Агент принимает платежи	Агентские платежи
Понять каждое поле транзакции	Транзакции
Управляйте неудачами должным образом	Ошибка ссылка
Читайте официальный договор	Универсальный протокол транзакций

Быстрый старт — ваш первый платеж 15 Минуты

Предпосылки​

Шаг вперед 1 Проверьте свою связь​

Шаг вперед 2 - Создать платеж​

Шаг вперед 3 Проверьте статус транзакции​

Шаг вперед 4 Смотри, как все улаживается​

Шаг вперед 5 - Получать уведомления Webhook​

Куда пойти дальше​