API Documentation

Welcome to the Cryptopay REST API documentation. This API (Application Programming Interface) will allow you to access the functionality of this exchange by means of HTTP requests, making integration with your own applications possible.

Connecting to the API

You can access the API at the following url:

https://api.cryptopay.io/v1/

Usage

In order to use a public API method, you must make an HTTP request to the appropriate endpoint for that particular method, sending the appropriate GET parameters for that method.

To access protected API methods, you must obtain an API key/secret pair. Their usage is explained further ahead in this document.

API Methods

In order to access these methods, you must obtain an API key/secret pair to authenticate your request.

#status_code 100 means success, otherwise request consider encounter error response.
{"status_code":"100","message":"Success."}

Obtaining An API Key

Your API Key and Secret were generated upon your website creation completed, you are able to retrieve both of them from website list.

Authenticating Your Request

To authenticate a request with your API key/secret pair, you must include the following parameters in your GET :

• api_key (string) - The API key that you generated.
• nonce (int) – UTC 0 timestamp to prevent replay attack.
• signature (string) – An HMAC-SHA256 signature of the JSON-encoded parameters of the request, signed using the API secret that was generated together with the api_key. These parameters include the api_key and nonce. This signature should then be added to the request parameters.

Possible errors during this phase:

{"status_code":"102","message":"Invalid signature."}

{"status_code":"103","message":"System is under maintenance."}

{"status_code":"104","message":"System rollback duplicated transaction."}

{"status_code":"110","message":"API not valid."}

{"status_code":"111","message":"Nonce not valid."}

{"status_code":"112","message":"Your usage has exceed the rate limit."}

{"status_code":"134","message":"System rollback duplicated transaction."}

We know that generating a signature might be a bit intimidating if you’re doing it for the first time, so please see the following examples:

Coin Properties

Get Exchange Rate & Supported Currencies

GET https://api.cryptopay.io/v1/getcurrencyrate

#php example

$api_key = "YOUR_API_KEY";
$api_secret = "YOUR_API_SECRET";

//make sure time is utc 0, and cast it into string
$utc_time = (string)time();

$commands['api_key'] = $api_key;
$commands['nonce'] = $utc_time; 
	
// create the signature
$signature = hash_hmac('sha256', json_encode($commands), $api_secret);

// add signature to request parameters
$commands['signature'] = $signature;

//The url you wish to send the GET request to
$url = "https://api.cryptopay.io/v1/getcurrencyrate/?";

//url-ify the data for the GET
$fields_string = http_build_query($commands);

//open connection
$ch = curl_init();

//set the url with GET data
curl_setopt($ch,CURLOPT_URL, $url . $fields_string);

//So that curl_exec returns the contents of the cURL; rather than echoing it
curl_setopt($ch,CURLOPT_RETURNTRANSFER, true); 

//execution result
$result = curl_exec($ch);
$result = json_decode($result, true);

Response:

results (Array) – An Array of currencies with its fiat/crypto exchange rate and currency availability status.

Example Response:

#Status online or offline used to indicate currency availability

{"status_code":"100","message":"Success.","currencies":[{"USDT_ERC20":{"status":"online","type":"crypto","fiat_currency":{"USD":"1.0013","CNY":"6.9907"}},"USD":{"status":"online","type":"fiat","crypto_currency":{"USDT_ERC20":"0.9987"}},"CNY":{"status":"online","type":"fiat","crypto_currency":{"USDT_ERC20":"0.1430"}}}]}

Get rate limit usage

GET https://api.cryptopay.io/v1/getrateusage

Example Response:

{"status_code":100,"message":"Success.","usage":{"remaining_usage":{"api\/minute":"195","api\/hour":"1995","api\/day":"19995"},"usage_limit":{"api\/minute":"200","api\/hour":"2000","api\/day":"20000"}}}

* Note: This api won't deduct api usage.

Balances And Info

GET https://api.cryptopay.io/v1/getbalances

Response:

results (Array) – An Array of user balances in available currencies.

Generate Deposit Address

This method came into use when merchant need to generate new address for their client to deposit cryptocurrency on the merchant’s website

GET https://api.cryptopay.io/v1/generatedepositaddress

Parameters:

crypto_type (string) – (Mandatory) Cryptocurrency code retrieved from the getcurrencyrate method above.

exchange_to(string) – (Optional) Fiat currency code retrieved from the getcurrencyrate method above. (only needed for seamless deposit type)

deposit_type (string) – (Mandatory) Either seamless or transfer where seamless is the most common deposit type used by merchant where we instantaneously convert the crypto that the customer deposited to fiat whereas if you choose transfer type, you will get the crypto amount as what user have transferred.

