API Documentation

How to use the API

To use the API you must generate an API Key in your API Access area. Each API key generated will have an "API Key" and an "API Secret".

Every query to the API must include the following POSTed fields:

  • key - API Key
  • nonce - Nonce
  • signature - Signature
API Key

The API Key in found in the "API Key" column when you generate your API keys.

Nonce

This is a (big)integer value that must increase with every API call you make, for example if your first API call uses nonce=1 then the next API call must use a nonce of 2 or greater

A common practice is to use unix time (or micro time) for that parameter.

Signature

A SHA-256 hash of the following data api_key + nonce + api_secret

A PHP example:

$signature = hash('sha256',$api_key.$nonce.$api_secret);


Bitcoin Price

This function allows you to convert any supported currency into CoinPay Bitcoin price.

URL: https://coinpay.in.th/api/price/

POSTed fields (in addition to the standard key, nonce, signature fields):

If POST fields are left empty the standard BTC to THB rate will be displayed.

Field Description Possible Values
Optional currency 3 character currency code string Example: USD
Optional amount Amount to be converted float
Returned JSON values:
Field Description Possible Values
success Price conversion was successful true / false
value Converted price value int
currency Currency of converted value (ie "BTC") string
error If success is false; this is the reason string

Get Bitcoin Address

This function can be used to get a Bitcoin address; any bitcoins sent to the address will be converted to THB at the CoinPay Bitcoin price.

If you have your account setup to automatically keep some percentage of Bitcoins, this setting will be used for any bitcoins received.

URL: https://coinpay.in.th/api/address/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Optional new If you want to force generation of a new address (default false) true / false
Returned JSON values:
Field Description Possible Values
success Address successfully returned true / false
address Bitcoin address string
error If success is false; this is the reason string

Create an Order

By creating an order you can lock in a Bitcoin rate for 15 minutes.

URL: https://coinpay.in.th/api/create/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required amount Amount in local currency of order float
Required currency 3 character currency code (ie "THB", "USD", "GBP") string
Optional order_id If order has already been created, and call is to update int
Optional reference_id A reference ID to link the order back to an order within your own system string
Optional ipn Full URL for IPN callbacks to be sent to string
Optional notes Any notes/text that you want added to the order string
Optional keep If you want to keep some percent as Bitcoins.
Enter integer from 0-100
"0" meaning convert all to THB, "100" meaning keep 100% as BTC
Defaults to "Keep Bitcoins" account setting if field omitted
int
Returned JSON values:
Field Description Possible Values
success Address successfully returned true / false
address Bitcoin address string
btc_amount Amount of Bitcoin to be paid float
expire Minutes until order expires (ie "15" minutes) float
order_id CoinPay order ID int
order_hash Text hash representation of order ID string
qr_data Base64 encoded PNG QR code data string
html Simple HTML of address and amount to pay string
error If success is false; this is the reason string
Deprecatederrors If success is false; this is the reason array

Update an Order

Once an order has been created the returned order ID should be retained and updated for any changes to the order prior to payment. Such as if the customer adds additional products to their order, or changes shipping preference.

Updating an order means the same bitcoin address will be kept; this will avoid confusion that can surround created a new order with a different bitcoin address.

To update an order simply use the "Create" function, but include the order_id parameter with the original order ID.

After payment completed

Orders can only be updated prior to payment. In the case that you want to charge the customer an additional amount later; a new order should be created.


Save Reference ID

This function can be used to save an associated Reference ID with an order; after the order has been created.

URL: https://coinpay.in.th/api/reference/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required order_id Order ID of the CoinPay order int
Required reference_id Reference ID to be associated with the order string
Returned JSON values:
Field Description Possible Values
success Reference ID successfully save true / false
error If success is false; this is the reason string

Check Order Status

Use this function to check on the status of an order.

URL: https://coinpay.in.th/api/check/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required order_id Order ID, or Order Hash of the CoinPay order int
Optional reference_id If you wish to update the reference ID associated with the order. string
Returned JSON values:
Field Description Possible Values
success Order has been successfully completed true / false
status Text description of order status string
date Date of order datetime
btc_amount Bitcoin amount of the order float
order_amount Amount of order in local currency float
currency 3 character currency code of local currency string
order_id CoinPay order ID int
order_hash Text hash representation of order ID string
confirmed Has order been paid and added to balance true / false
error_code 0 = No Error (payment received)
1 = Order not found
2 = Payment not received
3 = Insuffient payment
int
error If success is false; this is the reason string

List Orders

Use this function to get a list of orders

URL: https://coinpay.in.th/api/orders/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Optional status_id Comma separated list of order status IDs (default 0,1,2,5)
0 = Awaiting Payment
1 = Waiting Confirmations
2 = Completed
4 = Expired
5 = Partial Payment
string
Optional start_date List only orders after this date (UTC+7) datetime
Optional end_date List only orders before this date (UTC+7) datetime
Returned JSON values:
Field Description Possible Values
success List has been successfully returned true / false
error If success is false; this is the reason string
orders Will contain a nested array of the orders with below fields:
order_id CoinPay order ID int
order_hash Text hash representation of order ID string
date Date of order datetime
btc_amount Bitcoin amount of the order float
btc_received Bitcoin received for the order float
order_amount Amount of order in local currency float
currency 3 character currency code of local currency string
status Text description of order status string
order_status Contains a number order status code:
0 = Awaiting Payment
1 = Waiting Confirmations
2 = Completed
4 = Expired
5 = Partial Payment
int
transactions Array of Bitcoin transactions received on the order array

