Cointruce Payment Integration Guide

Sample Code (HTML + PHP)

Existing Shopping Cart Integrations

Simple HTML ‘Pay Now’ Button

API Reference

Getting Your Merchant API Credentails

Before you can start accepting payments with Cointruce Payment API, you need to enable the merchant feature on your account. To this, simply login to your account at https://cointruce.com/accounts and navigate to My Account -> My Merchant Dashboard then click the Create My Merchant Probile button to activate

Once activated, you will be able to complete your merchant account settings and have access to your API credentails.

Transaction Fee

Cointruce will charge a 0.0001btc standard bitcoin transaction fee plus a 1 merchant fee on each merchant transaction. No matter how much the transaction is, Cointruce will never charge you more than 0.00200000 BTC per transaction

The transaction fee is only charged when payment is received.

How It Works

Payment Flow

When your customer choose to pay with Cointruce, the customer is redirected to our secure payment page. At the payment page, the customer will be given a bitcoin address and exact amount to pay in BTC

Your customer is then required to transfer the total amount in a single transaction to the bitcoin address within 6 hours

Transaction will automatically expire if payment is not received within 6 hours, in which case the customer will be required to initiate a fresh transaction from your website.

Although the payment process will not be interrupted if a customer navigates away from or closes the payment page, we strongly recommend the page remains open, especially if Instant Payment notification is not enabled for the payment.

Upon receipt of full payment, the payment page will automatically display a successful payment notice to the customer and return to your website (if a return URL is set).

At thesame time of payment completion, Cointruce will post the transaction details and status update to your payment notification URL (if set).

Integration

All that is required for a once-off payment is an html form with the necessary variables (described in the checkout page) sent to Cointruce Paymemnt Link "https://cointruce.com/pay/". Cointruce will then process the transaction, update the merchants account, and send a payment notification to the notify URL. The return variables of the payment confirmation can then be used to verify and update your system accordingly.

There are two methods available for integrating with Cointruce, Instant Notify, which is our preferred integration method and Query Pay. The main difference, besides better security in Instant Notify, is that with Instant Notify our server contacts your website and notifies you of the payment, whereas with Query Pay you are required to contact and confirm with us.

The following is a list of pages that are generally needed on your website or application:

NAME DESCRIPTION
Checkout page Buyer clicks a button to confirm their order and is redirected to Cointruce for payment
Return page Page on your site which the buyer is returned to after payment
Notify page Callback page which does all the ‘heavy lifting’ with regards to updating your database with payment information etc

 

Checkout Page

This page will have an HTML form, usually hidden, with a number of fields containing all the necessary information needed for Cointruce to process the payment. Most shopping cart systems will have the buyer click on a ‘Confirm Order’ or ‘Pay Now’ button to submit the form and be redirected to the Cointruce Payment page.

Return Page ‘p_return_url’

This page on your site is where the buyer is redirected to, from Cointruce, after a successful or canceled payment. A plain HTML page thanking the buyer for their purchase (and maybe mentioning the delivery procedure) is usually the norm. The page is specified by the p_return_url variable in the HTML form on the Checkout Page.
Our system also post some important information regarding the trasaction while returing the customer. If you are using the Query Pay method to update your custom integration this page would handle any required functionality.

Notify Page ‘p_callback_url’

This page would do all the ‘work’ which is required (e.g. updating the order in your database), when using our Instant Pay method. This page is ‘called’ by our server directly after a successful payment and before the user is redirected to the Return Page. If there are any communication problems, or errors, our server will try again (up to 2 more times

Initiating Payment

To initiate payment, simply make a POST request to Cointruce payment URL (https://cointruce.com/pay/) with the following parameters;

Parameter Description Required
p_action This must be set to pay (Case-sensitive) Yes
p_merchant_key This is your Cointruce merchant API key. You can get this from your merchant settings Yes
p_tranx_reference This is a Unique transaction ID for this payment Yes
p_amount This is the amount to pay in BTC (e.g. 0.00123000) Yes
p_callback_url This is the link where payment notification for this transaction will be sent. If not set, the system will use the one you set at your merchant settings No
p_return_url This is the link payer will be returned to after payment. If not set, payment confirmation will be displayed on the payment page No
p_customer_pay_charge Set this to 1 if you want your customer to pay all transaction charges (default is 0) No
p_customer_id Use this to pass your unique customer identifier for this payer No
p_custom_param Use this to pass any other parameter you want. Cointruce will return thesame with payment notification No

 

Instant Payment Notification

Upon successful payment, Cointruce will automatically make a POST to your Notify URL as well as your Return URL with the following parameters;

Parameter Description
status This is the status of the transaction. Value can be completed, partial or expired
message This is a further explanation of the transaction status
amount_billed This the total amount in BTC you passed in the payment form
amount_received This is the total amount in BTC received
tranx_reference This is the same unique transaction ID you passed in the payment form
customer_id This will be the same as the value you passed with the p_customer_id parameter on the payment form
custom_param This will be the same as the value you passed with the p_custom_param parameter on the payment form

We Strongly Recommend you verify each payment before giving value to your customer. See details on next section

 

Verifying Payment Status

It is very important that you verify each payment notification data received on your notification script before you give value to your customer. This is because any one who knows your Notification URL can submit fake payment notifications to it

To validate a payment, simply send a HTTP GET or POST request to https://cointruce.com/pay with the following parameters

Parameter Description
p_action This must be set to query (Case-sensitive) Yes
p_merchant_key This is your Cointruce merchant API key. You can get this from your merchant settings Yes
p_merchant_token This is your Cointruce merchant API Token. You can get this from your merchant settings Yes
p_tranx_reference This is a Unique transaction ID for this payment to verify Yes

 

Cointruce will a JSON encoded response depending on sucess or failure of the request.

Sample Success Response

{"status":"completed","message":"transaction completed","amount_billed":"0.02100000","amount_received":"0.021000","tranx_reference":"6835735","custom_param":"0","customer_id":"James Ghta"}

Parameter Description
status This is the status of the transaction. Value can be completed, partial or expired
message This is a further explanation of the transaction status
amount_billed This the total amount in BTC you passed in the payment form
amount_received This is the total amount in BTC received
tranx_reference This is the same unique transaction ID you passed in the payment form
customer_id This will be the same as the value you passed with the p_customer_id parameter on the payment form
custom_param This will be the same as the value you passed with the p_custom_param parameter on the payment form

Sample Failure Response

{"status":"error","message":"Invalid merchant account credentails"}

Parameter Description
status This is the status of the request. Value is usually error
message This is a further explanation of the error encountered

Subscribe to Cointruce.com newsletters and stay updated with the latest trends on crypto-currency world!