Create subscription payment
Recurring bank card payments allow you to charge a token of a saved card without the payer re-entering card details. With an active binding, charges are processed through GATE (init_payment).
Contact your 1Payment account manager to enable this feature for your project.
Request format and signatures — see API request format.
How it works
The card subscription process consists of four steps:
- First payment (card binding) — complete a successful payment with
subscription=1via the payment form or GATE (host2host). The payer enters card details and completes 3-D Secure if required. - Receive token — after successful payment, 1Payment sends a unique
tokenin the callback tonotify_urlor in the status request response. Save it for subsequent charges. - Automatic charge (recurring) — for repeat payments, your server calls GATE (
init_payment), passing the savedtokeninstead ofaccount,card_holder,year,month, andcvc. - Notification — after each charge attempt, a callback arrives with the final transaction result.
Technical information
| Stage | Endpoint | Methods |
|---|---|---|
| Subscription registration (form) | https://api.1payment.com/init_form | GET, POST |
| Subscription registration (GATE) | https://api.1payment.com/init_payment | GET, POST |
| Recurring charge (GATE) | https://api.1payment.com/init_payment | POST (recommended), GET |
Response format: JSON. For cards, specify payment_type=card in GATE requests.
1. Obtain token (first payment)
To bind a card, complete a successful payment with subscription=1. For form and GATE parameters, see Create payment via form and Create host2host (GATE) payment. Below is the required set for binding.
Required parameters (form initialization)
| Parameter | Type | Description |
|---|---|---|
partner_id | Integer | Your unique ID in the 1Payment system. |
project_id | Integer | Your project identifier. |
amount | Number | Payment amount for binding (for example, 50.00). |
subscription | Integer | Subscription creation flag. Always 1. Without it, no token is returned. |
user_data | String | Your unique order ID for matching. |
shop_url | String | URL of the website where the purchase is made. |
sign | String | Request signature (see below). |
Required parameters (GATE initialization)
| Parameter | Type | Description |
|---|---|---|
partner_id | Integer | Your unique ID in the 1Payment system. |
payment_type | String | Always card. |
project_id | Integer | Your project identifier. |
account | String | Bank card number. |
card_holder | String | Cardholder name (as printed on the card). |
year | String | Card expiry year, last two digits (for example, 22). |
month | String | Card expiry month (for example, 01). |
cvc | String | Card CVV/CVC code. |
amount | Number | Payment amount for binding (for example, 50.00). |
subscription | Integer | Subscription creation flag. Always 1. Without it, no token is returned. |
user_data | String | Your unique order ID for matching. |
shop_url | String | URL of the website where the payment originates. |
sign | String | Request signature (see below). |
Optional parameters (initialization)
| Parameter | Type | Description |
|---|---|---|
description | String | Payment description. |
success_url | String | Customer redirect URL on success (form). |
failure_url | String | Customer redirect URL on error (form). |
return_url | String | Payer redirect URL after payment (GATE). |
ip | String | Payer IP address (GATE). |
user_id | String | Payer ID in your system. |
Signature for form registration — prefix init_form. Via GATE — prefix init_payment.
MD5(init_form + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)After the final SUCCESS status, save the token value from the callback or from the Payment statuses response.
2. Recurring charge (repeat payments)
For automatic charging, send a GATE request with the saved token. Do not pass account, card_holder, year, month, and cvc — use only token instead.
Required parameters (recurring)
| Parameter | Type | Description |
|---|---|---|
partner_id | Integer | Your unique ID in the 1Payment system. |
payment_type | String | Always card. |
project_id | Integer | Your project identifier. |
amount | Number | Amount of the recurring charge (for example, 500.00). |
token | String | Token received from the first successful payment (from callback or status request). |
user_data | String | New unique transaction ID on your side. |
shop_url | String | URL of the website where the payment originates. |
sign | String | Request signature (prefix init_payment). |
Optional parameters (recurring)
| Parameter | Type | Description |
|---|---|---|
description | String | Payment description. |
ip | String | Payer IP address. |
return_url | String | Payer redirect URL after payment. |
user_id | String | Payer ID in your system. |
Signature generation (sign)
Signature: MD5, lowercase (hex). General rules — API request format.
Formula:
MD5(init_payment + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)Example string before hashing:
init_paymentamount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_888secret_keySignature verification (recurring charge)
Signature check for {{method}}
Paste the request parameters (JSON), API key, and signature. The widget verifies them automatically.
amount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_888init_paymentamount=500.00&partner_id=1234&payment_type=card&project_id=5678&shop_url=https://test.com&token=card_t_1a2b3c&user_data=card_order_88859785c76ce35d08da343e6b8eec1e459Request examples
const crypto = require('crypto');
const axios = require('axios');
// 1. Инициация подписки через форму (первичная привязка)
async function setupCardSubscriptionForm(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_form${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_form', params);
return response.data; // поле url — ссылка на форму
}
// 2. Инициация подписки через GATE
async function setupCardSubscriptionGate(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_payment${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_payment', params);
return response.data; // redirect_url при необходимости 3-D Secure
}
// 3. Рекуррентное списание (по токену)
async function chargeCardByToken(apiKey, params) {
const sortedKeys = Object.keys(params).sort();
const queryString = sortedKeys.map((k) => `${k}=${params[k]}`).join('&');
const baseString = `init_payment${queryString}${apiKey}`;
params.sign = crypto.createHash('md5').update(baseString).digest('hex');
const response = await axios.post('https://api.1payment.com/init_payment', params);
return response.data;
}
const apiKey = process.env.ONEPAYMENT_API_KEY;
// Пример: привязка через форму
const setupFormData = {
partner_id: 1234,
project_id: 5678,
amount: '50.00',
subscription: 1,
user_data: 'card_setup_777',
shop_url: 'https://test.com',
};
// setupCardSubscriptionForm(apiKey, setupFormData).then(console.log);
// Пример: привязка через GATE
const setupGateData = {
partner_id: 1234,
payment_type: 'card',
project_id: 5678,
account: '4111111111111111',
card_holder: 'TEST',
year: '22',
month: '01',
cvc: '111',
amount: '50.00',
subscription: 1,
user_data: 'card_setup_777',
shop_url: 'https://test.com',
};
// setupCardSubscriptionGate(apiKey, setupGateData).then(console.log);
// Пример: списание
const recurringData = {
partner_id: 1234,
payment_type: 'card',
project_id: 5678,
token: 'card_t_1a2b3c',
amount: '500.00',
user_data: 'card_order_888',
shop_url: 'https://test.com',
};
chargeCardByToken(apiKey, recurringData).then(console.log);API response
On a successful recurring request (200):
{
"order_id": "8p3brmb19gfg0sg8gcwhws8kgc748s87",
"status": 2,
"status_description": "PENDING",
"status_code": 0
}| Field | Description |
|---|---|
order_id | Payment ID in the 1Payment system; use for status requests. |
status | Numeric status code (2 — pending). |
status_description | Text status description (PENDING, etc.). |
status_code | Decline error code (see decline codes). |
redirect_url | URL for 3-D Secure if additional authentication is required (may be absent). |
For the first payment with subscription=1 via form, the response contains the url field (see Create payment via form); via GATE — redirect_url if 3-D Secure is required (see Create host2host (GATE) payment). After successful payment, the token field arrives in the callback to notify_url or in the status request response — without subscription=1, no token is issued.
Request error (400):
{
"error_code": 2
}Status notifications (callbacks)
After successful card binding or a recurring charge, the system sends a POST request in JSON format to your notify_url.
| Parameter | Type | Req. | Description |
|---|---|---|---|
payment_type | String | Yes | Payment type (card). |
order_id | String | Yes | Payment ID in the 1Payment system. |
project_id | Integer | Yes | Your project ID. |
status | Integer | Yes | State: 2 (pending), 3 (success), 4 (declined). |
status_description | String | Yes | PENDING, SUCCESS, or FAILURE. |
init_time | String | Yes | Payment creation time. |
status_time | String | Yes | Time the final status was received. |
merchant_price | Number | Yes | Amount charged to the payer. |
init_price | Number | No | Amount at initialization. |
user_price | Number | Yes | Partner payout amount. |
currency | String | Yes | Payment currency (ISO 4217). |
account | String | Yes | Masked card number. |
user_data | String | Yes | Transaction ID passed at creation. |
sign | String | Yes | Callback signature. |
token | String | No | Token for subsequent charges — save after the first successful payment. |
test | Integer | No | 1 for test payments. |
status_code | String | No | Decline reason code. |
Important: your server must return HTTP 200 OK. Otherwise, the system retries the callback once per minute for 10 minutes.
Callback signature verification: MD5 of all parameters in alphabetical order joined with & + API_KEY (without the init_payment prefix). For details, see API request format.
You can also obtain the token via payment status request — the token field in the API response.