LetKnowPay Documentation

Introduction

The LetKnowPay API is a server-to-server integration, there is no redirect to a payment page or imbedded widget. The deposit and withdrawal page are customized by your team using the API data we send on your requests. API calls are implemented as standard HTTP POST (application/json) calls to https://pay.letknow.com/api/2 in production mode.

Supported currencies

The following is a list of currencies our Cryptocurrency Gateway currently support:
BTC, ETH, XRP, USDT (erc20), BCH, LTC, DASH, ZCASH, TUSD, USDC, PAX, USDT TRC20, USDTSOL, USDCSOL, TRX, BINANCEPAY

The following is a list of currencies our Fiat-To-Crypto Gateway currently support:
BTC, ETH, XRP, USDT (erc20), BCH, LTC, DASH, EUR, USD, USDT TRC20, USDTSOL, USDCSOL, ADA, ZEC

Currency code

When sending currency receive please use the following code for the following currencies:
BTC, ETH, XRP, USDT, BCH, LTC, DASH, ZEC, TUSD, USDC, PAX, USDTTRC20, USDTSOL, USDCSOL, TRX, BINANCEPAY

Note:

Please ask our managers for credentials to access our Gateway's API

API Setup

The only setup needed is to go to the Shops page and generate an API key. You will be given a private and public key used to authenticate your API calls. Make sure you don't share your private key with any 3rd parties!

Also, through the Shops page you may whitelist your needed IP address.

Authentication

HMAC

Every API call has a SHA-256 HMAC signature generated with your private key. Our server generates it's own HMAC signature and compares it with the API caller's. If they don't match the API call is discarded. The HMAC signature is sent as a HTTP header called 'C-Request-Signature'.

The HMAC signature is created from the POST data of "nonce" "shopId" and "shopKey" parameters in your request. For example if your API secret key (shopKey) was "shop_key_1" and API public key (shopId) was "public_key_1" (both without quotes) and you were using the "order" function the raw request might look like:

1234567890|public_key_1|shop_key_1

And the HMAC would be: 5dbe4862c4f7d8d071415cd465973ad61922bb592990e0647edf7ff20c99a322

HMAC PHP Example

<?php
$nonce = str_replace('.', '', microtime(true));
$shopId = 'public_key_1';
$shopKey = 'shop_key_1';
$signature = hash_hmac('sha256', "{$nonce}|{$shopId}|{$shopKey}", $shopKey);
?>

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

Nonce

Mandatory nonce (an integer that is always higher than in your previous API call) to prevent replay attacks. Note: API nonce processing is non-atomic so you always want to wait for an API call to return before making another. You can use, for example, php microtime function for nonce e.g. str_replace('.', '', microtime(true));). The nonce is sent as a HTTP header called 'C-Request-Nonce'.

Shop Pubkey (Your Shop ID)

The Shop Public key is sent as a HTTP header called 'C-Shop-Id'.

Crypto to crypto API calls

Get Crypto deposit address

This request generates a new Crypto deposit address (BTC in example below).

Please refer to the IPN (Webhooks) section to discover on how to process the deposits and withdrawals to/from generated addresses.

POST URL:

https://cmssupport.letknow.com/api/2/get_deposit_address

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

JSON Request:

{
    "currency":"BTC",
    "currency_receive":"BTC",
    "reference_id": "refid_0001",
	"client": {
		"id": "client_123456",
		"first_name": "Phil",
        "last_name": "MacNeely",
        "email": "hmacneely5@stumbleupon.com",
        "address": "276 Homewood Crossing",
    },
}

BINANCEPAY JSON Request:

{
    "currency":"BINANCEPAY",
    "currency_receive":"BINANCEPAY",
    "receive_amount":"40.99", // Mandatory only for BINANCEPAY
    "reference_id": "refid_0001",
	"client": {
		"id": "client_123456",
		"first_name": "Phil",
        "last_name": "MacNeely",
        "email": "hmacneely5@stumbleupon.com",
        "address": "276 Homewood Crossing",
    },
    "return_url": "https://yourshop.com/return/refid_0001",
}

Successful Response:

The API will synchronously return an array with field 'result' success or failed. If the 'result' field value is 'success' (case-sensitive) the API call was processed, otherwise it will contain an error message.

{
    "result":"success",
    "currency":"BTC",
    "currency_receive":"BTC",
    "address":"3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka",
    "account_id":"BTCBXUQOSLAEH58YVSSUJU8T8D5BWY",
    "crypto_destination_tag":"12345678", // Mandatory to receive deposits in XRP, EOS, XLM, XMR
	"reference_id": "refid_0001",
	"client": {
		"id": "client_123456",
    },
    "qr_code":"iVBORw0KGgoAAAANSxxxxxxxxxxxxxx",
    "timestamp":1234567890
}

BINANCEPAY Successful Response:

{
    "result":"success",
    "currency":"BINANCEPAY",
    "currency_receive":"BINANCEPAY",
    "address":"BINANCEPAY",
    "account_id":"BINANCEPAYQFVH0ADL2SYS0LGSNCQK",
	"reference_id": "refid_0001",
	"client": {
		"id": "client_123456",
    },
    "qr_code":"iVBORw0KGgoAAAANSxxxxxxxxxxxxxx",
    "universal_url":"https://app.binance.com/payment/secpay?linkToken=4daxxxxxxxx",
    "timestamp":1234567890
}

Error:

{
    "result":"failed",
    "error_code": "200",
    "error_message": "Validation error",
    "errors": {
        "currency_receive": [
            "The selected currency is invalid."
        ]
    }
    "timestamp": "1234567890",
}

Important!!!

The user must always generate a get deposit address request. However, it is possible that the user will send a multiple transaction to the same address without generating a get deposit address request. LetKnowPay will still send you the IPN response with the new LetKnowPay ID, Blockchain Transaction ID and the same client ID, however, the Reference ID will be used from the previous get deposit address request. Therefore, its important that you map incoming transactions from LetKnowPay using the Client ID and the LetKnowPay ID. And if you get an IPN with the same reference ID but with the new LetKnowPay ID you must record a new transaction using the new LetKnowPay ID. Reference ID is for your own accounting purposes, and reference ID is not mandatory.

Because one Client ID equals one address, you must make sure that you generate a get deposit request for a Client ID not the Reference ID.

Request fields

Parameter	Required?	Description	Length	Example
currency	YES	Currency of address to generate		BTC
currency_receive	YES	Currency of address to generate (mandatory field, receive Cryotocurrency should be the similar to the currency field)		BTC
receive_amount	Partial	Partially mandatory for BINANCEPAY		40.99
reference_id	no	Your reference id for accounting purposes	unique	refid_0001
client.id	YES	Client's ID in your shop, unique for each shop_id.	unique	client1
client.first_name	YES	Client's First Name in your Shop		John
client.last_name	YES	Client's Last Name in your Shop		Doe
client.email	YES	Client's E-mail in your Shop		john@doe.com
client.address	no	Client's postal address in your Shop	Maximum 255 chars	276 Homewood Crossing, Las Vegas, Nevada, US