amount (float) – (Mandatory) If you select seamless, this will be fiat amount otherwise this is crypto amount.

unique_id(string) - (Mandatory) The self generated unique id for this request. Valid format could be combination of digit (0-9), hyphen (-), alphabet (a-z, case insensitive) and length is between 1 and 50. E.g. 123, 1-232, 9999-0-1, aaa, aaa-bbb-123

Example Response:

{"status_code":"100","message":"Success.", "deposit_details":{"unique_id":"1583093795","crypto_type":"BTC","deposit_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","crypto_amount":"0.00003231","deposit_type":"seamless","exchange_to":"USD","exchange_price":9283.86,"fiat_amount":"0.3","time_created":"2020-03-01 20:16:36"}}

unique_id(string) - The unique id that you have passed in the request.

crypto_type(string) - The crypto currency to deposit

deposit_address(string) - The unique deposit address for the request.

crypto_amount(float) - The amount of crypto currency that needed to be deposited.

deposit_type(string) - The deposit type(“seamless” or “transfer”).

exchange_to(string) - The fiat currency to be converted to. (Applicable only for seamless)

exchange_price(float) - The reference exchange price. (Applicable only for seamless)

fiat_amount(float) - The reference fiat amount. (Applicable only for seamless)

time_created(datetime) - The UTC time that this request was created.

* Note: if crypto_amount in response param is lower than minimum coin amount, then an error will be response accordingly.

List All Deposit Addresses

This method came into use when merchant need to list all the deposits in ascending way that they have created

GET https://api.cryptopay.io/v1/getdepositlists

Parameters:

crypto_type (string) - (Mandatory) The crypto currency.

page (int) – (Mandatory) This should start with 1 or any number of page.

Example Response:

{"status_code":"100","message":"Success.","depositlists":[{"unique_id":"1583093795","crypto_type":"BTC","deposit_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","crypto_amount":"0.00003231","deposit_type":"seamless","exchange_to":"USD","exchange_price":9283.86,"fiat_amount":"0.3","deposited_amount":"0.00003231","time_created":"2020-03-01 20:16:36", "status":"exact"},{"unique_id":"1582197162","crypto_type":"BTC","deposit_address":"1N8GkJmCdoXumBw1cJJMesRoVsRbgJ6Ycoq","crypto_amount":"0.00003231", "deposit_type":"transfer","deposited_amount":"0.00003000", "time_created":"2020-02-20 11:12:43", "status":"insufficient"}], "page_info":{"pages":94}}

Each deposit item consists of

unique_id(string) - The unique id that you have passed in the request.

crypto_type(string) - The crypto currency to deposit

deposit_address(string) - The unique deposit address for the request.

crypto_amount(float) - The amount of crypto currency that needed to be deposited.

deposit_type(string) - The deposit type(“seamless” or “transfer”).

exchange_to(string) - The fiat currency to be converted to. (Applicable only for seamless)

exchange_price(float) - The reference exchange price. (Applicable only for seamless)

fiat_amount(float) - The reference fiat amount. (Applicable only for seamless)

deposited_amount(float) – An accumulation of deposit amount.

time_created(datetime) - The UTC time that this request was created.

status(string) -

Besides that, "page_info":{"pages":(int)} indicates total pages of this query.

* Note: To get transactions of deposit record, please refer to Get unique ID details section at the bottom

Withdraw Crypto Currency

Note: You are only allow to withdraw cryptocurrency.

GET https://api.cryptopay.io/v1/sendwithdrawal

Parameters:

crypto_type (string) – (Mandatory) cryptocurrency code retrieved from the getcurrencyrate method above.

withdraw_address(string) - (Mandatory) The destination of the withdrawal.

withdraw_amount (string) - (Mandatory) The amount of crypto_type before fees deduction.

unique_id(string) - (Mandatory) The self generated unique id for this request. Valid format could be combination of digit (0-9), hyphen (-) and alphabet (a-z, case insensitive). E.g. 123, 1-232, 9999-0-1, aaa, aaa-bbb-123

charge_type(string) - (Optional).

Example Response:

{"status_code":"100","message":"Success.", "withdrawal_details":{"unique_id":"1583093795","crypto_type":"BTC","charge_type":"inclusive", "withdraw_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","withdraw_amount":"0.00300000","withdraw_fee":"0.0009","net_amount":"0.00210000","time_created":"2020-03-01 20:16:36"}}

unique_id(string) - The unique id that you have passed in the request.

crypto_type(string) - The crypto currency to deposit

charge_type(string) - Charge type, either addon or inclusive

withdraw_address(string) – Receipient address.

withdraw_amount(float) – Total requested withdrawal amount.

withdraw_fee(float) - The fee of the withdrawal.

