Документация/Платежи/Создать платёжную сессию
Создать платёжную сессию
POST/api/v1/payment-sessions
Создаёт сессию hosted-checkout и возвращает checkout_url для перенаправления плательщика.
HMACIdempotency-Key requiredcreatePaymentSession
Параметры тела
| Поле | Тип | Описание |
|---|---|---|
| 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 |
Пример
Запрос
POST /api/v1/payment-sessions
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"
}Ответ 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/payment-sessions \
-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" }'$TS, $NONCE и $SIGNATURE вычисляются на вашем backend по канонической строке. secret_key никогда не должен попадать в браузер, в командную строку из истории и в тикеты.
Связанные операции
GET/api/v1/payment-sessions/{id}Статус платёжной сессииPOST/api/v1/payments/directПрямой платёж (H2H)GET/api/v1/payments/{id}Статус платежаPOST/api/v1/payments/{id}/confirmПодтвердить платёж (OTP)
Была ли страница полезной?