Сохранение карты

Создание плательщика

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

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

HTTP

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

{
    "external_id": "1",
    "email": "test@ioka.kz",
    "phone": "77771112233"
}

cURL

curl --location --request POST 'https://stage-api.ioka.kz/v2/customers' \
--header 'API-KEY: eyJ0eXAiOiJKV1..' \
--header 'Content-Type: application/json' \
--data-raw '{
    "external_id": "1",
    "email": "test@ioka.kz",
    "phone": "77771112233"
}'

Python

import requests
import json

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

payload = json.dumps({
    "external_id": "1",
    "email": "test@ioka.kz",
    "phone": "77771112233"
})
headers = {
    'API-KEY': 'eyJ0eXAiOiJKV1..',
    'Content-Type': 'application/json'
}

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

print(order['checkout_url'])

PHP

<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://stage-api.ioka.kz/v2/customers');
$request->setRequestMethod('POST');
$body = new http\Message\Body;
$body->append('{
    "external_id": "1",
    "email": "test@ioka.kz",
    "phone": "77771112233"
}');
$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();

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

{
    "customer": {
        "id": "8vcatBnudg",
        "status": "PENDING",
        "created_at": "2022-01-01T10:00:00.00000",
        "external_id": "1",
        "email": "test@ioka.kz",
        "phone": "77771112233",
        "accounts": [
            {
                "id": "act_AJHyDIVHv6",
                "shop_id": "shp_test",
                "status": "PENDING",
                "amount": 0,
                "created_at": "2022-01-01T10:00:00.00000",
                "resources": [
                    {
                        "id": "rsc_bc2fa2ca-83f2-4ef1-9abd-c07ee8faa456",
                        "is_default": true,
                        "created_at": "2022-01-01T10:00:00.00000",
                        "status": "PENDING"
                    }
                ]
            }
        ],
        "access_token": "8vcatBnudg_secret_89b7465c5ab2de16a252d9e34b4a9be453b9e6b0c29bd33c9117e265d77bc6a8",
        "checkout_url": "https://test.ioka.kz/customers/8vcatBnudg?access_token=8vcatBnudg_secret_89b7465c5ab2de16a252d9e34b4a9be453b9e6b0c29bd33c9117e265d77bc6a8"
    },
    "customer_access_token": "8vcatBnudg_secret_89b7465c5ab2de16a252d9e34b4a9be453b9e6b0c29bd33c9117e265d77bc6a8"
}

Статусы плательщика

Статус	Описание
PENDING	Первоначальный статус плательщика. У клиента еще нет успешно сохраненных карт.
READY	У клиента есть как минимум одна успешно сохраненная карта.
DELETED	Плательщик удален.

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

Сохранение карты

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

После успешного сохранения карты статус карты сменится с PENDING на APPROVED, а статус плательщика с PENDING на READY. Для плательщика отобразится форма со всеми раннее сохраненными картами, а также возможность добавить еще одну карту.

Проверка статуса сохранения карты

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

1. Настроить получение уведомлений (webhook-ов) от ioka на события CARD_APPROVED, CARD_DECLINED.

В случае успешного сохранения, Вам придет объект, содержащий следующую информацию:

{
  "event": "CARD_APPROVED",
  "customer": {
    "id": "abcdefghkj",
    "shop_id": "test",
    "status": "READY",
    "created_at": "2023-01-30T05:00:00",
    "external_id": null,
    "email": null,
    "phone": "777771112233"
  },
  "card": {
    "id": "abcdefghkj",
    "customer_id": "abcdefghkj",
    "status": "APPROVED",
    "created_at": "2023-01-30T05:00:00",
    "pan_masked": "411111******1111",
    "expiry_date": "12/24",
    "holder": "holder",
    "payment_system": "VISA",
    "emitter": "halykbank",
    "cvc_required": false,
    "masterpass_card": false,
    "error": null,
    "action": null
  }
}

Идентификатором сохраненной карты будет являться card.id

2. Периодически запрашивать информацию о сохраненных картах плательщика по customer_id методом GetCards.

Статусы карты

Статус	Описание
PENDING	Первоначальный статус карты. Сохранение карты находится в обратоке.
REQUIRES_ACTION	Клиент перенаправлен на прохождение проверки 3DS.
APPROVED	Карта успешно сохранена.
DECLINED	Карта отклонена.
DELETED	Карта удалена.

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