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.

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.

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=

Merchant need to pass authorization hash with every request to API

Get Quote

POST /quotes

Create an Order

POST /orders

Get Order Status

GET /orders/{id}/status

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=

Content-Type

string required

Default:

application/json

Request body

Object

cryptocurrency_amount

number nullable

cryptocurrency

string

Examples:

BTCLTCETHBCHXRPIOTATRXZECDASHALGO

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"
}

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

Content-Type

string required

Default:

application/json

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 /orders/{id}/status

Allows merchant to check order status.

Path variables

id

string required

Order id

Example:

1b2e2fd5-e997-451a-89e5-93677d180612

Request headers

Hash

string optional

Authorization Hash

Example:

eyJtZXJjaGFudF9jb2RlIjoxMDAwLCJjdXN0b21lcl9yZWZlcmVuY2UiOiJVc2VyMSIsInRpbWVzdGFtcCI6IjEwMDAiLCJzaWduYXR1cmUiOiI2NjQyZmIxYmY2MDg0ZDNiZmEwZGViODNmOGZlNzFkMWM3YTczMDExOTUwMjI5MzJhMTAzYjFkOTczMWEwNTZiIn0=

Content-Type

string required

Default:

application/json

Responses

200 OK

Body

Object

data

Object

order_id

string

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

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.

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

string

status

string

customer_reference

string

crypto_amount

number

cryptocurrency_code

string

address

string

blockchain_tx_id

string