We use cookies to ensure that we give you the best experience on our website. If you continue, we’ll assume that you are happy to receive all cookies on the TheCoinPay.com website. We only use them to track you anonymously across our site. So we can give you the most relevant content and the best user experience we can  Accept

Payment Gateway API V0.1

https://www.thecoinpay.com

 

Introduction

The Bitcoin Payment Gateway API is designed for merchants that need full control over their customers’ checkout experience. An eCommerce site can make use of this API to transmit invoice information to TheCoinPay.com from their back­end server, and receive server notifications when the customer has completed payment and the invoice total has been credited to the merchant account.

 

The following interactions with the TheCoinPay.com service available via this API:

  1. Create an invoice
  2. Receive invoice status updates
  3. Fetch an invoice status

 

Invoice States

A TheCoinPay.com invoice can be in one of the following states:

  1. “new”
  2. “confirmed”
  3. “completed”
  4. “smaller_amount”
  5. “expired”

Payments sent to the bitcoin address associated with an invoice will only be credited to the invoice when it is in the “new” state.

 

 

“new”

 

 

Each created invoice by TheCoinPay.com starts in this state.

 

 

“confirmed”

An invoice has been “confirmed” as soon as the payment appears on the Bitcoin network

 

 

“completed”

When an invoice is “completed”, it means that TheCoinPay.com has credited your account for the invoice. Currently, 10 confirmation blocks on the bitcoin network are required for an invoice to become completed.

 

“expired”

An unpaid invoice becomes “expired” after one day from creation time.

 

“smaller_amount”

When an invoice’s status is smaller amount, it means that the received amount is smaller than the expected payment amount.

 

Create an Invoice

An invoice is created by sending an http POST message to http://TheCoinPay.com/invoice/create with the details of the invoice passed in the body of the request.The body of the message must be JSON encoded.On successful creation, the invoice details will be provided in a JSON encoded response. If there is an error, you will receive a JSON encoded error text response.A user is restricted to create no more than 500 invoices per hour (there are also per second and per minute limits).

 

The fields in the request are described below:

 

Field

Description

Required

“merchant_id”

Your merchant ID, you can find it on the following address: https://www.thecoinpay.com/user/profile/myaccount

YES

“merchant_password”

Your merchant password, you can find it on the following address: https://www.thecoinpay.com/user/profile/myaccount

YES

 

“amount”

Final amount of the invoice.

 

YES

“return_url”

This is the URL for a return link that is displayed on the receipt, to return the shopper back to your website after a successful purchase. This could be a page specific to the order, or to their account.

NO

“notification_url”

(IPN – instant payment notification)

A URL to send status update messages to your server. (IPN)

TheCoinPay.com will send a POST request with a JSON encoding of the invoice to this URL when the invoice status changes.

NO

“notification_email”

System will send an email to this email address when the invoice status changes.

NO

“comment”

You can attach a comment to the invoice

NO

“currency”

The 3 letter currency code in which the invoice will be paid.