Extra request fields only for BINANCEPAY

Parameter	Required?	Description	Length	Example
return_url	no	Valid URL for redirecting the customer after BinancePay order	Maximum 255 chars	https://yourshop.com/return/refid_0001

Response Fields

Parameter	Description
result	success or failed
error_code	Parameter "1" is no errors
error_message	Error message (in case of result "failed")
errors	Validation errors(in case of result "failed")
currency	Deposit address Cryptocurrency
currency_receive	Deposit address Cryptocurrency
crypto_destination_tag	Tag that should be provided for deposits in XRP, EOS, XLM, XMR.
address	Generated Deposit Address
account_id	Client's Account ID in LetKnowPay
reference_id	Your reference ID
client.id	Client's ID in your Shop
qr_code	Base64 encoded QR code with address and amount data (Example of use: img src="data:image/png;base64,iVBORw0KGgoAAAANSxxxxxxxxxxxxxx")
timestamp	Response timestamp

Extra response fields only for BINANCEPAY

Parameter	Description
universal_url	Universal url to finish the payment. string(512)

Crypto Withdraw (To external Crypto address or BinancePay)

This request creates a new transaction in selected Blockchain. Withdraws funds from your Account to the provided Crypto address. Be careful with addresses, this is the irreversible action.

Please refer to the IPN (Webhooks) section to discover on how to process the deposits and withdrawals to/from generated addresses.

POST URL:

https://cmssupport.letknow.com/api/2/withdraw

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

JSON Request:

Crypto Withdraw:
{
    "withdrawal_currency":"BTC",
    "withdrawal_address":"3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka",
    "withdrawal_destination_tag":"1234567", // For XRP, XLM, EOS
    "withdrawal_amount":"0.00000008",
    "subtract_fee_from_amount":true,
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
}

BinancePay Withdraw:
{
    "withdrawal_currency":"BINANCEPAY",
    "binance_id":1234567,
    "binance_pay_currency":"USDC",
    "withdrawal_amount":"20",
    "subtract_fee_from_amount":true,
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
}

Successful Response:

The API will synchronously return an array with field 'result' success or failed. If the 'result' field value is 'success' (case-sensitive) the API call was processed, otherwise it will contain an error message.

Crypto Withdraw:
{
    "result":"success",
	"withdrawal_id":"W1234567890",
    "withdrawal_currency":"BTC",
    "withdrawal_address":"3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka",
    "withdrawal_destination_tag":"1234567", // For XRP, XLM, EOS
    "withdrawal_amount":"0.00000008",
	"withdrawal_fee":"0.03500000", // Deducted from Merchant account if "subtract_fee_from_amount":true
    "transaction_id":"blockchain_txid",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
    "timestamp":1234567890,
}

BinancePay Withdraw:
{
    "result":"success",
	"withdrawal_id":"W1234567890",
    "withdrawal_currency":"BINANCEPAY",
    "withdrawal_address":"BINANCEPAY",
    "withdrawal_amount":"0.00000008",
	"withdrawal_fee":"0.03500000", // Deducted from Merchant account if "subtract_fee_from_amount":true
    "transaction_id":null,
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
    "timestamp":1234567890,
}

Error:

{
    "result":"failed",
    "error_code": "200",
    "error_message": "Validation error",
    "validation": {
        "order_id": [
            "Client ID is Required field"
        ]
    }
    "timestamp": "1234567890",
}

Important!!!

The user must have a profile with the LetKnowPay before making a withdrawal request. If such user does not exist you will get an error code: 8000 To create a user profile you must first generate a get deposit request. Once get deposit request is initiated the user may withdraw from the LetKnowPay.

If you are switching the gateway and you already have existing user, please run a command get deposit address for all your existing users, so they can proceed with the withdrawal without initiating a deposit request.

Request fields

Parameter	Required	Description	Length	Example
withdrawal_currency	YES	Curency to withdraw		BTC
withdrawal_address	Partial	Crypto address to withdraw funds to. Required for cryptocurrencies (except BINANCEPAY).		3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka
withdrawal_amount	YES	Amount to withdraw		0.00000008
subtract_fee_from_amount	YES	If set true, all fees will be automatically deducted from Merchant's account and client will get exact amount from "withdrawal_amount" field on their Crypto address. Otherwise, amount will be deducted from provided "withdrawal_amount".		true OR false
withdrawal_destination_tag	Partial	Partially mandatory for XRP, EOS, XLM, XMR currency.	8 decimals	12345678
binance_id	Partial	Partially mandatory for BINANCEPAY. Customer binance_id where to withdraw funds		1234567
binance_pay_currency	no	Currency on BinancePay side. Available: USDT, USDC. Default: USDC		USDT
reference_id	no	Your reference ID		refid_0001
client.id	YES	Client's ID in your Shop		client_123456

Response Fields

Parameter	Description
result	success or failed
error_code	Parameter "1" is no errors
error_message	Error message (in case of result "failed")
validation	Validation errors (in case of result "failed")
withdrawal_id	Withdrawal ID in LetKnowPay
withdrawal_currency	Withdrawal currency
withdrawal_address	Crypto Address of withdrawal (BINANCEPAY for BinancePay withdraw)
withdrawal_destination_tag	XRP destination_tag of withdrawal address
withdrawal_amount	Withdrawal amount
transaction_id	Blockchain transaction hash
shop_id	Your shop ID in LetKnowPay
reference_id	Your reference ID
client.id	Your client ID
timestamp	Withdrawal timestamp

Crypto Gateway IPN service (Webhooks)

Instant Payment Notification will be sent to Shop's Callback URL when Transaction arrives in the blockchain and when Transaction status is changed to "pending" or "success". Status will be changed to "success" after 5-10 confirmations depending on Cryptocurrency.

Webhook requests are subject to the following timeouts:
- connection timeout: 3 seconds
- request timeout: 40 seconds
Requests exceeding these time limits may be terminated by the sender.

Setup Callback URL

Deposit IPN examples:

Pending deposit transaction (Unconfirmed in Blockchain):
{
    "letknowpay_id": "TRX1234455677889",
    "nonce": "15880073107779",
    "signature": "d9d2c15e62aa988b2d1355a07b236a046d270e462db33615f127b0bf7c67cd97",
    "type": "receive",
    "account_id": "BTCR6KFFE7BWLWTP4RUWLV8DG1NJZQ",
    "address": "3GTMbi5iQH5nArvuEGsk6Vco9AmbmpwgkS",
    "crypto_destination_tag": "12345678", // For XRP, XLM, EOS, XMR
    "txid": "e71415cd465973ad61922bb592990e0647edf7ff20c",
    "amount": "0.00050000",
    "currency": "BTC",
    "currency_receive": "BTC",
    "status": "pending",
    "shop_id": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "reference_id": "btc-1",
    "client": {
        "id": "your_client_id"
    },
    "created": "0000-00-00 00:00:00",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1588007313
}

