The QuadrigaCX Merchant Platform offers a hassle free to way for your business to accept bitcoin, while offering the option to instantly convert all funds to CAD or USD, effectively eliminating any currency fluctuation risks.
The following guide will teach you how to integrate the QuadrigaCX Merchant Platform into your website.
From within your QuadrigaCX account, visit the "Merchant Setup" page by clicking on your name in the top right corner. This can also be accessed by clicking here.
To create your store, click "Add New Store." On the following page, complete the form with the relevant information from your shopping cart interface.
|Name||The name that users will pay into, eg Acme Widgets Ltd|
|Secret||A long random string to sign the callbacks|
|Payout Currency||Desired payout currency (BTC, USD or CAD)|
|Callback URL||The URL on your server that will receive notification of payment|
|Callback Method||The method used for the callback (GET or POST)|
|Cancel URL||The URL where users will be sent in the event that the payment is not completed|
|Return URL||The URL where users will be sent after the payment is complete|
|Email Notification||An email containing details of the transaction will be sent to this email address if set|
The following is an example of the simplest QuadrigaCX Payment form:
<form method="post" action="https://www.quadrigacx.com/merchant"> <input type="hidden" name="key" value="cKFeYaLAXMfkKZhbQ" /> <input type="hidden" name="amount" value="10" /> <input type="submit" name="go" value="Go!" > </form>
|Key||The unique key given for your store (chosen during the store setup)|
|Amount||The amount that you wish to receive in the payment currency. The merchant system will automatically convert this amount to bitcoin for the client.|
|Currency||The currency you want to ask users to pay. If omitted, the default currency will be the payout currency *|
|Identifier||Identifier used to identify the payment in the callback URL|
|Description||Additional instructions for the client|
|Custom||It is possible to send custom fields to the Merchant so that they are sent back in the callback. The custom field should enumerate the additional fields you want to pass before defining them on their own. For example, if you want to send a special identifier and a transfer number to the callback, you would define a custom field which will contain "myid,transfer". Then you declare 2 additional inputs called "myid" and "transfer" with the values you need. See example below for clarification (the custom fields will only accept 100 characters non-HTML string)|
<input type="hidden" name="currency" value="usd" /> <input type="hidden" name="custom" value="myid,transfer" /> <input type="hidden" name="myid" value="somevalue" /> <input type="hidden" name="transfer" value="123456789" />
* Please note: The Payout Currency and Currency can be the same or a combination of Crypto Currency and Fiat. For example, setting Payout Currency to CAD and Currency in the form to USD is not allowed.
Your server will be notified if you have set up the callback url in the store creation.
|Reference||Unique payment reference|
|Status||The status of the Transaction (see below)|
|Signature||Hash to confirm the payment (see below)|
|Identifier||The identifier field will be sent if it has been set|
|Custom Fields||Any custom fields that you may have specified|
The signature is a HMAC SHA256 encryption of the following data:
Form Currency + Gross amount (inc decimals) + Reference + Store Key + Merchant client ID
usd + 10.00 + abcdef + JesaoqPSmWM + 3
Then HMAC SHA256 this with the MD5 of the secret key (therefore you never store the secret in plain text)
If the signature is valid, you are able to ensure that the payment is legitimate and was completed as predicted.
It is important to note that the first notification sent to the callback will be when the transaction has been seen on the chain; the status will be unconfirmed. However, another message will be sent when at least 1 confirmation of payment has been received - then and only then will the funds be released into your account; the status will therefore be confirmed.
You must echo the 3 letters "ack" to inform our server that you have received the message and have processed the payment. Our server will continue sending the data every 30 seconds 10 times. After that, the payment will be marked as failed and your server will not be notified.