Skip to main content

Быстрый старт

Информация

Здесь вы можете начать интеграцию вашего магазина с ioka API и принять свой первый тестовый перевод.

Подготовка к интеграции

Чтобы начать работать с ioka, вам нужно зарегистрироваться, получить доступ к личному кабинету, и создать свой первый магазин для принятия платежей. Для аутентификации, вам нужно получить в личном кабинете ключи доступа к API для вашего магазина.

Прежде чем начать проводить реальные переводы, вы можете проверить свою интеграцию в тестовом магазине. При переводе в тестовом магазине все проходит, как при настоящих переводах, но деньги никуда не переводятся.

Для тестирования:

  1. Создайте тестовый магазин в личном кабинете.
  2. Получите ключ доступа - API Key.
  3. Используйте следующий адрес в запросах к API:
https://stage-api.ioka.kz

Шаг 1: Создайте Корпоративную карту

Корпоративная карта карта магазина, которая будет хранится в системе ioka. Для того чтобы создать корпоративную карту в системе ioka, необходимо ввести номер корпоративной карты, cvc, срок действия карты. Остальные параметры необязательны, но помогут дополнить информацию о корпоративной карте. В теле ответа от ioka API вы получите созданный объект корпоративной карты где будет указан идентификатор корпоративной карты в системе ioka: corp_card_id.

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

Важно!

Все запросы к ioka API необходимо отправлять с вашего сервера. Для взаимодействия с ioka API вы можете использовать готовые серверные SDK.

Пример запроса на создание корпоративной карты:

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

{
"pan": "4405645000006150",
"cvc": "111",
"expiry_date": "09/24"
}

Пример созданного объекта корпоративной карты:

{
"id": "crp_1G67S8JSTX",
"holder": null,
"external_id": null,
"pan_masked": "440043******1176",
"emitter_code": "halykbank",
"emitter_name": "Народный банк"
}

Шаг 2: Создание заказа

Далее необходимо создать заказ на перевод. Для того чтобы создать заказ на перевод, необходимо ввести сумму для перевода в минорных денежных единицах, тип перевода ('TOPUP' - пополнение корпоративной карты, 'PAYOUT' - выплата из корпоративной карты) и идентификатор корпортивной карты. Например, для создания заказа на сумму 500 тенге, необходимо ввести 50000 (1 тенге = 100 тиын). Остальные параметры необязательны, но помогут дополнить информацию о заказе на перевод.

Пример запроса на создание заказа:

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

{
"amount": 50000,
"type": "TOPUP",
"corp_card_id": "crp_15G0KQ9S0C"
}

Шаг 3: Перенаправьте клиента на страницу перевода

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

Пример созданного объекта заказа:

{
"order": {
"id": "tro_QFT1G30H2F",
"status": "NOT_TRANSFERRED",
"created_at": "2022-06-04T22:07:26.897608",
"shop_id": "shp_6KH0XU8A3W",
"type": "PAYOUT",
"amount": 500,
"currency": "KZT",
"external_id": null,
"description": null,
"extra_info": null,
"due_date": null,
"corp_card_id": "crp_15G0KQ9S0C",
"back_url": null,
"success_url": null,
"failure_url": null,
"template": null,
"checkout_url": "https://dev-transfers.ioka.kz/transfer-orders/tro_QFT1G30H2F"
},
"order_access_token": "tro_QFT1G30H2F_secret_f66a17973a51d218bab4eca90f4a0a0722aab5196863bdfa02acc2382add1b5a"
}

Если вы создаете заказ для тестового магазина, для переводов используйте одну из тестовых карт, например pan=4405645000006150, expiry_date=09/25, cvc=643

Шаг 4: Получите результат перевода

Заказ можно считать успешным, как только он перешел в статус TRANSFERRED. Если пользователь передумает переводить или что-то пойдет не так, заказ останется в статусе NOT_TRANSFERRED.

Вы можете следить за статусом, запрашивая информацию о заказе с удобной для вас периодичностью. Для этого вам понадобится идентификатор заказа — значение параметра id в созданном объекте заказа.

Ура, вы приняли первый перевод!

Важно!

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