Quickstart

Info

Here you can start the integration of your shop with ioka API and accept your first payment.

Preparation

In order to start the integration, you need to get access to the dashboard and create a shop. For authentication, get your shop's API key.

Prior to accepting real payments, you can test your integration in test environment. When paying in a test environment, everything goes like with real payments, but the money is not transferred anywhere.

For testing:

1. Create a test shop in dashboard.
2. Get your shop's API Key.
3. Use the following address:

https://stage-api.ioka.kz

Step 1: Create a new order

Order is the main entity in ioka API. The order stores data about the goods or services that need to be paid for. To create an order, you must specify the amount in minor currency units. For example, to create an order for 500 tenge, you need to enter 50000 (1 tenge = 100 tiyn). Other parameters are optional, but will help extend the order info and describe the payment process.

Important!

All requests to the ioka API must be sent from your server. To interact with the ioka API, you can use server-side SDK.

An example of a request to create an order:

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': 10000
})
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": 10000
}');
$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();

Step 2: Redirect your customer to the checkout page

In the body of the response from the ioka API, you will receive the created order in the UNPAID status. To accept the payment, redirect the user to the checkout_url address with a payment form for collecting your customer's card data.

An example of a created order object:

{
    "id": "ord_test",
    "shop_id": "shp_test",
    "status": "UNPAID",
    "created_at": "2022-05-05T11:12:47.687859",
    "amount": 50000,
    "currency": "KZT",
    "mcc": null,
    "capture_method": "MANUAL",
    "external_id": null,
    "description": null,
    "extra_info": null,
    "attempts": 10,
    "due_date": null,
    "customer_id": null,
    "card_id": null,
    "back_url": null,
    "success_url": null,
    "failure_url": null,
    "template": null,
    "access_token": "ord_test_secret_f35ec68f34cf780aa2537be74c3e5f241c0a4261a1b59ac524cb42e8eb4c0ad6",
    "checkout_url": "https://stage-checkout.ioka.kz/orders/ord_test",
    "payments": []
}

If you are creating a payment in a test environment, use one of the test cards to pay, e.g. pan=555555555555559, expiry_date=12/24, cvc=123

Step 3: Get payment result

An order can be considered successful once it has entered the PAID or ON_HOLD status, depending on the capture methods. If the user changes their mind about paying or something goes wrong, the order will remain in the UNPAID status.

To get the status of a payment, subscribe to notifications from ioka.

You can also monitor the status by requesting information about the order at a convenient frequency for you. To do this, you need an order identifier - the value of the id parameter in the created order object.

Hooray, you have accepted your first payment!

This example describes the basic integration for accepting a payment, where card data are collected on the ioka checkout page. If it doesn't suit your needs, you can choose one of the integrations scenarios.

Important!

Remember that you need to use the production API Key to accept real payments.