Successful deposit transaction (Confirmed in Blockchain):
{
    "letknowpay_id": "TRX1234455677889",
    "nonce": "15880073107779",
    "signature": "d9d2c15e62aa988b2d1355a07b236a046d270e462db33615f127b0bf7c67cd97",
    "type": "receive",
    "account_id": "BTCR6KFFE7BWLWTP4RUWLV8DG1NJZQ",
    "address": "3GTMbi5iQH5nArvuEGsk6Vco9AmbmpwgkS",
    "crypto_destination_tag": "12345678", // For XRP, XLM, EOS, XMR
    "txid": "e71415cd465973ad61922bb592990e0647edf7ff20c",
    "amount": "0.00050000",
    "currency": "BTC",
    "currency_receive": "BTC",
    "status": "success",
    "shop_id": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "reference_id": "btc-1",
    "client": {
        "id": "your_client_id"
    },
    "created": "0000-00-00 00:00:00",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1588007313
}

Note:
signature = SHA-256 from nonce|shop_id|shop_key
e.g HMAC from string 1234567890|public_key_1|shop_key_1 would be:
5dbe4862c4f7d8d071415cd465973ad61922bb592990e0647edf7ff20c99a322

Response Fields

Parameter	Description
letknowpay_id	LetKnowPay transaction ID
nonce	Unique identificator for signature
signature	SHA-256 from nonce\|shop_id\|shop_key
type	Transaction type (receive or withdraw)
account_id	Address owner account ID in LetKnowPay
txid	Blockchain transaction ID
status	pending success failed
amount	Transaction amount
currency	Transaction currency
address	Crypto Address
created	Date created
updated	Date updated
shop_id	LetKnowPay shop ID
client.id	Your's client ID
timestamp	Callback timestamp

POST URL:

Your shop CallBack URL, provided in Shop settings e.g. https://yourshop.com/ORDERID12345/IPN

Your Shop settings

Retries

1 retry if CallBack URL status is equal 200

3 synchronous retries if CallBack URL status is not equal 200

1 asynchronous retry once in 10,30,60,120 minutes if CallBack URL status is not equal 200

IPN will wait for Callback URL response for 20 seconds each retry

Withdrawal IPN examples:

Pending Withdrawal transaction (Unconfirmed in Blockchain):
{
    "nonce":"16037142613288",
    "signature":"b4754a261e7269a5c9a3caa345347tee5aa35766d85c530af",
    "shop_id":"EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "withdrawal_id":"WHDDBEMEAAENSLERVXP",
    "withdrawal_currency":"BTC",
    "withdrawal_address":"3GTMbi5iQH5nArvuEGsk6Vco9AmbmpwgkS",
    "crypto_destination_tag":"12345678", // XRP
    "withdrawal_amount":"1.03000000",
    "withdrawal_fee":"0.03500000",
    "transaction_id":"",
    "reference_id":"136612",
    "client":{
        "id":"client_1"
    },
    "type":"withdraw",
    "letknowpay_id":"WHT7JBEMEAAENSLN9NXP",
    "txid":"",
    "status":"pending",
    "created":"2020-10-26 14:01:59",
    "updated":"0000-00-00 00:00:00",
    "timestamp":1603714261
}

Successful Withdrawal transaction (Confirmed in Blockchain):
{
    "nonce":"16037142613288",
    "signature":"b4754a261e7269a5c9a3caa345347tee5aa35766d85c530af",
    "shop_id":"EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "withdrawal_id":"WHDDBEMEAAENSLERVXP",
    "withdrawal_currency":"BTC",
    "withdrawal_address":"3GTMbi5iQH5nArvuEGsk6Vco9AmbmpwgkS",
    "crypto_destination_tag":"12345678", // XRP
    "withdrawal_amount":"1.03000000",
    "withdrawal_fee":"0.03500000",
    "transaction_id":"e71415cd465973ad61922bb592990e0647edf7ff20c",
    "reference_id":"136612",
    "client":{
        "id":"client_1"
    },
    "type":"withdraw",
    "letknowpay_id":"WHT7JBEMEAAENSLN9NXP",
    "txid":"e71415cd465973ad61922bb592990e0647edf7ff20c",
    "status":"success",
    "created":"2020-10-26 14:01:59",
    "updated":"0000-00-00 00:00:00",
    "timestamp":1603714261
}

BinancePay Withdrawal transaction (Confirmed):
{
    "nonce":"16037142613288",
    "signature":"b4754a261e7269a5c9a3caa345347tee5aa35766d85c530af",
    "shop_id":"EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "withdrawal_id":"WHDDBEMEAAENSLERVXP",
    "withdrawal_currency":"BINANCEPAY",
    "withdrawal_address":"BINANCEPAY",
    "withdrawal_amount":"1.03000000",
    "withdrawal_fee":"0.03500000",
    "transaction_id":"",
    "reference_id":"136612",
    "client":{
        "id":"client_1"
    },
    "type":"withdraw",
    "letknowpay_id":"WHT7JBEMEAAENSLN9NXP",
    "txid":"",
    "binance_pay_currency":"USDC",
    "status":"success",
    "created":"2020-10-26 14:01:59",
    "updated":"0000-00-00 00:00:00",
    "timestamp":1603714261
}

Note:
signature = SHA-256 from nonce|shop_id|shop_key
e.g HMAC from string 1234567890|public_key_1|shop_key_1 would be:
5dbe4862c4f7d8d071415cd465973ad61922bb592990e0647edf7ff20c99a322

Response Fields

Parameter	Description
letknowpay_id	LetKnowPay transaction ID
nonce	Unique identificator for signature
signature	SHA-256 from nonce\|shop_id\|shop_key
type	Transaction type (receive or withdraw)
txid	Blockchain transaction ID
transaction_id	Blockchain transaction ID
status	pending waiting for approval success canceled failed
withdrawal_id	Withdrawal ID in LetKnowPay
withdrawal_currency	Withdrawal currency
withdrawal_address	Crypto Address of withdrawal (BINANCEPAY for BinancePay withdraw)
withdrawal_amount	Withdrawal amount
withdrawal_fee	Withdrawal overall fee
binance_pay_currency	Optional. Will be provided for BinancePay
created	Date created
updated	Date updated
shop_id	LetKnowPay shop ID
client.id	Your's client ID
timestamp	Callback timestamp

POST URL:

Your shop CallBack URL, provided in Shop settings e.g. https://yourshop.com/ORDERID12345/IPN

Your Shop settings

Retries

1 retry if CallBack URL status is equal 200

3 synchronous retries if CallBack URL status is not equal 200

1 asynchronous retry once in 10,30,60,120 minutes if CallBack URL status is not equal 200

IPN will wait for Callback URL response for 20 seconds each retry

Crypto to Fiat API calls

Get Fiat-To-Crypto deposit address.

This request generates a new Crypto deposit address, the funds received on which will be automatically converted to selected Fiat currency (USD or EUR).

Please refer to the IPN (Webhooks) section to discover on how to process the deposits and withdrawals to/from generated addresses.

POST URL:

https://cmssupport.letknow.com/api/2/get_deposit_address

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

JSON Request:

{
    "currency":"XRP",
    "currency_receive":"USD",
    "receive_amount":"40.99",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
        "first_name": "Phil",
        "last_name": "MacNeely",
        "email": "hmacneely5@stumbleupon.com",
        "address": "276 Homewood Crossing",
    },
}

