Payment refunds

This method initiates a refund of a successful bank card payment. Pass the order_id of the original payment and a separate user_data for the refund operation. After the request is accepted, the API returns refund_order_id and status REFUND_PENDING; the final result arrives at the project notify_url.

Request format and signatures — see API request format.

1. Original payment — a refund is possible for an order_id of a payment in success status (SUCCESS, code 3). The ID comes from the form or host2host (GATE) creation response.
2. Initiation — signed request to init_refund with a unique refund user_data (different from the payment user_data).
3. Response — refund_order_id, status 9 (REFUND_PENDING), and status_description.
4. Final status — callback POST JSON to notify_url; if needed, poll status by refund_order_id via Payment statuses.

Interpretation of status and status_description for refunds — in Transaction statuses (REFUND, REFUND_PENDING).

Signature: MD5, lowercase (hex). General rules — API request format.

Formula:

MD5(init_refund + <параметры_без_sign_в_алфавитном_порядке_через_&> + <API_KEY>)

Example string before hashing:

init_refundorder_id=8p3brmb19gfg0sg8gcwhws8kgc748s87&partner_id=1234&project_id=5678&user_data=abcd1234secret_key

For partial refunds, the passed amount is included in the signature.

const crypto = require('crypto');
const axios = require('axios');

async function initCardRefund(apiKey, params) {
  const sortedKeys = Object.keys(params).sort();
  const queryString = sortedKeys.map((key) => `${key}=${params[key]}`).join('&');

  const baseString = `init_refund${queryString}${apiKey}`;
  params.sign = crypto.createHash('md5').update(baseString).digest('hex');

  const response = await axios.get('https://api.1payment.com/init_refund', { params });
  return response.data;
}

const apiKey = process.env.ONEPAYMENT_API_KEY;
const data = {
  partner_id: 1234,
  project_id: 5678,
  order_id: '8p3brmb19gfg0sg8gcwhws8kgc748s87',
  user_data: 'abcd1234',
};

initCardRefund(apiKey, data).then(console.log);

Successful response (200):

{
  "refund_order_id": "crf_1p3brmb19gfg0sg8gcwhws8kgc748s87",
  "status": 9,
  "status_description": "REFUND_PENDING",
  "status_code": 0
}

Request error (400):

{
  "error_code": 2
}

After the refund status changes, the server sends POST JSON to the project notify_url.

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_refund prefix). For details, see API request format.

• Create payment via form
• Create host2host (GATE) payment
• Create subscription payment
• Payment statuses
• Transaction statuses
• Payment types
• Error codes (API)
• Error codes (declines)