Skip to content

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:

  1. First payment (card binding) — complete a successful payment with subscription=1 via the payment form or GATE (host2host). The payer enters card details and completes 3-D Secure if required.
  2. Receive token — after successful payment, 1Payment sends a unique token in the callback to notify_url or in the status request response. Save it for subsequent charges.
  3. Automatic charge (recurring) — for repeat payments, your server calls GATE (init_payment), passing the saved token instead of account, card_holder, year, month, and cvc.
  4. Notification — after each charge attempt, a callback arrives with the final transaction result.

Technical information

StageEndpointMethods
Subscription registration (form)https://api.1payment.com/init_formGET, POST
Subscription registration (GATE)https://api.1payment.com/init_paymentGET, POST
Recurring charge (GATE)https://api.1payment.com/init_paymentPOST (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)

ParameterTypeDescription
partner_idIntegerYour unique ID in the 1Payment system.
project_idIntegerYour project identifier.
amountNumberPayment amount for binding (for example, 50.00).
subscriptionIntegerSubscription creation flag. Always 1. Without it, no token is returned.
user_dataStringYour unique order ID for matching.
shop_urlStringURL of the website where the purchase is made.
signStringRequest signature (see below).

Required parameters (GATE initialization)

ParameterTypeDescription
partner_idIntegerYour unique ID in the 1Payment system.
payment_typeStringAlways card.
project_idIntegerYour project identifier.
accountStringBank card number.
card_holderStringCardholder name (as printed on the card).
yearStringCard expiry year, last two digits (for example, 22).
monthStringCard expiry month (for example, 01).
cvcStringCard CVV/CVC code.
amountNumberPayment amount for binding (for example, 50.00).
subscriptionIntegerSubscription creation flag. Always 1. Without it, no token is returned.
user_dataStringYour unique order ID for matching.
shop_urlStringURL of the website where the payment originates.
signStringRequest signature (see below).

Optional parameters (initialization)

ParameterTypeDescription
descriptionStringPayment description.
success_urlStringCustomer redirect URL on success (form).
failure_urlStringCustomer redirect URL on error (form).
return_urlStringPayer redirect URL after payment (GATE).
ipStringPayer IP address (GATE).
user_idStringPayer 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)

ParameterTypeDescription
partner_idIntegerYour unique ID in the 1Payment system.
payment_typeStringAlways card.
project_idIntegerYour project identifier.
amountNumberAmount of the recurring charge (for example, 500.00).
tokenStringToken received from the first successful payment (from callback or status request).
user_dataStringNew unique transaction ID on your side.
shop_urlStringURL of the website where the payment originates.
signStringRequest signature (prefix init_payment).

Optional parameters (recurring)

ParameterTypeDescription
descriptionStringPayment description.
ipStringPayer IP address.
return_urlStringPayer redirect URL after payment.
user_idStringPayer 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_key

Signature verification (recurring charge)

Signature check for {{method}}

Paste the request parameters (JSON), API key, and signature. The widget verifies them automatically.

Parameter string: 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_888
String for MD5: 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_888
Expected signature: 59785c76ce35d08da343e6b8eec1e459
Signature does not match

Request 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
}
FieldDescription
order_idPayment ID in the 1Payment system; use for status requests.
statusNumeric status code (2 — pending).
status_descriptionText status description (PENDING, etc.).
status_codeDecline error code (see decline codes).
redirect_urlURL 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.

ParameterTypeReq.Description
payment_typeStringYesPayment type (card).
order_idStringYesPayment ID in the 1Payment system.
project_idIntegerYesYour project ID.
statusIntegerYesState: 2 (pending), 3 (success), 4 (declined).
status_descriptionStringYesPENDING, SUCCESS, or FAILURE.
init_timeStringYesPayment creation time.
status_timeStringYesTime the final status was received.
merchant_priceNumberYesAmount charged to the payer.
init_priceNumberNoAmount at initialization.
user_priceNumberYesPartner payout amount.
currencyStringYesPayment currency (ISO 4217).
accountStringYesMasked card number.
user_dataStringYesTransaction ID passed at creation.
signStringYesCallback signature.
tokenStringNoToken for subsequent charges — save after the first successful payment.
testIntegerNo1 for test payments.
status_codeStringNoDecline 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.

Was this article helpful?