API Documentation

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 crated

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;
    }
  }