Successful Response:

The API will synchronously return an array with field 'result' success or failed. If the 'result' field value is 'success' (case-sensitive) the API call was processed, otherwise it will contain an error message.

{
    "result": "success",
    "currency": "XRP",
    "currency_receive": "USD",
    "address":"r9kSGStGJxrLM8xv6aHaQg7beGjVy6ebqG",
    "crypto_destination_tag":"76959845",
    "account_id":"XRP833462YXSD8RODKTHQ9ZUJV3JGH",
    "reference_id":"xrp-usd-1",
    "client": {
        "id": "client_123456",
        "first_name": "Phil",
        "last_name": "MacNeely",
        "email": "hmacneely5@stumbleupon.com",
        "address": "276 Homewood Crossing",
    },
    "receive_amount":"40.99",
    "rate":"0.24253125",
    "crypto_amount":"123.69995400",
    "deposit_network_fee":"0.02",
    "qr_code":"iVBORw0KGgoAAAANSxxxxxxxxxxxxxx",
    "timestamp: "1603202569"
}

BINANCEPAY Successful Response:

{
    "result": "success",
    "currency": "BINANCEPAY",
    "currency_receive": "USD",
    "address":"BINANCEPAY",
    "account_id":"BINANCEPAYQFVH0ADL2SYS0LGSNCQK",
    "reference_id":"BINANCEPAY-USD-1",
    "client": {
        "id": "client_123456",
        "first_name": "Phil",
        "last_name": "MacNeely",
        "email": "hmacneely5@stumbleupon.com",
        "address": "276 Homewood Crossing",
    },
    "receive_amount":"40.99",
    "rate":"0.24253125",
    "crypto_amount":"123.69995400",
    "deposit_network_fee":"0.02",
    "qr_code":"iVBORw0KGgoAAAANSxxxxxxxxxxxxxx",
    "universal_url":"https://app.binance.com/payment/secpay?linkToken=4daxxxxxxxx",
    "timestamp: "1603202569"
}

Error:

{
    "result":"failed",
    "error_code": "200",
    "error_message": "Validation error",
    "errors": {
        "currency_receive": [
            "The selected currency is invalid."
        ]
    }
    "timestamp": "1234567890",
}

Important!!!

The user must always generate a get deposit address request. However, it is possible that the user will send a multiple transaction to the same address without generating a get deposit address request. LetKnowPay will still send you the IPN response with the new LetKnowPay ID, Blockchain Transaction ID and the same client ID, however, the Reference ID will be used from the previous get deposit address request. Therefore, its important that you map incoming transactions from LetKnowPay using the Client ID and the LetKnowPay ID. And if you get an IPN with the same reference ID but with the new LetKnowPay ID you must record a new transaction using the new LetKnowPay ID. Reference ID is for your own accounting purposes, and reference ID is not mandatory.

Because one Client ID equals one address, you must make sure that you generate a get deposit request for a Client ID not the Reference ID.

Request fields

Parameter	Required	Description	Length	Example
currency	YES	Currency of address to generate		BTC
currency_receive	YES	Fiat currency to which the Crypto deposit automatically convert to		USD or EUR
receive_amount	YES	Approximate amount of fiat currency you wish to receive (in USD or EUR)		40.99
reference_id	no	Your reference id	unique	refid_0001
client.id	YES	Client's ID in your shop, unique for each shop_id.	unique	client1
client.first_name	no	Client's First Name in your Shop		John
client.last_name	no	Client's Last Name in your Shop		Doe
client.email	YES	Client's E-mail in your Shop		john@doe.com
client.address	no	Client's postal address in your Shop	Maximum 255 chars	276 Homewood Crossing, Las Vegas, Nevada, US

Extra request fields only for BINANCEPAY

Parameter	Required?	Description	Length	Example
return_url	no	Valid URL for redirecting the customer after BinancePay order	Maximum 255 chars	https://yourshop.com/return/refid_0001

Response Fields

Parameter	Description
result	success or failed
error_code	Parameter "1" is no errors
error_message	Error message (in case of result "failed")
errors	Validation errors(in case of result "failed")
currency	Cryptocurrency of address to generate
currency_receive	Fiat currency to which the Crypto deposit automatically convert to
address	Generated Deposit Address
crypto_destination_tag	Destination tag, Mandatory to receive XRP deposits
account_id	Client's Account ID in LetKnowPay
reference_id	Your reference ID
client.id	Client's ID in your Shop
receive_amount	Approximate amount of fiat currency that you will receive after conversion (in USD or EUR)
crypto_amount	Crypto amount to deposit in BTC, ETH, XRP
deposit_network_fee	The deposit network fee is included in the crypto amount. Deposit network fee is charged to a client of the merchant for routing the funds to an exchange.
rate	Conversion rate at the moment of the request
qr_code	Base64 encoded QR code with address and amount data (Example of use: img src="data:image/png;base64,iVBORw0KGgoAAAANSxxxxxxxxxxxxxx")
timestamp	Response timestamp

Extra response fields only for BINANCEPAY

Parameter	Description
universal_url	Universal url to finish the payment. string(512)

Fiat-To-Crypto Withdraw (To external Crypto address or BinancePay)

This request creates a new transaction in selected Blockchain. Buys selected Crypto amount and Withdraws Fiat from your Account to the provided Crypto address. Be careful with addresses, this is the irreversible action.

Please refer to the IPN (Webhooks) section to discover on how to process the deposits and withdrawals to/from generated addresses.

POST URL:

https://cmssupport.letknow.com/api/2/buy_crypto_and_withdraw

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

JSON Request:

Fiat-To-Crypto Withdraw:
{
   "fiat_currency":"USD",
   "crypto_currency":"BTC",
   "crypto_address":"3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka",
   "crypto_destination_tag":"1234567", // For XRP, XLM, EOS
   "fiat_amount":"30.99",
   "reference_id": "refid_0001",
   "client": {
        "id": "client_123456",
    },
}

Fiat-To-BinancePay Withdraw:
{
   "fiat_currency":"USD",
   "crypto_currency":"BINANCEPAY",
   "binance_id":1234567,
   "binance_pay_currency":"USDC",
   "fiat_amount":"30.99",
   "reference_id": "refid_0001",
   "client": {
        "id": "client_123456",
    },
}

Successful Response:

The API will synchronously return an array with field 'result' success or failed. If the 'result' field value is 'success' (case-sensitive) the API call was processed, otherwise it will contain an error message.

Fiat-To-Crypto Withdraw:
{
    "result":"success",
    "letknowpay_id":"WR3VIJ7F6HETBCFEVW7B",
    "fiat_currency":"USD",
    "crypto_currency":"BTC",
    "crypto_address":"3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka",
    "crypto_destination_tag":"1234567", // For XRP, XLM, EOS
    "fiat_amount":"30.99",
    "crypto_amount":"0.00090001",
    "transaction_id":"blockchain_txid",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
    "timestamp":1234567890,
}

