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 flowAuthentication
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:
{ "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
.