Выплаты

Введение

Руководство по созданию ссылок на выплату, обработке вебхуков и работе с сохраненными картами в 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/payouts/create.

Заголовки:

api-key: YOUR_API_KEY
Accept-Language: RU

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

{
  "amount": 1000, // сумма в тиынах (1000 = 10 тенге)
  "currency": "KZT",
  "confirm": false, // false для ссылок на выплату
  "payout_type": "card",
  "payout_link": true, // создать ссылку
  "auto_fulfill": true, // авто-выплата
  "customer": {
    "email": "client_email@gmail.com",
    "id": "YOUR_CUSTOMER_ID", // например, телефон или ИИН
    "name": "имя фамилия"
  },
  "return_url": "https://example.com",
  "payment_link_config": {
    "logo": "https://encrypted-tbn0.gstatic.com/images?q=tbn:ANd9GcRfzUmrtQk1XqGAVaBEhWM-TXFKcBzFBYGa_Q&s",
    "merchant_name": "OnePay",
    "theme": "#123123",
    "enabled_payment_methods": [
      {
        "payment_method": "card",
        "payment_method_types": ["credit", "debit"]
      }
    ],
    "test_mode": false
  },
  "recurring": true, // сохранить карту клиента
  "priority": "instant",
  "order_id": "000000000", // внутренний номер выплаты
  "profile_id": "YOUR_PROFILE_ID"
}

Ответ

{
  "payout_id": "payout_XXXXX",
  "merchant_id": "YOUR_MERCHANT_ID",
  "amount": 1000,
  "currency": "KZT",
  "payout_type": "card",
  "auto_fulfill": true,
  "customer_id": "111111111",
  "customer": {
    "id": "YOUR_CUSTOMER_ID",
    "name": "имя фамилия",
    "email": "client_email@gmail.com"
  },
  "client_secret": "payout_payout_XXXXX_secret_XXXXX",
  "return_url": "https://example.com",
  "order_id": "000000000",
  "recurring": true,
  "status": "requires_payout_method_data",
  "profile_id": "YOUR_PROFILE_ID",
  "priority": "instant",
  "payout_link": {
    "payout_link_id": "payout_link_XYXYXY",
    "link": "https://api.onepayltd.kz/ac/payout_link/YOUR_MERCHANT_ID/payout_XXXXX?locale=ru"
  }
}

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

Шаг 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 — идентификатор клиента, использованный при выплате.

api-key: YOUR_API_KEY

{
  "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/payouts/create с confirm: true и payout_method_id.

api-key: YOUR_API_KEY

{
  "amount": 1000,
  "currency": "KZT",
  "confirm": true,
  "payout_type": "card",
  "payout_method_id": "YOUR_CUSTOMERS_PAYMENT_METHOD_ID",
  "auto_fulfill": true,
  "customer": {
    "id": "YOUR_CUSTOMER_ID"
  },
  "recurring": true,
  "priority": "instant",
  "order_id": "XXXXXXX",
  "profile_id": "YOUR_PROFILE_ID"
}

Ответ

{
  "payout_id": "payout_XXXXX",
  "merchant_id": "YOUR_MERCHANT_ID",
  "amount": 1000,
  "currency": "KZT",
  "payout_type": "card",
  "payout_method_data": {
    "card": {
      "last4": "4242",
      "card_exp_month": "12",
      "card_exp_year": "2042",
      "card_holder_name": "FIRSTNAME LASTNAME"
    }
  },
  "auto_fulfill": true,
  "customer_id": "YOUR_CUSTOMER_ID",
  "client_secret": "payout_payout_XXXX_secret_XXXXX",
  "order_id": "XXXXXXX",
  "recurring": true,
  "status": "success",
  "profile_id": "YOUR_PROFILE_ID",
  "priority": "instant",
  "payout_method_id": "pm_XXXXXXX"
}

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

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