Get Account Balances

Get a list of account balances and pending withdrawal amounts.

URL: https://coinpay.in.th/api/balance/

POST only the standard authentication fields (key, nonce, signature)

Returned JSON values:
Field Description Possible Values
success Balances were successfully returned true / false
error If success is false; this is the reason string
balances Will contain a nested array of the balances for each currency:
currency Currency of converted value (ie "BTC") string
balance Balance in the specific currency float
pending_withdraw Sum of pending withdrawals for the specific currency float

Generate Payment Link

Use this function to generate payment link for customers; using the payment link will route the payee through the CoinPay hosted mobile-friendly payment website.

URL: https://coinpay.in.th/api/paylink/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required amount Amount in local currency of order float
Required currency 3 character currency code (ie "THB", "USD", "GBP") string
Optional reference_id A reference ID to link the order back to an order within your system string
Optional ipn Full URL for IPN callbacks to be sent to string
Optional redirect Payees will be redirected to this URL after completing their payment string
Returned JSON values:
Field Description Possible Values
success List has been successfully returned true / false
error If success is false; this is the reason string
link Send this URL to payee to make a payment string

Sample Code

You can find our PHP API class and demo code on Github here:

  View on Github

You can also use our shopping cart plugins as reference code


IPN Callbacks

When creating an order you can add an IPN URL, our CoinPay server will send callbacks to the IPN URL when an order is confirmed and added to your account balance.

IPN callback will contain the following POSTed data:

Field Description Possible Values
order_id CoinPay order ID int
order_hash Text hash representation of order ID string
verify String used for IPN verification string
success Order has been successfully completed true / false
status Text description of order status string
order_status Contains a number order status code:
0 = Awaiting Payment
1 = Waiting Confirmations
2 = Completed
4 = Expired
5 = Partial Payment
int
reference_id Refence ID associated with the order string
btc_amount Bitcoin amount of the order float
btc_received Bitcoins received for the order float
message Plain text description of the order status string

IPN Verification

In order to protect again fake IPN calls, sent by malicious users, you should using the following function to verify that we are really the senders of the IPN callback.

URL: https://coinpay.in.th/api/verifyipn/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required order_id CoinPay Order ID int
Required verify IPN verify hash string
Returned JSON values:
Field Description Possible Values
success IPN has been successfully verified true / false
error If success is false; this is the reason string
Deprecatederrors If success is false; this is the reason array

Account Functions

You must request special permission with CoinPay first before you will be able to access any account functions.

Create an Account

Use this function to create an account on behalf of a user. This function should only be used with users acknowlegement and agreement to CoinPay terms of service.

URL: https://coinpay.in.th/api/account/create/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required email Email address of new user string
Required password Desired password of new user string
Required name Full name of the new user string
Required nationality Nationality of new user string
Required id_number ID Card or password number of new user string
Required photo_id base64 encoded photo ID image of new user string
Required photo_format File type, possible: "png", "jpg", "gif" string
Required business_name Business or company name string
Required business_address Business address of new user's business string
Required business_type Business type of new user's business:
  • Individual
  • Sole Proprietorship Company documents required
  • Partnership Company documents required
  • Limited Company Company documents required
  • Public Company Company documents required
string
Dependent company_docs base64 encoded company registration image string
Dependent docs_format File type, possible: "png", "jpg", "gif" string
Returned JSON values:
Field Description Possible Values
success Account was successfully created true / false
account_id Account ID for newly created account string
api_key API Key for newly created account string
api_secret API Secret for newly created account string
error If success is false; this is the reason string

Get Account Details

Use this function to get a list of all accounts, or a specific account that you have created.

Note that if you users choose to turn off 3rd party access in their account; their account details will not longer be accessible.

URL: https://coinpay.in.th/api/account/details/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Optional account_id If you want to list a specific account only string
Returned JSON values:
Field Description Possible Values
success Account details were successfully returned true / false
error If success is false; this is the reason string
accounts Will contain a nested array of the accounts:
account_id Account ID for updating string
verified Account has been verified true / false
balances Will contain a nested array of the balances for each currency:
currency Currency of converted value (ie "BTC") string
balance Balance in the specific currency float
pending_withdraw Sum of pending withdrawals for the specific currency float
banks Will contain a nested array of banks on the account:
branch Bank branch string
owner Bank account owner string
account Bank account number string
active Bank account is the active withdrawal account true / false

Set Bank

Use this function to set an active withdrawal bank account.

Note that if you users choose to turn off 3rd party access in their account; you will no longer able to set bank accounts.

URL: https://coinpay.in.th/api/account/bank/

POSTed fields (in addition to the standard key, nonce, signature fields):

Field Description Possible Values
Required account_id Account ID to be updated string
Required branch Bank branch code:
- BAY
- BBK
- KBANK
- KTB
- SCB
- TMB
string
Required owner Bank account owners name string
Required account Bank account number string
Returned JSON values:
Field Description Possible Values
success Bank was successfully added true / false
error If success is false; this is the reason string