net_amount(float) - The net amount of the withdrawal after deduction of fees.

time_created(datetime) - The UTC time that this request was created.

List Crypto Currency Withdrawal

GET https://api.cryptopay.io/v1/getwithdrawallists

Parameters:

crypto_type (string) - (Mandatory) The crypto currency.

page (int) – (Mandatory) This should start with 1 or any number of page.

Example Response:

{"status_code":"100","message":"Success.","withdrawallists":[{"unique_id":"1583093795","crypto_type":"BTC","charge_type":"inclusive","withdraw_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","withdraw_amount":"0.00300000","withdraw_fee":"0.0009","net_amount":"0.00210000","time_created":"2020-03-01 20:16:36","txid":"5197c8fdcbf4b74bbfa3a563079aff4b863ce78b5ae541a3636039b0eef0ee7c", "status":"paid"},{"unique_id":"1583093795","crypto_type":"BTC","charge_type":"addon","withdraw_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","withdraw_amount":"0.00300000","withdraw_fee":"0.0009","net_amount":"0.00300000","time_created":"2020-03-01 20:16:36", "txid":"","status":"to_be_approved"}], "page_info":{"pages":94}}

Each withdrawal item consists of

unique_id(string) - The unique id that you have passed in the request.

crypto_type(string) - The crypto currency to deposit.

charge_type(string) - Charge type, either addon or inclusive

withdraw_address(string) – Receipient address.

withdraw_amount(float) – Total requested withdrawal amount.

withdraw_fee(float) - The fee of the withdrawal.

net_amount(float) - The net amount of the withdrawal after deduction of fees.

time_created(datetime) - The UTC time that this request was created.

txid(string) - Blockchain transaction id for completed withdrawal only.

status(string) -

Besides that, "page_info":{"pages":(int)} indicates total pages of this query.

* Note: To get individual withdrawal, please refer to Get unique ID details section at the bottom

Exchange (Swap)

Note: You can only exchange currencies between Cryptocurrency and Fiat Currency

GET https://api.cryptopay.io/v1/exchange

Parameters:

exchange_from (string) – (Mandatory) cryptocurrency code retrieved from the getcurrencyrate method above.

exchange_to (string) - (Mandatory) cryptocurrency code retrieved from the getcurrencyrate method above.

exchange_amount (string) - (Mandatory) The amount of currency in exchange_from for exchange from.

unique_id(string) - (Mandatory) The self generated unique id for this request. Valid format could be combination of digit (0-9), hyphen (-) and alphabet (a-z, case insensitive). E.g. 123, 1-232, 9999-0-1, aaa, aaa-bbb-123

Example Response:

{"status_code":"100","message":"Success.", "exchange_details":{"unique_id":"1583093795","exchange_from":"BTC","exchange_to":"USD","from_amount"=>"1.23456789","net_from_amount"=>"1.22222221", "to_amount"=>"12222.22", "net_to_amount"=>"12222.22", "price"=>"10000", "crypto_exchange_fee"=>"0.01234567", "time_created":"2020-03-01 20:16:36"}}

unique_id(string) - The unique id that you have passed in the request.

exchange_from(string) - The crypto currency for exchange from.

exchange_to(string) – The crypto currency for exchange to.

from_amount(float) – The amount of currency in exchange_from.

net_from_amount(float) – if exchange_from is cryptocurrency, then this amount is amount less exchange fees.

to_amount(float) – The converted amount of currency in exchange_to.

net_to_amount(float) – if exchange_to is cryptocurrency, then this amount is amount less exchange fees.

price(float) – Conversion rate.

crypto_exchange_fee(float) - The exchange fee deduct from crypto amount.

time_created(datetime) - The UTC time that this request was created.

List Exchange

GET https://api.cryptopay.io/v1/getexchangelists

Parameters:

page (int) – (Mandatory) This should start with 1 or any number of page.

Example Response:

{"status_code":"100","message":"Success.","exchangelists":[{"unique_id":"1583093795","exchange_from":"BTC","exchange_to":"USD","from_amount"=>"1.23456789","net_from_amount"=>"1.22222221", "to_amount"=>"12222.22", "net_to_amount"=>"12222.22", "price"=>"10000", "crypto_exchange_fee"=>"0.01234567", "time_created":"2020-03-01 20:16:36", "status":"pending"},{"unique_id":"1583093795","exchange_from":"USDT","exchange_to":"MYR","from_amount"=>"1.234567","net_from_amount"=>"1.222221", "to_amount"=>"4.938268", "net_to_amount"=>"4.888884", "price"=>"4", "crypto_exchange_fee"=>"0.012345", "time_created":"2020-03-01 20:16:36","status":"success"}], "page_info":{"pages":94}}

