Koinal Checkout API

The Koinal Checkout integration enables cryptocurrency purchasing with credit cards. The system provides credit card payment processing together with crypto buying on-the-fly. Little or no further action needed by merchants to provide the service to their customers.
Introduction

The Koinal Checkout API is designed to be a simple interface to enable merchants’ customers to buy supported cryptocurrencies with their credit cards. Checkout provides both form and Restful API interfaces.

Authorization

Before reaching out to API or form interfaces, merchant should generate an encoded hash and pass it to form or API.

Hash generation and passing to Checkout API

Merchant needs to pass a base64 encoded json message to the form or API which includes merchant_code, customer_reference, timestamp and signature values.

Signature is used in decoded hash and protects the message from changes. Each request is signed by the signature.

Signature is calculated by merchant with secret key value (generated specifically for merchant)and values of the other JSON body parameters with SHA-256 hmac method. Secret is generated by Koinal.

For example, you have following parameters:

Secret: 11qq22ww

JSON body parameters and values: merchant_code: 1000, customer_reference: User1, timestamp: 1000

Then merchant will pass this JSON body:

{
    "merchant_code": 1000,
    "customer_reference": "User1",
    "timestamp": "1000"
}

Merchant will also need to calculate SHA-256 signature of the following string and add it to JSON body:

merchant_code + customer_reference + timestamp + secret

which is (for this example), hmac hash value of 1000User1100011qq22ww with SHA-256 algorithm equals: 6642fb1bf6084d3bfa0deb83f8fe71d1c7a7301195022932a103b1d9731a056b

Then merchant should add this to JSON Body as signature:

{"merchant_code":1000,"customer_reference":"User1","timestamp":"1000","signature":"6642fb1bf6084d3bfa0deb83f8fe71d1c7a7301195022932a103b1d9731a056b"}

The result string of hash after encoding it with base64 will be:

eyJtZXJjaGFudF9jb2RlIjoxMDAwLCJjdXN0b21lcl9yZWZlcmVuY2UiOiJVc2VyMSIsInRpbWVzdGFtcCI6IjEwMDAiLCJzaWduYXR1cmUiOiI2NjQyZmIxYmY2MDg0ZDNiZmEwZGViODNmOGZlNzFkMWM3YTczMDExOTUwMjI5MzJhMTAzYjFkOTczMWEwNTZiIn0=

API

Merchant need to pass authorization hash with every request to API

POST /quotes
POST /orders
GET /orders/{id}/status
Get Quote
POST /quotes

Allows merchant to get a quote. cryptocurrency_amount or currency_amount should be passed to calculate a quote.

Request headers

Hash
string required

Authorization Hash

Example:
eyJtZXJjaGFudF9jb2RlIjoxMDAwLCJjdXN0b21lcl9yZWZlcmVuY2UiOiJVc2VyMSIsInRpbWVzdGFtcCI6IjEwMDAiLCJzaWduYXR1cmUiOiI2NjQyZmIxYmY2MDg0ZDNiZmEwZGViODNmOGZlNzFkMWM3YTczMDExOTUwMjI5MzJhMTAzYjFkOTczMWEwNTZiIn0=

Request body

Object
cryptocurrency_amount
number nullable
cryptocurrency
string
Examples:
BTCLTCETHBCHXRP
currency_amount
number nullable
currency
string
Example:
USD

Responses

201 Created
Body
Object
data
Object
token
string
cryptocurrency_amount
number
cryptocurrency
string
currency_amount
number
currency
string
code
string
message
string
status
string
Response Example
{
    "data": {
        "cryptocurrency_amount": 0.10034116,
        "cryptocurrency": "BTC",
        "currency_amount": 1000,
        "currency": "USD",
        "token": "83771cad9663db92693bc57579182678"
    },
    "code": "00",
    "message": "APPROVED",
    "status": "APPROVED"
}
Create an Order
POST /orders

Allows Merchant to create a on order. Merchant should redirect customers to checkout URL returned by this call. Rest of the buying process will be handled on Koinal side.

Request headers

Hash
string required

Authorization Hash

Example:
eyJtZXJjaGFudF9jb2RlIjoxMDAwLCJjdXN0b21lcl9yZWZlcmVuY2UiOiJVc2VyMSIsInRpbWVzdGFtcCI6IjEwMDAiLCJzaWduYXR1cmUiOiI2NjQyZmIxYmY2MDg0ZDNiZmEwZGViODNmOGZlNzFkMWM3YTczMDExOTUwMjI5MzJhMTAzYjFkOTczMWEwNTZiIn0=
Authorization
string required

Token code from quote request

Example:
b4034a647879bd3b45a3d0e4ffe296a9

Request body

Object
token
string required

Token from get quote request

Example:
b4034a647879bd3b45a3d0e4ffe296a9
wallet_address
string required

Wallet address of the customer

destination_tag
string nullable

Destination tag for XRP addresses

ip_address
string

Merchant customer’s ip address

Responses

201 Created
Body
Object
data
Object
order_id
string
checkout_url
string

Checkout url that merchant should redirect

Get Order Status
GET /orders/{id}/status

Allows merchant to check order status.

Path variables

id
string required

Order id

Example:
12

Request headers

Hash
string optional

Authorization Hash

Example:
eyJtZXJjaGFudF9jb2RlIjoxMDAwLCJjdXN0b21lcl9yZWZlcmVuY2UiOiJVc2VyMSIsInRpbWVzdGFtcCI6IjEwMDAiLCJzaWduYXR1cmUiOiI2NjQyZmIxYmY2MDg0ZDNiZmEwZGViODNmOGZlNzFkMWM3YTczMDExOTUwMjI5MzJhMTAzYjFkOTczMWEwNTZiIn0=

Responses

200 OK
Body
Object
data
Object
order_id
integer

Order id

status
string

Order status

Example:
PAYMENT_WAITING
total_amount
string

Total fiat amount of order

currency_code
string

Currency code of order

cryptocurrency_amount
string

Cryptocurrency amount of order

cryptocurrency_code
string

Cryptocurrency code of order

blockchain_tx_id
string

Transaction id on blockchain

timestamp
integer

Timestamp of the request

code
string
message
string
status
string
Callbacks

After the transaction is processed, callback in JSON format is sent to callback URL provided by merchant.

Callbacks are always sent:

  • when received transaction was completed

Callback signature

Signature is used in callbacks and protects the message from changes. Each callback’s request is signed by the signature, signature of callback is sent in callback header.

Signature is calculated by Koinal from callback secret(generated for merchant) value and JSON body of callback request with SHA-256. Callback secret is also generated by Koinal and received by merchant with merchant code.

For example, you have following parameters:

Callback secret: 11qq22ww

Received callback’s JSON body

Then merchant will need to calculate SHA-256 signature of the following string:

{ “id”: 123, … }11qq22ww

The result string must be equal to string in the header Signature of callback.

POST /callback/url
Callback Request
POST /callback/url

Callback requests are sent with the following parameters.

Request headers

Content-Type
string required
Default:
application/json
Signature
string required

Callback signature

Request body

Object
order_id
integer
status
string
customer_reference
string
crypto_amount
number
cryptocurrency_code
string
address
string
blockchain_tx_id
string