Документация/Платежи/Прямой платёж (H2H)
Прямой платёж (H2H)
POST/api/v1/payments/direct
Приём карточных данных на стороне мерчанта. Доступен только при собственной сертификации PCI DSS.
HMACIdempotency-Key requiredcreateDirectPayment
Параметры тела
| Поле | Тип | Описание |
|---|---|---|
| order_idreq | string | |
| amount_minorreq | int64 | |
| currencyreq | string | |
| description | string | |
| customer | object | Card-holder data. For a Mastercard PAN email is required. For a Visa PAN first_name, last_name, email, billing_address.country and billing_address.line1 are required. country is accepted as a current ISO 3166-1 alpha-2 code and converted to PSP numeric-3 by the backend. |
| first_name | string | |
| last_name | string | |
| phone | string | |
| billing_address | object | |
| country | string | Current assigned ISO 3166-1 alpha-2 country code. |
| postal_code | string | |
| region | string | |
| city | string | |
| line1 | string | |
| line2 | string | null | |
| line3 | string | null | Third address line, forwarded to the PSP as address_line_3. Optional everywhere; no card scheme requires it. |
| customer_reference | string | Opaque, stable identifier of the payer in the merchant's own system. It is the account a stored card is bound to: the same reference on a later payment offers that customer their saved cards on the hosted page, and scopes GET /cabinet/v1/payment-method-tokens. |
| return_url | uri | |
| locale | "ru" | "en" | "ua" | Forwarded to the provider as the envelope `lang`, which chooses the language of the pages the provider renders itself - its hosted checkout and the issuer's 3DS step. Defaults to `ru`. It does not translate the platform's own hosted payment page, which is English-only. If your payers need the platform page in another language, that is a separate piece of work and this field will not produce it. |
| expires_in_seconds | integer | |
| save_payment_method | boolean | Store the card for later payments by this customer. Requires customer_reference; without one there would be no account to bind the card to and it could never be listed, reused or deleted, so the request is rejected with customer_reference_required. |
| subscription | object | |
| interval_unitreq | "day" | "week" | "month" | "year" | |
| interval_countreq | integer | |
| first_charge_atreq | date-time | |
| disclosure_versionreq | string | |
| consent | boolean | Checkout collects the payer's separate consent again. |
| metadata | object | |
| operation_mode | "charge" | "authorize" | |
| payment_methodreq | object | |
| typereq | "card" | "apple_pay" | "google_pay" | "samsung_pay" | "mobile" | |
| card | object | |
| number | string | |
| expire_month | integer | |
| expire_year | integer | |
| cvv | string | |
| cardholder | string | |
| wallet | object | |
| payload_mode | "token" | "direct" | Selects the documented token or direct PSP wallet method. Wallet authorize is supported when the channel capability allows it. |
| mobile | object | Required when type is mobile: the mobile account the operator debits. Rejected with 422 capability_not_supported together with operation_mode=authorize - the operator settles immediately and offers no hold to capture later. |
| phonereq | string | E.164, leading plus required. Spaces, dashes and brackets are stripped before validation. The plus is not assumed: a national number carries no country code, and reading its first digits as one would debit a different subscriber. |
| device | object | Neutral browser snapshot. The backend derives authoritative accept_header and user_agent values from HTTP request headers and merges payer IP only into the provider DTO. Forwarded IP headers are accepted only from socket peers in the configured trusted-proxy CIDRs. |
| accept_header | string | |
| color_depth | number | |
| screen_width | number | |
| screen_height | number | |
| viewport_width | number | |
| viewport_height | number | |
| device_pixel_ratio | number | |
| language | string | |
| languages | string[] | |
| timezone | string | |
| utc_offset | number | |
| user_agent | string | |
| platform | string | |
| javascript_enabled | boolean | |
| touch_enabled | boolean | |
| max_touch_points | number | |
| cookie_enabled | boolean | |
| online | boolean | |
| referrer_origin | string | |
| session_started_at | string | |
| client_timestamp | string |
Пример
Запрос
POST /api/v1/payments/direct
Idempotency-Key: order-20260817-001
{
"order_id": "order-20260817-001",
"amount_minor": 1001,
"currency": "EUR",
"description": "Заказ №014",
"return_url": "https://merchant.example.com/payments/return",
"payment_method": {
"type": "card"
}
}Ответ 201
{
"payment_id": "0198c5f2-7b3e-7a41-9c2d-3f8a1b6e4d02",
"status": "created",
"final": false,
"created_at": "2026-08-17T12:45:22Z",
"updated_at": "2026-08-17T12:45:22Z"
}Собрать запрос
Собрать запрос
curl -X POST \
https://api.calibripay.com/api/v1/payments/direct \
-H "X-Access-Key: $CALIBRIPAY_ACCESS_KEY" \
-H "X-Timestamp: $TS" \
-H "X-Nonce: $NONCE" \
-H "X-Signature: $SIGNATURE" \
-H "Idempotency-Key: order-20260817-001" \
-d '{ "order_id": "order-20260817-001", "amount_minor": 1001, "currency": "EUR", "description": "Заказ №014", "return_url": "https://merchant.example.com/payments/return", "payment_method": { "type": "card" } }'$TS, $NONCE и $SIGNATURE вычисляются на вашем backend по канонической строке. secret_key никогда не должен попадать в браузер, в командную строку из истории и в тикеты.
Связанные операции
POST/api/v1/payment-sessionsСоздать платёжную сессиюGET/api/v1/payment-sessions/{id}Статус платёжной сессииGET/api/v1/payments/{id}Статус платежаPOST/api/v1/payments/{id}/confirmПодтвердить платёж (OTP)
Была ли страница полезной?