Each exchange item consists of

unique_id(string) - The unique id that you have passed in the request.

exchange_from(string) - The crypto currency for exchange from.

exchange_to(string) – The crypto currency for exchange to.

from_amount(float) – The amount of currency in exchange_from.

net_from_amount(float) – if exchange_from is cryptocurrency, then this amount is amount less exchange fees.

to_amount(float) – The converted amount of currency in exchange_to.

net_to_amount(float) – if exchange_to is cryptocurrency, then this amount is amount less exchange fees.

price(float) – Conversion rate.

crypto_exchange_fee(float) - The exchange fee deduct from crypto amount.

time_created(datetime) - The UTC time that this request was created.

status(string) -

Besides that, "page_info":{"pages":(int)} indicates total pages of this query.

* Note: To get individual exchange, please refer to Get unique ID details section at the bottom

Get unique ID details

GET https://api.cryptopay.io/v1/getuniqueid

Parameters:

unique_id (string) - (Mandatory) The unique ID of the request of the actions you performed earlier.

txid (string) - (Optional) Only applicable to deposit transaction type. If txid found, then tx array will contain only 1 tx item or tx array will become empty.

Example Response (Deposit transaction type):

{"status_code":"100","message":"Success.","unique_id_info":{"unique_id":"1583093795","crypto_type":"BTC","deposit_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","crypto_amount":"0.00003231","deposit_type":"seamless","exchange_to":"USD","exchange_price":9283.86,"fiat_amount":"0.3","deposited_amount":"0.00003000", "time_created":"2020-03-01 20:16:36","status":"insufficient", "transactions":[{"txid":"9522cf8b0fb33355229f9ccb55ef4ff70df7759737661cdef00570a711fa6a8c", "deposit_fee":"0.0000035", "net_crypto_amount":"0.0006965","exchange_price":9222.22, "net_fiat_amount":"6.42327623"}]}}

unique_id_info details please refer to response param in List All Deposit Addresses API.

Example Response (Withdrawal transaction type):

{"status_code":"100","message":"Success.","unique_id_info":{"unique_id":"1583093795","crypto_type":"BTC","charge_type":"inclusive","withdraw_address":"1N63HXNPg3sMBaKFdWfKntJsDgxkopTKeNm","withdraw_amount":"0.00300000","withdraw_fee":"0.0009","net_amount":"0.00210000","time_created":"2020-03-01 20:16:36","txid":"5197c8fdcbf4b74bbfa3a563079aff4b863ce78b5ae541a3636039b0eef0ee7c", "status":"paid"}}

unique_id_info details please refer to response param in List Crypto Currency Withdrawal API.

Example Response (Exchange transaction type):

{"status_code":"100","message":"Success.","unique_id_info":{"unique_id":"1583093795","exchange_from":"BTC","exchange_to":"USD","from_amount"=>"1.23456789","net_from_amount"=>"1.22222221", "to_amount"=>"12222.22", "net_to_amount"=>"12222.22", "price"=>"10000", "crypto_exchange_fee"=>"0.01234567", "time_created":"2020-03-01 20:16:36", "status":"pending"}}

unique_id_info details please refer to response param in List Exchange API.

Callback

To enable callback service, you must ensure that you fill in workable callback URL in website edit page.

Cryptopay just notify you unique id and notification type. Therefore you are still need to hit get unique ID api to requery for the details.

Cryptopay will resend and retry for max. 3 times if that is down encounter in callback URL. So it is normal if your side receive more than 1 time of same notification.

Such down include your http (port 80) and https(port 443) not reachable or Cryptopay not send notification data in full length.

GET https://www.yourcallbackurl.com/yourcallback.php?unique_id=[AFFECTED UNIQUE ID]&type=[NOTIFICATION TYPE]&nonce=[CURRENT TIMESTAMP]&signature=[HMAC-SHA256 SIGNATURE]&...[EXTRA PARAMS]...

#Cryptopay will append 4 constant params (unique_id, type, nonce & signature) onto your provided callback URL 
#Cryptopay may append extra params depend on notification type

Sample to verify correctness of signature at your end.

#signature only involve these 3 params
$commands['unique_id'] = $_GET['unique_id'];
$commands['type'] = $_GET['type'];
$commands['nonce'] = $_GET['nonce'];
	
// create the signature
$signature = hash_hmac('sha256', json_encode($commands), $api_secret);

if ($signature == $_GET['signature']) {
	//signature is valid
	$tolerance_sec = 30;
	if ($_GET['nonce'] >= time() - $tolerance_sec AND $_GET['nonce'] <= time() + $tolerance_sec ) {	
		//time is valid
	}
}