Fiat-To-BinancePay Withdraw:
{
    "result":"success",
    "letknowpay_id":"WR3VIJ7F6HETBCFEVW7B",
    "fiat_currency":"USD",
    "crypto_currency":"BINANCEPAY",
    "crypto_address":"BINANCEPAY",
    "fiat_amount":"30.99",
    "crypto_amount":"0.00090001",
    "transaction_id":null,
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456",
    },
    "timestamp":1234567890,
}

Error:

{
    "result":"failed",
    "error_code": "200",
    "error_message": "Validation error",
    "validation": {
        "order_id": [
            "Client ID is Required field"
        ]
    }
    "timestamp": "1234567890",
}

Important!!!

The user must have a profile with the LetKnowPay before making a withdrawal request. If such user does not exist you will get an error code: 8000 To create a user profile you must first generate a get deposit request. Once get deposit request is initiated the user may withdraw from the LetKnowPay.

If you are switching the gateway and you already have existing user, please run a command get deposit address for all your existing users, so they can proceed with the withdrawal without initiating a deposit request.

Request fields

Parameter	Required	Description	Length	Example
withdrawal_currency	YES	Curency to withdraw		1.00
withdrawal_address	Partial	Crypto address to withdraw funds to. Required for cryptocurrencies (except BINANCEPAY)		3LHeYhVufqfF4VSbyBf9DXVChBGDFV42Ka
withdrawal_amount	YES	Amount to withdraw		0.00000008
withdrawal_destination_tag	Partial	Mandatory tag for XRP currency		12345678
binance_id	Partial	Partially mandatory for BINANCEPAY. Customer binance_id where to withdraw funds		1234567
binance_pay_currency	no	Currency on BinancePay side. Available: USDT, USDC. Default: USDC		USDT
reference_id	no	Your reference ID		refid_0001
client.id	YES	Client's ID in your Shop		client_123456

Response Fields

Parameter	Description
result	success or failed
error_code	Parameter "1" is no errors
error_message	Error message (in case of result "failed")
validation	Validation errors (in case of result "failed")
withdrawal_id	Withdrawal ID in LetKnowPay
withdrawal_currency	Withdrawal currency
withdrawal_address	Crypto Address of withdrawal (BINANCEPAY for BinancePay withdraw)
withdrawal_amount	Withdrawal amount
transaction_id	Blockchain transaction hash
shop_id	Your shop ID in LetKnowPay
reference_id	Your reference ID
client.id	Your client ID
timestamp	Withdrawal timestamp

Fiat-To-Crypto Gateway IPN service (Webhooks)

Instant Payment Notification will be sent to Shop's Callback URL when Transaction arrives in the blockchain and when Transaction status is changed to "pending" or "success". Status will be changed to "success" after 5-10 confirmations depending on Cryptocurrency.

Webhook requests are subject to the following timeouts:
- connection timeout: 3 seconds
- request timeout: 40 seconds
Requests exceeding these time limits may be terminated by the sender.

Setup Callback URL

Deposit IPN examples:

Pending deposit transaction (Unconfirmed in Blockchain):
{
    "nonce": "16037025655557",
    "signature": "ab62c9129dcbef81ad0fd1e6cebbe7b63a68ab10a449279ec34c1c7735e27a41",
    "shop_id": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "fiat_currency": "USD",
    "crypto_currency": "XRP",
    "crypto_amount": "160.00000000",
    "rate": null,
    "fiat_amount": null,
    "fiat_amount_fee": null,
    "fiat_amount_without_fee": null,
    "address": "r9kNGStGJxrQK8xv6aHaQg7beGjVy6ebmG",
    "crypto_destination_tag": "76959865",
    "account_id": "XRP8MWF62YXCG8RODKTHQ9ZUJVXJGH",
    "reference_id": "xrp-usd-1",
    "client": {
        "id": "u1"
    },
    "type": "receive_crypto_and_sell",
    "letknowpay_id": "DX7LISRL5ZEPSVECQR1X",
    "status": "pending",
    "created": "2020-10-26 10:56:02",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1603702565
}

Successful deposit transaction (Confirmed in Blockchain):
{
    "nonce": "16037027742476",
    "signature": "6528ed6dcccb4f82dc57ac80b1ca946012931f704fb16332b662dc51613ccb84",
    "shop_id": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
    "fiat_currency": "USD",
    "crypto_currency": "XRP",
    "crypto_amount": "160.00000000",
    "rate": "0.25306830",
    "fiat_amount": 40.49,
    "fiat_amount_fee": 0.8,
    "fiat_amount_without_fee": 39.69,
    "address": "r9kNGStGJxrQK8xv6aHaQg7beGjVy6ebmG",
    "crypto_destination_tag": "76959865",
    "account_id": "XRP8MWF62YXCG8RODKTHQ9ZUJVXJGH",
    "reference_id": "xrp-usd-1",
    "client": {
        "id": "u1"
    },
    "type": "receive_crypto_and_sell",
    "letknowpay_id": "DX7LISRL5ZEPSVECQR1X",
    "status": "success",
    "created": "2020-10-26 10:56:02",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1603702774
}

Response Fields

Parameter	Description
letknowpay_id	LetKnowPay transaction ID
nonce	Unique identificator for signature
signature	SHA-256 from nonce\|shop_id\|shop_key
type	Transaction type (receive or withdraw)
account_id	Address owner account ID in LetKnowPay
txid	Blockchain transaction ID
status	pending success failed
amount	Transaction amount
currency	Transaction currency
address	Crypto Address
created	Date created
updated	Date updated
shop_id	LetKnowPay shop ID
client.id	Your's client ID
timestamp	Callback timestamp

POST URL:

Your shop CallBack URL, provided in Shop settings e.g. https://yourshop.com/ORDERID12345/IPN

Your Shop settings

Retries

1 retry if CallBack URL status is equal 200

3 synchronous retries if CallBack URL status is not equal 200

1 asynchronous retry once in 10,30,60,120 minutes if CallBack URL status is not equal 200

IPN will wait for Callback URL response for 20 seconds each retry

Fiat-To-Crypto Withdrawal IPN examples:

Pending Withdrawal transaction (Unconfirmed in Blockchain):
{
    "nonce": "16022339258963",
    "signature": "58dba9ba97b69388a3dabe7b83794f30d41ac297b68381693f1ce90446b720c8",
    "shop_id": "Ejo0vRe4REJ4a3fYaIGuEDw5GFgHnjDd",
    "fiat_currency": "USD",
    "crypto_currency": "BTC",
    "crypto_address": "3BertjLYwJPo5penreXQWgAjN86MedNAkB",
    "crypto_destination_tag":"1234567", // For XRP, XLM, EOS
    "fiat_amount": "30.99",
    "crypto_amount": "0.00175424",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456"
    },
    "type": "buy_crypto_and_withdraw",
    "letknowpay_id": "WR3VIJ7F6HETBCFEVW7B",
    "txid": "0",
    "status": "pending",
    "created": "2020-10-08 17:37:50",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1602233926
}

