Приём платежей

Создание заказа

При создании заказа:

• amount (сумму) необходимо указывать в минорных денежных единицах, т.е. для создания заказа на сумму 500 тенге, необходимо ввести 50000 (1 тенге = 100 тиын)
• capture_method по умолчанию устанавливается метод AUTO, т.е. платеж по данному заказу будет однофакторный. Для проведения двухфакторных платежей в данный параметр необходимо передать MANUAL

Более подробно ознакомиться с остальными параметрами для создания заказа, а также со всеми доступными методами для управления заказами можно в Справочнике по API.

Пример запроса:

HTTP

POST /v2/orders HTTP/1.1
Host: stage-api.ioka.kz
API-KEY: eyJ0eXAiOiJKV1..
Content-Type: application/json

{
    "amount": 50000
}

cURL

curl --location --request POST 'https://stage-api.ioka.kz/v2/orders' \
--header 'API-KEY: eyJ0eXAiOiJKV1..' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 50000
}'

Python

import requests
import json

url = "https://stage-api.ioka.kz/v2/orders"

payload = json.dumps({
    "amount": 50000
})
headers = {
    'API-KEY': 'eyJ0eXAiOiJKV1..',
    'Content-Type': 'application/json'
}

response = requests.post(url, headers=headers, data=payload)
order = response.json()['order']

print(order['checkout_url'])

PHP

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://stage-api.ioka.kz/v2/orders');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "amount": 50000
}');
$request->setBody($body);
$request->setOptions(array());
$request->setHeaders(array(
  'API-KEY' => 'eyJ0eXAiOiJKV..',
  'Content-Type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();

Пример ответа:

{
    "order": {
        "id": "ord_test",
        "shop_id": "shp_test",
        "status": "UNPAID",
        "created_at": "2022-01-01T10:00:00.00000",
        "amount": 50000,
        "display_amount": 50000,
        "currency": "KZT",
        "mcc": null,
        "acquirer": null,
        "capture_method": "AUTO",
        "external_id": null,
        "description": null,
        "extra_info": null,
        "attempts": 10,
        "due_date": null,
        "split": null,
        "customer_id": null,
        "card_id": null,
        "back_url": null,
        "success_url": null,
        "failure_url": null,
        "template": null,
        "access_token": "ord_test_secret_4ed07d5a47d...",
        "checkout_url": "https://test.ioka.kz/orders/ord_test",
        "payment_link_url": null,
        "payments": []
    },
    "order_access_token": "ord_test_secret_4ed07d5aл47d..."
}

Статусы заказа

Статус	Описание
UNPAID	Первоначальный статус. Заказ может быть оплачен. Статус заказа может обновиться на ON_HOLD или PAID в случае успешной оплаты.
ON_HOLD	Промежуточный статус, возможен при двухфакторной оплате. Возвращается после успешной авторизации (холдирования) денежных средств на карте плательщика. Может быть списан или отменен.
PAID	Заказ оплачен, т.е. денежные средства списаны с карты плательщика и будут перечислены на расчетный счет мерчанта в течении 3 рабочих дней. По данному заказу может быть оформлен возврат.
EXPIRED	Срок оплаты заказа (due_date) истек. Необходимо создать новый заказ.

Проведение оплаты

Для проведения оплаты необходимо перенаправить пользователя на адрес checkout_url, полученный в теле ответа на создание заказа, где находится форма сбора карточных данных.

Заказ можно считать успешным, как только он перешел в статус PAID или ON_HOLD в зависимости от способа списания денег.

По умолчанию у клиента есть 10 попыток для проведения платежа по данному заказу, т.е. в случае неуспешной оплаты на форме будет показана причина отклонения и появится возможность для повторной оплаты.

Проверка статуса платежа

Доступны несколько способов для проверки статуса платежа:

1. Настроить получение уведомлений (webhook-ов) от ioka на события PAYMENT_APPROVED, PAYMENT_CAPTURED, PAYMENT_DECLINED.
2. Периодически запрашивать информацию о заказе методом GetOrderByID.
3. Проверять статус в Личном Кабинете Мерчанта.

Важно

Если клиент при оплате заказа выбрал Сохранить карту на этом сайте, то в webhook-е или в ответе на запрос GetOrderByID, в объекте payer придут заполненные параметры customer_id и card_id.

Подробнее ознакомиться с проведением оплаты по сохраненным картам можно в разделе Оплата по сохраненной карте.

Статусы платежа

Статус	Описание
PENDING	Ожидает подтверждения оплаты. Промежуточный статус.
REQUIRES_ACTION	Плательщик перенаправлен на прохождение проверки 3DS.
APPROVED	Платеж прошел успешно. Сумма авторизована (захолдирована) на карте плательщика при двухфакторной оплате. Если платеж не будет списан или отменен в течении 48 часов, то вся авторизованная сумма спишется в пользу мерчанта, т.е. платеж перейдет в статус CAPTURED.
CAPTURED	Платеж прошел успешно. Сумма списана с карты плательщика.
CANCELLED	Платеж отменен, т.е. авторизованная сумма полностью расхолдирована (разблокирована) с карты плательщика.
DECLINED	Попытка платежа неуспешна. Необходимо повторить оплату.

Если платеж был отклонен (payment_status = DECLINED), в уведомлении придет объект error:

"error": {
    "code": "WRONG_CARD_DATA_INPUT",
    "message": "The transaction is declined. Check the card details and try again."
}

Более подробно ознакомиться со всеми возможными ошибками платежа можно ознакомиться в Справочнике по API.