Get Started
To use the API you must generate an API Key in your API Access area.
API key must be included in the Step 1 POSTed fields:
bxid
- API Key as bxid
API Key
The API Key in found in the "API Key" column when you generate your API keys.
Step 1: Request forwarding addresses
Step 1 is for requesting all addresses
In this step, you request the payment addresses and amount to pay the order.
Send your bx id, amount and currency of you shopping cart, you will receive list of addresses with amount in it currency.
URL: https://api.coinpay.co.th/get_forwarding_address
POSTed fields:
All requests must be in JSON format
Field | Description | Possible Values | |
---|---|---|---|
Required | bxid |
your BX id key | string Example: XXXXXXXXXXXXX |
Required | callback |
your callback URL | string |
Required | amount |
total amount of your cart | string Example: 450.00 |
Required | currency_from |
your shopping cart default currency | string Example: THB |
optional | currency_to |
currncy to be converted. comma separeted list | string Example: BTC, BCH, LTC |
Required | order_label |
your shopping cart payment order name | string |
curl -X POST https://api.coinpay.co.th/get_forwarding_address \
-H "Content-Type:application/json" \
-d '{ \
"bxid": "XXXXXXXXXXXX", \
"callback": "http://yourshopname.com/callback", \
"amount": "10.99", \
"currency_from": "USD", \
"currency_to": "BTC,BCH,LTC", \
"order_label": "Payment on ZooManiya" \
}'
Returned JSON values:
Field | Description | Possible Values |
---|---|---|
success |
Price conversion was successful | true / false |
data |
Array of addresses | array |
error |
Error message if success is false | string |
"success" => true|false,
"data" => [
"addresses" => [
"BTC" => [
"available" => true|false,
"error" => ""|"This payment method is not available",
"address" => "391BHlfkASdfkioweASDfaskkSse98alfjls",
"amount" => "0.00001550",
"exchange_rate" => "0.000001",
"payment_url" => "bitcoin://....",
"qr_code_base64" => "code here",
"name" => "Bitcoin"
],
"BCH" => [
//...
]
]
]
Check transaction is created
This request can be used to check whather transaction was created or not; to check that, simply send all received addresses back to the API and you will get response
You will get success = true if one of the addresses has been used to pay the order otherwise false.
URL: https://api.coinpay.co.th/payment_received
POSTed fields:
Field | Description | Possible Values | |
---|---|---|---|
Required | addresses |
Array of payment addresses received on step 1 |
curl -X POST https://api.coinpay.co.th/payement_received \
-H "Content-Type:application/json" \
-d '{ \
"addresses" => [
"391BHJWqZifRLPRAa4NkpgTq3b4Hn9j1Vb",
"191BHJWqZifRLPRAa4NkpgTq3b4Hn9j1Vb"
]
}'
Returned JSON values:
Field | Description | Possible Values |
---|---|---|
success |
Response from the API server | true / false |
data |
Payment information data if success is true | array |
error |
If success is false; this is the reason | string |
"success" => true|false, // boolean
"data" => [
"paid" => [ // this array exists in response if it was partial payment only
[
"amount" => "0.001", // string
"cryptocurrency" => "BCH", // string
"proof_link" => "http://explorer.com/tx/..." // string
"address" => "1467587646547545465879788" // string
],
[
"amount" => "0.002", // string
"cryptocurrency" => "BTC", // string
"proof_link" => "http://explorer.com/tx/..." // string
"address" => "3467587646547545465879788" // string
]
],
"paid_by" => [ // this array exists in response if it was paid in full only
"name" => "Bitcoin Cash", // string
"ticker" => "BCH", // string
"amount" => "0.001", // string
"proof_link" => "http://explorer.com/tx/..." // string
"address" => "3467587646547545465879788" // string
],
"is_enough" => true|false, // boolean (true if paid in full)
"payment_received" => true|false, // boolean (was ANY payment received)
"signature" => "78465872651987362" // string (Signature to verify response)
],
"error" => ""|"Error message" // string
Save order id
After you get successfull response from API with payment details you can create order and send order id back to API server
URL: https://api.coinpay.co.th/save_order_id
POSTed fields:
Field | Description | Possible Values | |
---|---|---|---|
Required | addresses |
Array of addresses received in step 1 | array |
Required | order_id |
Your shopping cart order id number | string |
curl -X POST https://api.coinpay.co.th/save_order_id \
-H "Content-Type:application/json" \
-d '{ \
"addresses" => [
"391BHJWqZifRLPRAa4NkpgTq3b4Hn9j1Vb",
"191BHJWqZifRLPRAa4NkpgTq3b4Hn9j1Vb"
],
"order_id" => "123"
}'
Returned JSON values:
Field | Description | Possible Values |
---|---|---|
success |
Response from the API server | true / false |
error |
Error message if success is false | string |
IPN callbacks
In step 1 you should add callback URL so API server will know where to send call to you shopping cart with success payment
The callback will be sent as soon as payment transaction will be confirmed in blockchain
POSTed fields (POST to your shopping cart URL address which you provide in step 1):
Field | Description | Possible Values |
---|---|---|
order_id |
Order ID which payment was successfull confirmed | string |
message |
Message of payment status | string |
confirmed_in_full |
True if successfull | true / false |
signature |
Signature to verify IPN call | string |
Returned JSON values:
Field | Description | Possible Values |
---|---|---|
ok |
Return anything with status code 200 | string |
IPN Verification
After you get IPN call from API server you must verify it's data by using example in Signature section
Signature
Signature Generation and Verification
To check signature, you need add your API Key to the data received from API server, after that sort data in ascending order (acording to the key), returned data from API server (make sure you use function to manipulate multi-dimensional arrays.
After you sort retured data, smply convert it into json string. Last but not least step is get the SHA-1 hash of converted in json format string. The result of this will be your signature.
Simply compare your signature with one comes from the API server.
A PHP example:
class Signature
{
protected $secret;
public function __construct($secret)
{
$this->secter = $secret;
}
/**
* Generate signature
* @param array $data
* @return string
*/
public function generate($data)
{
$data['secret'] = $this->secret; // your API Key
// Sort to have always the same order in signature.
$data = array_walk_recursive($data, function($item) {
if (is_array($item)) {
return ksort($item);
}
return $item;
});
$signable_string = json_encode($data); // Convert into json
return sha1($signable_string); // Get SHA-1 hash
}
public function check($data)
{
if (!isset($data['signature'])) {
return false;
}
$signature = $data['signature'];
$correctSignature = $this->generate($this->clean($data));
return $signature === $correctSignature;
}
protected function clean($data)
{
unset($data['signature']);
return $data;
}
}