Successful Withdrawal transaction (Confirmed in Blockchain):
{
    "nonce": "16022339258963",
    "signature": "58dba9ba97b69388a3dabe7b83794f30d41ac297b68381693f1ce90446b720c8",
    "shop_id": "Ejo0vRe4REJ4a3fYaIGuEDw5GFgHnjDd",
    "fiat_currency": "USD",
    "crypto_currency": "BTC",
    "crypto_address": "3BertjLYwJPo5penreXQWgAjN86MedNAkB",
    "crypto_destination_tag":"1234567", // For XRP, XLM, EOS
    "fiat_amount": "30.99",
    "crypto_amount": "0.00175424",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456"
    },
    "type": "buy_crypto_and_withdraw",
    "letknowpay_id": "WR3VIJ7F6HETBCFEVW7B",
    "txid": "4c89ef23441bc995f204fdde7f41Fa86ce3362f77fbb3a6d830c71c4a89173f4",
    "status": "success",
    "created": "2020-10-08 17:37:50",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1602233926
}

BinancePay Withdrawal transaction (Confirmed):
{
    "nonce": "16022339258963",
    "signature": "58dba9ba97b69388a3dabe7b83794f30d41ac297b68381693f1ce90446b720c8",
    "shop_id": "Ejo0vRe4REJ4a3fYaIGuEDw5GFgHnjDd",
    "fiat_currency": "USD",
    "crypto_currency": "BINANCEPAY",
    "crypto_address": "BINANCEPAY",
    "fiat_amount": "30.99",
    "crypto_amount": "30.99",
    "reference_id": "refid_0001",
    "client": {
        "id": "client_123456"
    },
    "type": "buy_crypto_and_withdraw",
    "letknowpay_id": "WR3VIJ7F6HETBCFEVW7B",
    "txid": "",
    "binance_pay_currency":"USDC",
    "status": "success",
    "created": "2020-10-08 17:37:50",
    "updated": "0000-00-00 00:00:00",
    "timestamp": 1602233926
}

Note:
signature = SHA-256 from nonce|shop_id|shop_key
e.g HMAC from string 1234567890|public_key_1|shop_key_1 would be:
5dbe4862c4f7d8d071415cd465973ad61922bb592990e0647edf7ff20c99a322

Response Fields

Parameter	Description
letknowpay_id	LetKnowPay transaction ID
nonce	Unique identificator for signature
signature	SHA-256 from nonce\|shop_id\|shop_key
type	Transaction type (buy_crypto_and_withdraw)
txid	Blockchain transaction ID
status	pending waiting for approval success canceled failed
fiat_currency	Transaction fiat currency
crypto_currency	Transaction cryptocurrency
fiat_amount	Transaction fiat amount
crypto_amount	Transaction crypto amount
crypto_address	Crypto Address (BINANCEPAY for BinancePay)
binance_pay_currency	Optional. Will be provided for BinancePay
created	Date created
updated	Date updated
shop_id	LetKnowPay shop ID
client.id	Your's client ID
timestamp	Callback timestamp

POST URL:

Your shop CallBack URL, provided in Shop settings e.g. https://yourshop.com/ORDERID12345/IPN

Your Shop settings

Retries

1 retry if CallBack URL status is equal 200

3 synchronous retries if CallBack URL status is not equal 200

1 asynchronous retry once in 10,30,60,120 minutes if CallBack URL status is not equal 200

IPN will wait for Callback URL response for 20 seconds each retry

Payment Page API calls

Create deposit order

This request creates a new Payment Page deposit order. The funds received will be automatically converted to the settlement currency configured for the merchant (EUR, USD or USDT).

The order can be created in any of the following currencies:
USD, EUR, USDT, AED, AUD, AZN, BAM, BBD, BHD, BND, BOB, BRL, BSD, BTN, BWP, BZD, CAD, CHF, CZK, DKK, DOP, EGP, ERN, FJD, GBP, GEL, GHS, GMD, GTQ, HNL, ILS, INR, JOD, JPY, KWD, LSL, MAD, MDL, MKD, MUR, MVR, MXN, MYR, NAD, NIO, NOK, NZD, OMR, PAB, PEN, PGK, PHP, PLN, QAR, RON, SAR, SBD, SCR, SEK, SGD, SRD, SVC, SZL, THB, TJS, TMT, TOP, TRY, TTD, TWD, UYU, WST, XCD, ZAR

POST URL:

https://cmssupport.letknow.com/api/payment-page/create

Headers

