Документация/Приём платежей/Прямой платёж
Прямой платёж (H2H)
Backend мерчанта передаёт карточные данные напрямую. Это единственный поток, в котором PAN проходит через вашу инфраструктуру — и единственный, который требует отдельного допуска.
Условия доступа
Нужен письменный допуск PCI/compliance
Боевая обработка карт в прямом потоке запрещена без письменного согласования PCI и compliance. Если у вас нет собственной сертификации PCI DSS, используйте hosted-checkout: там карточные данные не попадают в ваш контур.
Запрос допустим только server-to-server. Ни секрет API, ни PAN, ни CVV никогда не проходят через браузер и не появляются в мобильном бандле.
Запрос
Запрос
POST /api/v1/payments/direct
Idempotency-Key: direct-order-20260817-001
{
"order_id": "direct-order-20260817-001",
"amount_minor": 1001,
"currency": "EUR",
"return_url": "https://merchant.example.com/payments/3ds-return",
"payment_method": {
"type": "card",
"card": {
"number": "<PAN>",
"expire_month": 12,
"expire_year": 2030,
"cvv": "<CVV>",
"cardholder": "<CARDHOLDER NAME>"
}
},
"customer": {
"first_name": "Anna",
"last_name": "Schmidt",
"email": "anna.schmidt@example.test",
"billing_address": { "country": "DE", "line1": "Friedrichstrasse 100" }
}
}201 — это не списание
Ответ обычно приходит со статусом processing. HTTP 201 подтверждает только приём операции в обработку. Итог приходит вебхуком или запрашивается по статусу платежа.
Обязательные поля по схеме карты
Состав обязательных полей плательщика определяется платёжной схемой, к которой относится PAN:
| Схема | Обязательные поля |
|---|---|
| Mastercard | customer.email |
| Visa | customer.first_name, customer.last_name, customer.email, customer.billing_address.country, customer.billing_address.line1 |
country передаётся действующим кодом ISO 3166-1 alpha-2 (DE, FR, NL). Платформа сама преобразует его в числовой код провайдера, включая ведущие нули.
3-D Secure
Если платёж перешёл в requires_action, ответ содержит следующее действие:
{
"status": "requires_action",
"final": false,
"next_action": {
"type": "three_ds",
"url": "https://acs.issuer.example/..."
}
}- Отправьте браузер плательщика на
next_action.urlполным переходом. - После прохождения 3-D Secure браузер вернётся на ваш return_url.
- Найдите
payment_idпо собственной серверной записи заказа, а не по параметрам URL. - Вызовите POST /payments/{payment_id}/confirm с новым Idempotency-Key; для 3-D Secure тело может быть пустым.
- Итог получите вебхуком или запросом статуса.
3-D Secure — это браузерный поток
Не открывайте next_action.url с backend или из Postman и не считайте query-параметры возврата подтверждением оплаты.
OTP
Если next_action.type = "otp", соберите код у плательщика и передайте его тем же эндпоинтом подтверждения:
POST /api/v1/payments/{payment_id}/confirm
Idempotency-Key: confirm-direct-order-20260817-001
{ "value": "123456" }