Kanga Payment Gateway API | Kanga Exchange

Introduction

The Kanga Payment Gateway API provides cryptocurrency payment functionality for e-commerce. For a detailed description of the Kanga Payment Gateway, please see: About the Kanga Payment Gateway

CONTENTS

Transaction flow
Authentication
Nonce
GET PRICE ESTIMATE
START PAYMENT
CALLBACK
CREATE PAYMENT TOKEN
CHECK PAYMENT
Testing

Transaction flow

When the Kanga Payment Gateway payment option is selected, the store redirects the user to the payment gateway (START PAYMENT) via a URL that includes the following payment details:
- payment amount and settlement currency,
- a unique payment identifier (TRANSACTION_ID) generated by the store,
- (optional) item/order description.
The user completes the payment (if the ‘on-chain’ option is selected, this may take up to several days).
When the status of the payment changes, the Kanga Payment Gateway system sends a callback with the TRANSACTION_ID parameter to the URL defined in the Payment gateway API tab.
At any point, the store can check the status of the payment by executing the CHECK PAYMENT call.
The payment amount is transferred to the store immediately upon the completion of the payment.

Authentication

To use the Kanga Payment Gateway API, you need an API key and an API secret. They can be viewed under Payment gateway API. The API key must be included in all requests from your application to the Kanga Payment Gateway system. The API secret is used to sign each request (except GET PRICE ESTIMATE).

The signature is a HMAC512 hash of the request body, created with the API secret. The result is converted to a hex string and included in the API-Sig field of the request header.

Example implementation (Kotlin/Java):

import java.security.MessageDigest
import java.util.*
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
 
fun calculateHMAC512(data: String, key: String): String {
    val algorithm = “HmacSHA512”
    val secretKeySpec = SecretKeySpec(key.toByteArray(),algorithm)
    val mac = Mac.getInstance(algorithm)
    mac.init(secretKeySpec)
    val bytes = mac.doFinal(data.toByteArray())
    val formatter = Formatter()
    for (b in bytes) {
        formatter.format("%02x", b)
    }
    return formatter.toString()
}

Nonce

The nonce is a numeric parameter that uniquely identifies every call to the Kanga Payment Gateway API. The nonce must increase with each call. The recommended solution is to use the current timestamp (in milliseconds).

GET PRICE ESTIMATE

URL:

https://kanga.exchange/tpg/price/estimate

Required parameters:

`token`	string	Settlement curency
`quantity`	string	Payment amount (in the settlement currency)
`shopToken`	string	API key

Success response:

JSON object of available currency/price estimate pairs, e.g.:

{
  "EMT":"3090",
  "BTC":"0.0015",
  "ETH":"0.0685",
  "oPLN":"40.33"
}

Sample call:

curl https://api.kanga.exchange/api/tpg/price/estimate -d '{"token":"EMT", "quantity":"3000", "shopToken":"V7JM4R4361E80SfSEEffxlhJb2C1d"}'

START PAYMENT

URL:

https://kanga.exchange/tpg/payment/<API_KEY>

Required parameters:

`currency`	string	Transaction settlement currency
`amount`	string	Payment amount (in the settlement currency)
`transactionKey`	string	Unique payment identifier generated by the store

Optional parameters:

`name`	string	Order description or payment reference information
`email`	string	Payer e-mail address
`paymentToken`	string	See notes below
`forceCurrency`	string	Payment currency restriction (see notes below)

Notes:

If both the email and paymentToken parameters are provided, the user will be taken directly to the the payment page (skipping the e-mail address verification step). paymentToken has to be created by calling /api/v2/tpg/create/payment (description below).

The forceCurrency parameter allows to restrict the payment to a specific currency.

Example:

https://kanga.exchange/tpg/payment/V7JM4R4361E80SfSEEffxlhJb2C1d?currency=o[email protected]mailserver.com&paymentToken=LRmVFCEkBPbLjd8vsOADmnbGZYBjOoo6&forceCurrency=ETH

CALLBACK

URL:

https://<CALLBACK_URL>?transactionKey=<TRANSACTION_ID>

The CALLBACK_URL is defined by the store in the Payment gateway API tab. On payment status change, Kanga Payment Gateway calls the URL with the TRANSACTION_ID parameter.

On a 200 response, Kanga Payment Gateway assumes the status change information has been successfully transmitted to the store. On any other response, the system will repeat the call after 15 minutes, then after 1 hour, and after 6 hours.

CREATE PAYMENT TOKEN

URL:

https://api.kanga.exchange/api/v2/tpg/create/payment

Method:

POST

Required parameters:

`appId`	string	API key
`nonce`	integer	See the “Nonce” section above

Success response:

`result`	string	`ok`
`paymentToken`	string	Payment token to be used with the redirection link

Example:

{
  "result":"ok",
  "paymentToken":"xoLcXoC5spJA1PVZh0O7U0IRByYkuWhl"
}

Error response:

`result`	string	`fail`
`code`	integer	`9000` Invalid credentials (can be incorrect nonce)

Sample call:

curl -d '{"appId":"V7JM4R4361E80SfSEEffxlhJb2C1d", "nonce":1571776939}' -H "api-sig: 8fab071d251d17c1169263960f0c91b83fd82cc34f836bb67ace81c836a9cef115e6865448fff6e0fe370889b56f8f98b8940d1a8198bbb3b1c518123a138412" https://api.kanga.exchange/api/v2/tpg/create/payment

CHECK PAYMENT

URL:

https://api.kanga.exchange/api/v2/tpg/transaction

Method:

POST

Required parameters:

`id`	string	a unique payment identifier (`TRANSACTION_ID`)
`appId`	string	API key
`nonce`	integer	See the “Nonce” section above

Success response:

`result`	string	`ok`
`currency`	string	Settlement currency
`amount`	string	Payment amount
`state`	string	Can be `NEW`, `ACTIVE`, `PROCESSING`, `FINALIZING`, `FINALIZED`, `CANCELED`, `CANCELLING`, or `FAILED`.

Example:

{
  "result" : "ok",
  "currency" : "BTC",
  "amount" : "0.01",
  "state" : "ACTIVE"
}

Error response:

`result`	string	`fail`
`code`	integer	`9000` Invalid credentials (can be incorrect nonce) `9001` Transaction ID not found

Sample call:

curl -d '{"id":"ORDER34H773A1", "appId":"V7JM4R4361E80SfSEEffxlhJb2C1d", "nonce":1571775936}' -H "api-sig: f5319a6d448efedcbe144b8a33732d7323a078fa1ff061ce317c532a00ebed036872a4bb5f19075d1892196422d99130d0da34352a582de08d11980fedca94e2" https://api.kanga.exchange/api/v2/tpg/transaction

Testing

A dedicated call is provided for the purpose of testing the authorization mechanism:

URL:

https://api.kanga.exchange/api/v2/test

Method:

POST

Required parameters:

`appId`	string	Should be “TEST”
`nonce`	integer	Does not need to be incremented in a test call

Optional parameters:

`param1`	integer
`param2`	string

Success response:

result string ok

Error response:

result string fail

Sample call:

curl -d '{"appId":"TEST","nonce":1234}' -H "api-sig: 19626ab50989ecae16031cf6f90c90203d38b1d17797960d38551b80c37449c118e60050f941077c491ff50bdf48d21841a9379026b10903100708745f6c9a12" http://kanga.dev/api/v2/test

Notes:

The API secret for test call signing is: 8B2EFBECA2BEBB2C413BCFD7915E9209D80F3F4222042B31DD9D605E39F2035F.