Host: pay.letknow.com
Accept: */*
C-Request-Nonce: nonce
C-Shop-Id: shopId
C-Request-Signature: signature
Content-Type: application/json

JSON Request:

{
    "orderCurrencyCode":"EUR",
    "orderAmount":"100.99",
    "storeOperationId":"refid_0001",
    "returnUrl":"https://yourshop.com/return/refid_0001",
    "customerId":"customer_1",
    "customerEmail":"john@doe.com",
    "customerFirstName":"John",
    "customerLastName":"Doe",
}

Successful Response:

The API will synchronously return an array with the created order data. If the API call fails, the response array will contain an error message.

{
    "orderId":"8be3e718-3818-479d-8ec1-2e69c8b59450",
    "orderUrl":"https://payment.letknow.com/8be3e718-3818-479d-8ec1-2e69c8b59450",
}

Error Response:

{
    "error": 101,
    "errorTranslation": "Validation error",
    "errors": {
        "orderAmount": [
            "The order amount must be a number."
        ]
    }
}

Request fields

Parameter	Required	Type	Description	Example
orderCurrencyCode	Yes	string [3-4 chars]	The currency for the order	EUR
orderAmount	Yes	numeric	The order amount	100.99
storeOperationId	Yes	string [up to 255 chars]	Your reference ID for accounting purposes	refid_0001
returnUrl	No	string [up to 255 chars]	Valid URL for redirecting the customer after payment of the order	https://yourshop.com/return/refid_0001
customerId	Yes	string [up to 199 chars]	Customer's ID in your shop, unique for each shopId	customer_1
customerEmail	No	string [up to 255 chars]	Customer's valid email in your shop	john@doe.com
customerFirstName	No	string [up to 255 chars]	Customer's first name in your shop	John
customerLastName	No	string [up to 255 chars]	Customer's last name in your shop	Doe

Response fields

Parameter	Required	Type	Description
orderId	Yes	string [UUID v4]	Unique LetKnowPay ID of new deposit order
orderUrl	Yes	string [URL]	Link to pay for new deposit order
If response is error
error	Yes	integer	Error code
errorTranslation	Yes	string	Error message
errors	No	array	Validation errors

Payment Page deposit IPN (Webhooks)

An Instant Payment Notification (IPN) will be sent to Shop's Callback URL when the order status changes. The first of them will be sent after the customer starts paying - this is the "pending" order status. If the customer never starts paying, the first notification will be with the order status "expired". Further IPNs will be sent when the order status changes to final or pre-final.

The IPN contains a special boolean field "finalStep", which can be used to determine whether the order has a final status or not. Read more below.

Webhook requests are subject to the following timeouts:
- connection timeout: 3 seconds
- request timeout: 40 seconds
Requests exceeding these time limits may be terminated by the sender.

Setup Callback URL

Available order statuses

Status	Description	Final only
pending	Payment for the order was initiated by the customer	No
success	Payment has been received and the order has been successfully paid for by the customer	Yes
declined_by_user	Payment was received, but the customer declined to pay for the order	Yes
declined_by_system	Payment was received, but the customer did not take any action, and the system automatically declined the payment for the order	Yes
expired	The order lifetime has expired, the customer is not able to operate on it, but our system continues to wait for payment if it has been started but not completed	No
failed	Payment for the order was unsuccessful	Yes
refunded	Part of the payment was received, but the merchant refunded the funds to the client	Yes
archived	The order is finally closed, the system stops further actions on it, including payment	Yes

Deposit IPN examples:

Pending order status:
{
  "client": {
    "email": "john@doe.com",
    "firstName": "John",
    "id": "customer_1",
    "lastName": "Doe"
  },
  "letknowpayId": "33c28de5-276a-4abe-8108-e31daa6586a2",
  "order": {
    "created": "2025-01-01 00:00:01",
    "cryptoAmount": "41.121465",
    "cryptoAmountPaid": "0.000000",
    "cryptoAmountReceived": "0.000000",
    "cryptoCurrencyCode": "XRP",
    "cryptoCurrencyNetwork": "ripple",
    "finalStep": false,
    "orderAmount": "100.00",
    "orderAmountPaid": "0.00",
    "orderCurrencyCode": "USD",
    "rate": "2.43182000",
    "resolvedByEmail": null,
    "resolvedManually": false,
    "settlementAmount": null,
    "settlementCurrencyCode": "EUR",
    "settlementFee": null,
    "settlementNetAmount": null,
    "settlementRate": null,
    "status": "pending"
  },
  "shopId": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
  "storeOperationId": "refid_0001",
  "type": "payment_page_deposit_order",
  "nonce": "1742373483362",
  "signature": "12ecfd6ab6419be2beb0a6de013a4e575f2439bb5c9d94d759e7fe07243f34e6",
  "timestamp": 1742373483
}

Success order status:
{
  "client": {
    "email": "john@doe.com",
    "firstName": "John",
    "id": "customer_1",
    "lastName": "Doe"
  },
  "letknowpayId": "33c28de5-276a-4abe-8108-e31daa6586a2",
  "order": {
    "created": "2025-01-01 00:00:01",
    "cryptoAmount": "41.121465",
    "cryptoAmountPaid": "41.121465",
    "cryptoAmountReceived": "41.121465",
    "cryptoCurrencyCode": "XRP",
    "cryptoCurrencyNetwork": "ripple",
    "finalStep": true,
    "orderAmount": "100.00",
    "orderAmountPaid": "100.00",
    "orderCurrencyCode": "USD",
    "rate": "2.43182000",
    "resolvedByEmail": "john@doe.com",
    "resolvedManually": true,
    "settlementAmount": "92.58",
    "settlementCurrencyCode": "EUR",
    "settlementFee": "0.50",
    "settlementNetAmount": "92.08",
    "settlementRate": "2.25148000",
    "status": "success"
  },
  "shopId": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
  "storeOperationId": "refid_0001",
  "type": "payment_page_deposit_order",
  "nonce": "17423740286524",
  "signature": "bb17e17921421e93ea6379ba53782c113fedd3a6507cc07bf1801b9ff739a55f",
  "timestamp": 1742374028
}

Expired order status:
{
  "client": {
    "id": "customer_2"
  },
  "letknowpayId": "650e74ea-9635-4712-a7fb-291ba12be97e",
  "order": {
    "created": "2025-02-02 00:00:02",
    "cryptoAmount": null,
    "cryptoAmountPaid": null,
    "cryptoAmountReceived": null,
    "cryptoCurrencyCode": null,
    "cryptoCurrencyNetwork": null,
    "finalStep": true,
    "orderAmount": "50.00",
    "orderAmountPaid": "0.00",
    "orderCurrencyCode": "EUR",
    "rate": null,
    "resolvedByEmail": null,
    "resolvedManually": false,
    "settlementAmount": null,
    "settlementCurrencyCode": "EUR",
    "settlementFee": null,
    "settlementNetAmount": null,
    "settlementRate": null,
    "status": "expired"
  },
  "shopId": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
  "storeOperationId": "refid_0002",
  "type": "payment_page_deposit_order",
  "nonce": "17423766683253",
  "signature": "328e22d4feba2bc0ff6e2445aed46b414852d7396b7684ec7be4d5f6d996c397",
  "timestamp": 1742376668
}

Refunded order status:
{
  "client": {
    "id": "customer_3",
  },
  "letknowpayId": "e96f094f-2d81-4c4b-9be1-fc0dce9f6569",
  "order": {
    "created": "2025-03-03 00:00:03",
    "cryptoAmount": "124.373984",
    "cryptoAmountPaid": "0.000000",
    "cryptoAmountReceived": "500.000000",
    "cryptoCurrencyCode": "XRP",
    "cryptoCurrencyNetwork": "ripple",
    "finalStep": true,
    "orderAmount": "300.000000",
    "orderAmountPaid": "0.000000",
    "orderCurrencyCode": "USDT",
    "rate": "2.41208000",
    "resolvedByEmail": "john@doe.com",
    "resolvedManually": true,
    "settlementAmount": null,
    "settlementCurrencyCode": "EUR",
    "settlementFee": null,
    "settlementNetAmount": null,
    "settlementRate": null,
    "status": "refunded"
  },
  "shopId": "EjofvReMREJ4aGfYaIGuEDw5GDl8Dd",
  "storeOperationId": "refid_0003",
  "type": "payment_page_deposit_order",
  "nonce": "17422955127896",
  "signature": "0200c211019d730b2389a51d1774620d3720ab7ffae5a97109fc93a601fefb42",
  "timestamp": 1742295512
}

Note:
signature = SHA-256 from nonce|shop_id|shop_key
e.g HMAC from string 1234567890|public_key_1|shop_key_1 would be:
5dbe4862c4f7d8d071415cd465973ad61922bb592990e0647edf7ff20c99a322

IPN fields

Parameter	Required	Nullable	Type	Description
client.id	Yes	No	string	The customer's unique ID assigned during order creation
client.email	No	Yes	string	The customer's email address provided during order creation
client.firstName	No	Yes	string	The customer's first name provided during order creation
client.lastName	No	Yes	string	The customer's last name provided during order creation
letknowpayId	Yes	No	string [UUID v4]	The unique order ID assigned by LetKnowPay
order.created	Yes	No	string [Datetime]	Order creation date and time
order.cryptoAmount	Yes	Yes	string [Numeric]	Initial order amount in cryptocurrency equivalent `order.orderAmount / order.rate`
order.cryptoAmountPaid	Yes	Yes	string [Numeric]	The amount of cryptocurrency that have already been used to pay for the order
order.cryptoAmountReceived	Yes	Yes	string [Numeric]	The amount of cryptocurrency already received from the customer
order.cryptoCurrencyCode	Yes	Yes	string [3-4 chars]	Cryptocurrency associated with the customer's chosen payment method
order.cryptoCurrencyNetwork	Yes	Yes	string	Crypto network for associated cryptocurrency
order.finalStep	Yes	No	boolean	This flag indicates whether the order status is final. If set to true, the order status will no longer change, and this will be the final IPN notification. If set to false, the order status may still change. For example, if a client chooses to pay with cryptocurrency and receives a deposit address from our system but fails to send funds before the order expires, we will send you an IPN with the order status expired and the flag set to false. However, we maintain a link between the order and the issued address for some time, even after the order has expired. If the client later sends the required amount, we will accept their payment and complete the order. After that, we will send you an IPN with the order status success and the flag set to true.
order.orderAmount	Yes	No	string [Numeric]	Initial order amount obtained from your order creation request `order.cryptoAmount * order.rate`
order.orderAmountPaid	Yes	No	string [Numeric]	The amount of funds received that have already been used to pay for the order
order.orderCurrencyCode	Yes	No	string [3-4 chars]	Initial order currency obtained from your order creation request
order.rate	Yes	Yes	string [Numeric]	Exchange rate between order currency and cryptocurrency
order.resolvedByEmail	Yes	Yes	string	The user email who performed the manual action, if applicable
order.resolvedManually	Yes	No	boolean	This flag indicates whether a manual action was performed on the order.
order.settlementAmount	Yes	Yes	string [Numeric]	The total amount to be settled in the settlement currency. This is the value of the amount paid by the customer, converted to the settlement currency `order.cryptoAmountPaid * order.settlementRate`
order.settlementCurrencyCode	Yes	No	string [3-4 chars]	The currency code used for settlement (one of EUR, USD or USDT)
order.settlementFee	Yes	Yes	string [Numeric]	The fee charged by the system for processing the transaction. This fee is deducted from the settlement amount
order.settlementNetAmount	Yes	Yes	string [Numeric]	The final amount the merchant will receive after all fees have been deducted. `order.settlementAmount - order.settlementFee`
order.settlementRate	Yes	Yes	string [Numeric]	Exchange rate between cryptocurrency and settlement currency
order.status	Yes	No	string	Current order status (the list of available values can be found above)
shopId	Yes	No	string	Your shop's unique ID in LetKnowPay
storeOperationId	Yes	No	string	Reference ID assigned during order creation
type	Yes	No	string	The type of operation associated with this IPN. For Payment Page deposit orders, this value is always "payment_page_deposit_order".
nonce	Yes	No	string	A unique identifier used for signature generation
signature	Yes	No	string	SHA-256 hash generated from nonce, shopId and shopKey (nonce\|shopId\|shopKey)
timestamp	Yes	No	integer	Timestamp of the webhook event

POST URL:

Your shop CallBack URL, provided in Shop settings e.g. https://yourshop.com/ipn/refid_0001

Your Shop settings

Retries

We will continue attempting to send you a webhook until we receive a response code confirming the successful processing of our request (e.g., code 200).

The maximum number of attempts is 10, with progressively increasing intervals between retries:
- The first three attempts will be made at 1-minute intervals.
- There will be a 10-minute gap before the fourth attempt.
- There will be a 30-minute gap before the fifth attempt.
- The intervals will continue increasing in a similar pattern.
- The final, tenth attempt will be made 72 hours after the ninth attempt.

Error Table

Below is an explanation of possible system error codes:

Code	Description
200	Request data validation error
100	Shop does not exist
105	Shop does not exist
110	Merchant does not exist
120	Incorrect Signature
130	Order with this order_id already exist
140	Order does not exist
150	Gateway error
160	Access denied
170	Shop IP access denied
8000	User does not exist to make a withdrawal request

Example Code Snippets

For your convenience, you can use these examples for easier integration.

Get Deposit Address (PHP+CUrl)

<?php
// Variables
$requestUrl = 'https://cmssupport.letknow.com/api/2/get_deposit_address';
$nonce = str_replace('.', '', microtime(true));
$shopId = 'shop_id';
$shopKey = 'shop_key';

// Generate signature
$signature = hash_hmac('sha256', "{$nonce}|{$shopId}|{$shopKey}", $shopKey);

// Set headers
$requestHeader = [
	"C-Request-Nonce: {$nonce}",
	"C-Request-Signature: {$signature}",
	"C-Shop-Id: {$shopId}",
	"Content-Type: application/json"
];

// Set request body
$request = [
	'currency' => 'BTC',
	'currency_receive' => 'BTC',
    'reference_id' => 'refid_0001',
	'client' => [
		'id' => 'client_123456',
		'first_name' => 'Phil',
		'last_name' => 'MacNeely',
		'email' => 'hmacneely1@stumbleupon.com',
		'address' => '276 Homewood Crossing',
	],
];
$requestJson = json_encode($request);

// Set curl
$ch = curl_init($requestUrl);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, $requestHeader);
$response = curl_exec($ch);

// Http response
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Header & body response
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $headerSize);
$response = substr($response, $headerSize);

// Curl debug
$error = curl_error($ch);
$errorCode = curl_errno($ch);
curl_close($ch);

// Get parsed result
$parsedResult = (array)json_decode($response, 1);

print_r($parsedResult);

Withdrawal (PHP+CUrl)

<?php
// Variables
$requestUrl = 'https://cmssupport.letknow.com/api/2/withdraw';
$nonce = str_replace('.', '', microtime(true));
$shopId = 'shop_id';
$shopKey = 'shop_key';

// Generate signature
$signature = hash_hmac('sha256', "{$nonce}|{$shopId}|{$shopKey}", $shopKey);

// Set headers
$requestHeader = [
	"C-Request-Nonce: {$nonce}",
	"C-Request-Signature: {$signature}",
	"C-Shop-Id: {$shopId}",
	"Content-Type: application/json"
];

// Set request body
$request = [
	'withdrawal_currency' => 'BTC',
	'withdrawal_address' => '1NRkk5JmW4LajR1wSa7LA8AJs6muujWhun',
	'withdrawal_amount' => '0.0005',
	'reference_id' => 'refid_0001',
	'client' => [
		'id' => 'client_123456',
	],
];
$requestJson = json_encode($request);

// Set curl
$ch = curl_init($requestUrl);
curl_setopt($ch, CURLOPT_CONNECTTIMEOUT, 60);
curl_setopt($ch, CURLOPT_TIMEOUT, 60);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, 0);
curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, 0);
curl_setopt($ch, CURLOPT_HEADER, 1);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $requestJson);
curl_setopt($ch, CURLOPT_HTTPHEADER, $requestHeader);
$response = curl_exec($ch);

// Http response
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

// Header & body response
$headerSize = curl_getinfo($ch, CURLINFO_HEADER_SIZE);
$header = substr($response, 0, $headerSize);
$response = substr($response, $headerSize);

// Curl debug
$error = curl_error($ch);
$errorCode = curl_errno($ch);
curl_close($ch);

// Get parsed result
$parsedResult = (array)json_decode($response, 1);

print_r($parsedResult);

Still have questions?

Ask our Support Team at support@letknow.zendesk.com