OnePay Docs

Оформление

Оплаты ​

Введение ​

Руководство по созданию ссылок на оплату, обработке вебхуков и работе с сохраненными картами в OnePay.

Что подготовить

  • Сервер, с которого можно отправлять API-запросы к OnePay.
  • Активный мерчант-аккаунт в OnePay.

Шаг 1. Настройка аккаунта OnePay ​

Регистрация и доступы ​

  • Зарегистрируйте мерчант-аккаунт через info@onepayltd.kz.
  • После активации вы получите merchant_id, profile_id, api_key и payment_response_hash_key.
  • Добавьте домен, на котором будет открыт iframe со ссылкой на оплату, в белый список. Убедитесь, что домен также разрешен для отправки вебхуков.

Внимание

Храните api_key и payment_response_hash_key только на серверной стороне.

Шаг 2. Создать ссылку для оплаты ​

Запрос ​

Отправьте POST-запрос на https://api.onepayltd.kz/ac/payments.

Заголовки:

http
api-key: YOUR_API_KEY
Accept-Language: RU // для выбора интерфейса ссылки на оплату

Тело запроса:

json
{
  "amount": 1000,               // сумма в тиынах (1000 = 10 тенге)
  "currency": "KZT",
  "confirm": false,             // подтверждать ли платеж
  "payment_link": true,         // создать ли ссылку
  "capture_method": "automatic",
  "setup_future_usage": "off_session", // для сохранения карты
  "customer_acceptance": {
    "acceptance_type": "online"
  },
  "customer": {
    "email": "client_email@gmail.com",
    "id": "YOUR_CUSTOMER_ID",   // например, телефон или ИИН
    "name": "имя фамилия"
  },
  "return_url": "https://example.com", // куда перенаправить клиента
  "profile_id": "YOUR_PROFILE_ID",
}

Ответ ​

json
{
  "payment_id": "000000000",
  "merchant_id": "YOUR_MERCHANT_ID",
  "status": "requires_payment_method",
  "amount": 1000,
  "net_amount": 1000,
  "amount_capturable": 0,
  "client_secret": "CLIENT_SECRET",
  "created": "2025-12-01T09:39:18.301Z",
  "currency": "KZT",
  "customer_id": "YOUR_CUSTOMER_ID",
  "customer": {
    "id": "YOUR_CUSTOMER_ID",
    "name": "имя фамилия",
    "email": "client_email@gmail.com",
  },
  "email": "client_email@gmail.com",
  "name": "имя фамилия",
  "return_url": "https://example.com/",
  "business_label": "default",
  "ephemeral_key": {
    "customer_id": "YOUR_CUSTOMER_ID",
    "created_at": 0000000000,
    "expires": 0000000000,
    "secret": "SECRET"
  },
  "payment_link": {
    "link": "https://api.onepayltd.kz/ac/payment_link/YOUR_MERCHANT_ID/payXXXXX?locale=en",
    "secure_link": "https://api.onepayltd.kz/ac/payment_link/s/YOUR_MERCHANT_ID/payXXXXX?locale=en",
    "payment_link_id": "plink_XYXYXY"
  },
  "profile_id": "YOUR_PROFILE_ID",
  "attempt_count": 1,
  "expires_on": "2025-12-01T09:54:18.298Z",
  "updated": "2025-12-01T09:39:18.321Z",
}

Встройте payment_link.link в iframe на домене из белого списка. Ссылка действует 15 минут.

html
<iframe
  src="https://api.onepayltd.kz/ac/payment_link/YOUR_MERCHANT_ID/payXXXXX?locale=en"
  frameborder="0">
</iframe>

Форма оплаты

Шаг 3. Проведение оплаты и вебхуки ​

После завершения оплаты (успех или отказ) OnePay отправляет вебхук на URL мерчанта. Тело запроса описано в Stoplight (OutgoingWebhook).

Вебхуки подписываются HMAC-SHA512 с ключом payment_response_hash_key:

  1. Преобразуйте тело вебхука в JSON-строку.
  2. Сгенерируйте HMAC-SHA512 подпись с тем же ключом.
  3. Сравните результат с заголовком x-webhook-signature-512.

Шаг 4. Получение сохраненных карт клиента ​

Запрос ​

Отправьте POST на https://api.onepayltd.kz/ac/customers/{client_id}/payment_methods, где client_id — идентификатор клиента, использованный при оплате.

http
api-key: YOUR_API_KEY
json
{
  "customer_payment_methods": [
    {
      "payment_token": "token_XXXXXXXX",
      "payment_method_id": "YOUR_CUSTOMERS_PAYMENT_METHOD_ID",
      "customer_id": "YOUR_CUSTOMER_ID",
      "payment_method": "card",
      "payment_method_type": "debit",
      "card": {
        "last4_digits": "4242",
        "expiry_month": "12",
        "expiry_year": "2042",
        "card_holder_name": "FIRSTNAME LASTNAME"
      },
      "created": "2025-11-21T13:45:41.298Z",
      "default_payment_method_set": true,
      "requires_cvv": true
    }
  ]
}

Сохраненный payment_method_id используется для рекуррентных оплат.

Шаг 5. Оплата по сохраненной карте ​

Запрос ​

Отправьте POST на https://api.onepayltd.kz/ac/payments с confirm: true и payment_method_id.

http
api-key: YOUR_API_KEY
json
{
  "amount": 1000,
  "currency": "KZT",
  "confirm": true,
  "capture_method": "automatic",
  "customer_id": "YOUR_CUSTOMER_ID",

  "off_session": true, // обязательно при рекуррентных платежах
  "recurring_details": {
      "type": "payment_method_id",
      "data": "pm_XXXXXXXXX"
  },

  "return_url": "https://example.com",
  "profile_id": "YOUR_PROFILE_ID"
}

С подробным телом запроса и ответа можно ознакомиться в Stoplight

Обратите внимание

Так как ответ содержит финальный статус (success или failed), повторный вебхук не отправляется.

Документация OnePay

© 2025 OnePay