(accepted currencies https://www.thecoinpay.com/api/acceptedCurrencies)

YES

“showSubmit”

Display payment button (available values: 1 or 0)

YES

"paymentLink"       Return payment link(available values: 1 or 0)   NO

 

 

TheCoinPay.com server’s response

The response to a create invoice request, the response to a get invoice request, and the content of a status update notification are all identical JSON representations of the invoice object. The fields are described below:

 

“txn_id”

The unique id of created invoice (You have to save it into your database)

“confirmed”

Confirmation time, when was the invoice confirmed on the Bitcoin network.

“completed”

Timestamp when the invoice had 10 confirmation blocks on the Bitcoin network.

 

 

“commission”

Commission amount

“btcAmount”

Invoice’s amount

“status”

Invoice current status

“received_amount”

Incoming amount 0 or >0

“notification_email”

Added notification email when the invoice was created

“return_url”

Added return Url when the invoice was created

”notification_url” ( IPN  )

Added notification url

“comment”

Attached comment to invoice

 

Example for successfully JSON response

{

   "txn_id":"0227ec06747b8e5",

   "confirmed":"2014-04-10 13:55:37",

   "completed":"2014-04-10 14:45:26",

   "btcAmount":"0.785",

   "commision":"0.0010",

   "status":"completed",

   "recived_amount":"1",

   "return_url":"http:\/\/yourdomain\/controller\/action",

   "notification_url":"http:\/\/yourdomain\/controller\/action",

   "comment":"some comment",

   "notification_email":"notifyme@notify.me"

}

Get Invoice Status

To get the current state of an invoice, you have to send an http or https GET request like this one: https://thecoinpay/getinvoice/invoice?merchantid=poiAW12Lokdsap&merchantpassword=puy089902W12Lokdsap&id=254


The format of the response is exactly the same as of the created invoice.

Example for successfully JSON response

{

   "txn_id":"0227ec06747b8e5",

   "confirmed":"2014-04-10 13:55:37",

   "completed":"2014-04-10 14:45:26",

   "address":"1146nGkDPaG4gM6QwXc4MszCmw8xfynHR6",

   "btcAmount":"0.785",

   "commision":"0.0010",

   "status":"completed",

   "recived_amount":"1",

   "return_url":"http:\/\/yourdomain\/controller\/action",

   "notification_url":"http:\/\/yourdomain\/controller\/action",

   "comment":"some comment",

   "notification_email":"notifyme@notify.me"

}

Downloads & Code samples

You can download API and examples for usage here:

  1. https://www.thecoinpay.com/site/apiDownload?fullexample=1
  2. https://www.thecoinpay.com/site/apiDownload?lib=1

 

Create Invoice

  1. You have to copy the TheCoinPayApi.php files onto your libraries, components or root folder.
  2. Set up necessary data for TheCoinPayApi(merchant id, merchant password, return url, notification url, etc.)
  3. Include TheCoinPayApi into your controller
  4. Create an instance of TheCoinPayApi in you controller
<?php 
    define('__ROOT__', dirname(dirname(__FILE__)));
    require_once(__ROOT__.'/foldername/TheCoinPayApi.php');
    $invoice  =new TheCoinPayApi();
    $optionalParams = array(param1=>value1,param2=>param2,paramN =>paramN+1);
    $invoice->Setup($amount,$optionalParams = array());
    $createdInvoice = json_encode($invoice->createInvoice());
    
    If(!is_array($createdInvoice) || empty($createdInvoice))
    {
        echo $createdInvoice;
        //Some error
    }
    else
    {
        //$createdInvoice invoice was successfully created
    }

 

 

 

Get Invoice status

All you have to do is to create a curl call to the following url with the required GET parameters. In most cases this should be a Cron job.

$urlToCall = “http://www.thecoinpay.com?invoiceId=’requestedinvoiceid’&merchantId=’merchantid’& merchantPassword=’your merchantpassword’”

$ch = curl_init($urlToCall);
$result = json_decode(curl_exec($ch));

Or

$result = file_get_contents($urlToCall);
//Check the result
if(!is_array($result)){
   //some error
}else{
    //Process the result/ update status in DB etc.
}

 

Example for successfully JSON response

{

   "txn_id":"0227ec06747b8e5",

   "confirmed":"2014-04-10 13:55:37",

   "completed":"2014-04-10 14:45:26",

   "address":"1146nGkDPaG4gM6QwXc4MszCmw8xfynHR6",

   "btcAmount":"0.785",

   "commision":"0.0010",

   "status":"completed",

   "recived_amount":"1",

   "return_url":"http:\/\/yourdomain\/controller\/action",

   "notification_url":"http:\/\/yourdomain\/controller\/action",

   "comment":"some comment",

   "notification_email":"notifyme@notify.me"

}