Kanga TPG API

Introduction

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

Transaction flow
  1. When the Kanga TPG 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.
  2. The user completes the payment (if the ‘on-chain’ option is selected, this may take up to several days).
  3. When the status of the payment changes, the Kanga TPG system sends a callback with the TRANSACTION_ID parameter to the URL defined in the TPG TPG API tab.
  4. At any point, the store can check the status of the payment by executing the CHECK PAYMENT call.
  5. The payment amount is transferred to the store immediately upon the completion of the payment.
Authentication

To use the Kanga TPG API, you need an API key and an API secret. They can be viewed under TPG TPG API. The API key must be included in all requests from your application to the Kanga TPG 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 TPG 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 TPG TPG API tab. On payment status change, Kanga TPG calls the URL with the TRANSACTION_ID parameter.

On a 200 response, Kanga TPG 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.