Loading...

Merchant Payment Gateway

Introduction to Bitcloudpay and our payment gateway API for Merchants

Merchant API for Cryptocurrency Payments

Bitcloudpay API is designed as an easy starting point for online businesses and merchants that wish to accept cryptocurrencies as a payment method. Bitcloudpay handles the payment flow from checkout to settlement, allowing businesses to use this payment method without deep technical know-how and risks related to exchange rate fluctuations. The API is, therefore, suitable for applications from basic projects, to enterprise-level integration. Our gateway provides full automation for accepting Bitcoin, XRP, Ethereum, Tether and others, unique addresses for each order, real-time transparent exchange rates for customers, and a platform for merchants to track and manage their payment history and payouts. Configuration of our API for processing payments on virtually any website is rather straightforward. API integration can be tested on our Sandbox environment (create separate credentials here) or straight in live mode.

1.Call Create Order API method to create an order in the Bitcloudpay system.

2.Bitcloudpay checks if the order is valid.

2a. If the order is valid, Bitcloudpay responds with 200 HTTP status and returns order data. After receiving 200 HTTP status, you should redirect the shopper to payment_url address.

2b. If the order is not valid, Bitcloudpay returns 422 (or another) error HTTP status and an error message (see Errors).

3.When the shopper pays for the order, Bitcloudpay sends Payment Callback/Payment Notification to your callback_url, which is defined when creating the order (see Create Order). Bitcloudpay also sends Payment Callback when order status is changed to canceled, expired or to any other status (see Order Statuses). Please note that payment notifications are sent using POST method.

Environments

Live https://api.bitcloudpay.com/v2
Sandbox https://api.bitcloudpay.com/v2/test
  • If you wish to use Live environment, create an account and API credentials on https://bitcloudpay.com
  • If you wish to use Sandbox environment, create an account and API credentials on https://bitcloudpay.com, but generate data for sandbox.

Limits and Quotas

Orders 500 per hour per userid (contact support to increase) This default value is the number of orders that can be created per hour. Reaching the limit will prevent further orders to be created before the hourly timer resets.
Public API endpoints 200 per minute and 10,000 per hour per IP address Applies to API methods that do not require authentication, such as Get Exchange Rate and List Exchange Rates (note that Bitcloudpay exchange rates are updated every 60 seconds, therefore it is not recommended to call the API more often than every 60 seconds to retrieve the latest exchange rates).
Private API endpoints 200 per minute and 1,000 per hour per API App (contact support to increase)

API Requests

API Requests are used to query the Bitcloudpay API (examples: Create Order, Get Order). To review your API Requests, login to your Bitcloudpay account, then go to API » Requests. API Request attributes:

  • Action - Which API method was queried.
  • Response - HTTP status returned by Bitcloudpay.
  • Parameters - Parameters used to query the Bitcloudpay API.
  • Response - Parameters returned by Bitcloudpay.

Payment Callbacks (Payment Notifications)

Payment Callback (Payment Notification) is a response which is sent after the order status changes (see Order Statuses). Bitcloudpay sends the Payment Callback to merchant's callback_url, which is set during order creation (see Create Order). To review your Payment Callbacks, login to your Bitcloudpay account, then go to API » Payment Callbacks. Payment Callback attributes:

  • Response Status - HTTP status returned by merchant.
  • Response Data - Data body returned by merchant.
  • Callback Params - Parameters sent by Bitcloudpay to merchant's callback_url.

POST Request

In every POST method set Content-Type: application/x-www-form-urlencoded header. Create auth token on: https://bitcloudpay.com/ Please note, that for "Test" (sandbox) mode you must generate separate API credentials on https://bitcloudpay.com. API credentials generated for LIVE mode will not work for "Test" (sandbox) mode. Provide generated Token to HTTP Authorization Header. cURL PHP

curl -v -H "Authorization: Token YOUR_APP_TOKEN"
"https://api.bitcloudpay.com/v2/orders/15012"

Code Libraries

Libraries and read-made tools for a quick integration

Code libraries:

  • Bitcloudpay PHP
  • Bitcloudpay (JS)

Plugins for e-commerce and billing systems:

  • Blesta
  • Magento / Magento 2
  • OpenCart 1/2/3
  • OsCommerce
  • PrestaShop
  • Wordpress WooCommerce
  • ZenCart

Errors. Bitcloudpay API error responses

Most common API error responses are described below. Error response must be identified by HTTP status and reason attribute in your application. Please note that specific API methods (for example Create Order) have their own errors (e.g. 422 Unprocessable Entity - when order is not valid). See Common Issues for troubleshooting.

HTTP Status Reason Description
401 (Unauthorized) BadCredentials API credentials are not valid
404 (Not Found) PageNotFound Page, action or record not found
404 (Not Found) RecordNotFound Record not found
500 (Internal Server Error) InternalServerError Something wrong in Bitcloudpay
429 (Too Many Requests) RateLimitException API request limit is exceeded

Response example: JSON

{
  "message": "Not found App by Access-Key",
  "reason": "BadCredentials"
}

Common Issues

Troubleshooting common API or ecommerce integration issues

Unable to create order / unable to send a request to Bitcloudpay API

Reason Solution
API credentials used in the wrong environment Create separate users and separate API credentials for Sandbox or Live (bitcloudpay.com) environments
Wrong API credentials Please check if you have entered them correctly; make sure that there are no spaces before or after the text.
Wrong API credentials signature, invalid order, etc. You can see the details of a specific API request issue by logging in to your Bitcloudpay account and going to API » Requests
API requests are coming from a different IP address(es) than the IPs that were whitelisted when creating API credentials when creating If IP whitelisting is desired, log in to your Bitcloudpay account, visit API » Apps and clicking Edit next to your API credentials; make sure the whitelisted IPs match the IPs your requests are coming from
cURL or another library used to communicate with the Bitcloudpay API is working incorrectly, or is outdated Please check your library version
Your server cannot reach bitcloudpay.com Check if bitcloudpay.com is available and if your server can reach it (also see Status Page)

You can see your API Request logs by locating API » Requests in the menu of your Bitcloudpay account.

Order status is not updated / Bitcloudpay does not send Payment Callback (Payment Notification)

Reason Solution
Your server is on a private network, for example localhost Make sure that your application is publicly accessible
Your website is disabled or in maintenance mode Make sure your website is accessible
Your server firewall, third-party security service (Cloudflare, Incapsula, etc.) or your application is blocking Bitcloudpay IP address(es) Verify that Bitcloudpay IP address(es) are allowed by your server firewall, third-party security services and your application

You can check the specific reason why Payment Callback was not sent by logging in to your Bitcloudpay account and locating API » Payment Callbacks in the menu.

Create Order

Create order at Bitcloudpay and redirect shopper to invoice (payment_url)

Definition

https://api.bitcloudpay.com/v2/orders

Body Params

order_id:string

Merchant's custom order ID. We recommend using a unique order ID. Example: CGORDER-12345.

price_amount: required double

The price set by the merchant. Example: 1050.99.

price_currency: required string

ISO 4217 currency code which defines the currency in which you wish to price your merchandise; used to define price parameter. Possible values: EUR, USD, CAD, BTC, ETH, etc.

receive_currency: required string

ISO 4217 currency code which defines the currency in which you wish to receive your settlements. Currency conversions are done by Bitcloudpay. Possible values: fiat - EUR, USD; stablecoin - USDT; crypto: BTC, LTC, ETH or DO_NOT_CONVERT. Note: use DO_NOT_CONVERT to keep payments received in original currency (Altcoin payments will be converted to BTC). With DO_NOT_CONVERT you can also extend invoice expiration time up to 24 hours.

title:string

Max 150 characters. Example: product title (Apple iPhone 6), order id (MyShop Order #12345), cart id (Cart #00004335).

description:string

More details about this order. Max 500 characters. It can be cart items, product details or other information. Example: 1 x Apple iPhone 6, 1 x Apple MacBook Air

callback_url: string

Send an automated message to Merchant URL when order status is changed. Example: http://example.com/payments/bitcloudpay-callback

cancel_url: string

Redirect to Merchant URL when buyer cancels the order. Example: http://example.com/cart.

success_url:string

Redirect to Merchant URL after successful payment. Example: http://example.com/account/orders.

token:string

Your custom token to validate payment callback (notification).



Result Format: 200 OK

422 Unprocessable Entity

{
  "id": 1195862,
  "status": "new",
  "price_currency": "USD",
  "price_amount": "2000.0",
  "receive_currency": "EUR",
  "receive_amount": "",
  "order_id": "111",
  "payment_url": "https://bitcloudpay.com/invoice/6003de09-ee9a-4584-be0e-5c0c71c5e497",
  "token": "MVsgsjGXv-pRWMnZzsuD4B5xcdnj-w"
}

Documentation

The order is placed with the "Create Order" API method. From the user's point of view, at the moment of creating the order, the user is redirected to (payment_url) our payment page (invoice), where shopper can see the payment amount, select the desired payment currency and complete the payment.

Note on the receive_currency parameter - this is your settlement currency. When USD is selected, all your received payments are immediately settled on exchanges to guarantee a fixed payout for each order. By selecting BTC, ETH, LTC or BCH as your settlement currency, you will automatically be credited with the chosen cryptocurrency (e.g. if BTC is your receive_currency and your customer pays with ETH, you will be credited BTC according to the real-time market rate locked at the moment the invoice is generated). To keep the coins which your customers pay with, use DO_NOT_CONVERT as your receive_currency (e.g. if a customer pays in BTC, you will be credited BTC, and if the customer pays in ETH, you will be credited with ETH). Please contact our support for further clarification, if needed.

Checkout

Placing created order with pre-selected payment currency (BTC, LTC, ETH, etc). Display payment_address and pay_amount for shopper or redirect to payment_url. Can be used to White-Label invoices.

Important. Checkout method can only be used with the following payment currencies: BTC, XRP, ETH, LTC, BCH, TRX, NANO, DAI, USDS, SRN, TEL, BTT.



Definition

https://api.bitcloudpay.com/v2/orders/:id/checkout

Path Params

id: integer

Bitcloudpay order ID

Body Params

pay_currency: string

required Payment cryptocurrency. Possible values: BTC, LTC, ETH, BCH, NANO, TRX, SRN, TEL. Other cryptocurrencies are processed via Changelly and are not accessible with the Checkout method.

Examples

cURL
curl -H "Authorization: Token YOUR_APP_TOKEN" -X POST -d "pay_currency=BTC"
https://api.bitcloudpay.com/v2/orders/140043/checkout

Result Format: 200 OK

422 Unprocessable Entity

{
    "id": 1723,
    "order_id": "",
    "pay_amount": "0.000023",
    "pay_currency": "BTC",
    "payment_address": "2MzyF5xfYRAmHVPwG6YPRMY74dojhAVEtmm",
    "payment_url": "http://bitcloudpay.com/invoice/4949cf0a-fccb-4cc2-9342-7af1890cc664",
    "price_amount": "0.01",
    "price_currency": "USD",
    "receive_amount": "0.01",
    "receive_currency": "USD",
    "status": "pending",
    "created_at": "2018-05-04T21:46:07+00:00",
    "expire_at": "2018-05-04T22:11:58+00:00"
}

Documentation

White-label invoices using Checkout method

Using Checkout method, invoices can be white-labelled and integrated into your website, without redirecting the customer to Bitcloudpay.

This is achieved by pre-selecting BTC, LTC, ETH, BCH, NANO, TRX, SRN or TEL (new coins added regularly) as the payment currency, and retrieving the pay_amount and payment_address parameters. These are sufficient for a customer to complete the payment, as well as to generate a QR code which a customer can scan with a mobile wallet.



Get Order

Retrieving information of a specific order by Bitcloudpay order ID

Definition

https://api.bitcloudpay.com/v2/orders/:id

Path Params

id: integer

Bitcloudpay order ID

Examples

curl -H "Authorization: Token YOUR_APP_TOKEN"
https://api.bitcloudpay.com/v2/orders/1195824

Result Format: 200 OK

404 Not Found

{
  "id": 1195824,
  "status": "paid",
  "price_currency": "EUR",
  "price_amount": "10.0",
  "pay_currency": "BTC",
  "pay_amount": "0.001281",
  "receive_currency": "EUR",
  "receive_amount": "9.9",
  "created_at": "2018-04-24T23:43:14+00:00",
  "expire_at": "2018-04-25T00:05:40+00:00",
  "payment_address": "38gmr5MujyDxcEhaqFfC5P9K6bhJo548gu",
  "order_id": "110",
  "underpaid_amount": "0",
  "overpaid_amount": "0",
  "is_refundable": false,
  "payment_url": "https://bitcloudpay.com/invoice/4f5e5a63-5270-435d-bf05-eec369b0fdba"
}

Documentation

Fields pay_currency, pay_amount, expire_at, payment_address are only sent when the customer chooses the currency with which he is going to pay for the invoice.

List Orders

Retrieving information of all placed orders

Definition

https://api.bitcloudpay.com/v2/orders

Query Params

per_page: integer100

How many orders per page. Max: 100. Default: 100.

page: integer1

sort: string created_at_desc

Sort orders by field. Available sort options: created_at_asc, created_at_desc. Default: created_at_desc.

created_at[from]: string

Optional. Where order creation time is equal or greater. Example: 2018-09-01

created_at[to]: string

Optional. Where order creation time is equal or less. Example: 2018-09-30

Examples

curl -H "Authorization: Token YOUR_APP_TOKEN"
https://api.bitcloudpay.com/v2/orders?per_page=2&page=1&sort=created_at_desc
curl -H "Authorization: Token YOUR_APP_TOKEN"
https://api.bitcloudpay.com/v2/orders?created_at[from]=2018-09-01&created_at[to]=2018-09-30

Result Format

{
  "current_page": 1,
  "per_page": 2,
  "total_orders": 940,
  "total_pages": 470,
  "orders": [
    {
      "id": 1195862,
      "status": "new",
      "price_currency": "USD",
      "price_amount": "2000.0",
      "receive_currency": "EUR",
      "receive_amount": "",
      "created_at": "2018-04-25T13:28:16+00:00",
      "order_id": "111",
      "payment_url": "https://bitcloudpay.com/invoice/6003de09-ee9a-4584-be0e-5c0c71c5e497"
    },
    {
      "id": 1195824,
      "status": "paid",
      "price_currency": "EUR",
      "price_amount": "10.0",
      "pay_currency": "BTC",
      "pay_amount": "0.001281",
      "receive_currency": "EUR",
      "receive_amount": "9.9",
      "created_at": "2018-04-24T23:43:14+00:00",
      "expire_at": "2018-04-25T00:05:40+00:00",
      "payment_address": "38gmr5MujyDxcEhaqFfC5P9K6bhJo548gu",
      "order_id": "110",
      "payment_url": "https://bitcloudpay.com/invoice/4f5e5a63-5270-435d-bf05-eec369b0fdba"
    }
  ]
}

Order Status

Status Description
new Newly created invoice. The shopper has not yet selected payment currency.
pending Shopper selected payment currency. Awaiting payment.
confirming Shopper transferred the payment for the invoice. Awaiting blockchain network confirmation.
paid Payment is confirmed by the network, and has been credited to the merchant. Purchased goods/services can be safely delivered to the shopper.
invalid Payment rejected by the network or did not confirm within 7 days.
expired Shopper did not pay within the required time (default: 20 minutes) and the invoice expired.
canceled Shopper canceled the invoice.
refunded Payment was refunded to the shopper.

Statuses by priority:

1. new

2. pending

3. confirming*

4a. expired OR canceled**

4b. paid OR invalid

5.refunded

*The "confirming" status is sometimes skipped and "paid" or "invalid" status is sent instead.

**The "expired" or "canceled" status is sometimes changed to "paid" if the payment arrived after the invoice has expired / was canceled.

Payment Callback

Payment callback (Payment notification) will be sent to merchant's callback_url when order status is changed to pending confirming, paid, invalid, canceled, refunded or expired.

Callback data is sent in POST method.

Bitcloudpay callback sends data below:

Name Value
id Bitcloudpay (invoice) ID.
order_id Custom order ID of the merchant. Should be used to identify order or invoice number.
status Bitcloudpay payment status.
price_amount The price set by the merchant; for example, 499.95.
price_currency The currency code which defines the currency in which the merchant's goods/services are priced; for example, USD, CHF, BTC (see supported currencies).
receive_currency The currency code which defines the currency in which the merchant's settlements will be paid. Currency conversions are done by Bitcloudpay automatically. For example: EUR, USD, BTC, USDT, etc.
receive_amount The amount which will be credited to the merchant when the invoice is paid. It is calculated by taking the price amount (converted to currency units set in receive_currency) and subtracting Bitcloudpay processing fee from it.
pay_amount The amount of cryptocurrency (defined by pay_currency) paid by the shopper.
pay_currency The cryptocurrency in which the payment was made; for example, BTC, LTC, ETH.
underpaid_amount The amount of cryptocurrency (defined by pay_currency) underpaid by the shopper; for example, if pay_amount => 0.123, pay_currency => BTC, and the shopper paid 0.12 BTC, then underpaid_amount => 0.003. Changes in underpaid_amount will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
overpaid_amount The amount of cryptocurrency (defined by pay_currency) overpaid by the shopper; for example, if pay_amount => 0.123, pay_currency => BTC, and the shopper paid 0.15 BTC, then overpaid_amount => 0.027. Changes in overpaid_amount will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
is_refundable Possible values: true, false. Indicates whether or not the shopper can request a refund on the invoice. Changes in is_refundable will not trigger additional callbacks, but when order information is retrieved using GET or LIST, latest value will be shown.
created_at Invoice creation time.
token Your custom token (or generated by Bitcloudpay) to validate payment callback.

Fields pay_currency, pay_amount, expire_at, payment_address are only sent when the customer chooses the currency with which he is going to pay for the invoice.

Content-Type: application/x-www-form-urlencoded

PHP

// print_r($_POST)

Array
(
    [id] => 343
    [order_id] => 14037
    [status] => paid
    [price_amount] => 1050.99
    [price_currency] => USD
    [receive_amount] => 926.73
    [receive_currency] => EUR
    [pay_amount] => 4.81849315
    [pay_currency] => BTC
    [created_at] => 2014-11-03T13:07:28+00:00
    [token] => ff7a7343-93bf-42b7-b82c-b38687081a4e
)

See the code below how to accept callback.

Callback Retry Time

Bitcloudpay sends payment notification while your application returns response 200 (OK) HTTP status code.

  • Sends every 1 minute if retry count is <= 5
  • Sends every 5 minutes if retry count is > 5 and <= 10
  • Sends every 10 minutes if retry count is > 10 and <= 15
  • Sends every 20 minutes if retry count is > 15 and <= 20
  • Sends every 30 minutes if retry count is > 20 and <= 25
  • Sends every 1 hour if retry count is > 25 and <= 30
  • Sends every 5 hours if retry count is > 30 and <= 35
  • Sends every 1 day if try count is > 35 and <= 40
  • Callback will be canceled if retry count is >= 41

After sending payment notification, Bitcloudpay waits for a response for 20 seconds.

Payment notification will be canceled and terminated if one of the following conditions occur:

  • Payment notification is sent 40 times.
  • After sending payment notification, response status received is 301, 302 (Redirect). This commonly happens if you use "http" in your URL and it gets redirected to "https".
  • After sending payment notification, response status received is 401 (Unauthorized). This commonly happens when your website is password-protected (Basic access authentication). Ensure your website is publicly accessible.
  • Payment notification is sent to TOR network.
  • Payment notification is sent to a private network, such as localhost

IP Addresses

Payment Callback is sent from servers described in API endpoint. This API endpoint is public, authentication is not required.

Live: https://api.bitcloudpay.com/v2/ips-v4

Sandbox: https://api.bitcloudpay.com/v2/test/ips-v4

Each IP is separated by a new line. Make sure that your server, as well as third-party security services (cloudflare, incapsula, etc.), are not blocking these IP addresses.

We recommend update your IP whitelist from this API endpoint regularly.

Private Nework & Localhost

Bitcloudpay payment callback will not send notifications to private networks (for example: localhost).

In localhost, you can send test payment notification with cURL library:

curl -X POST -d "id=343&order_id=ORDER-1415020039&status=paid&price_amount=1050.99&price_currency=USD&receive_currency=EUR
&receive_amount=926.73&pay_amount=4.81849315&pay_currency=BTC&created_at=2014-11-03T13:07:28%2B00:00" http://localhost/Bitcloudpay-payment-callback

Payment Callback Logs

You can review payment callbacks and your server response to callback in your account panel. Login to your account and locate API » Payment Callbacks.

Accepting Payment Callback

Example: save the code below as accept-Bitcloudpay-callback.php and execute cURL command in your command line tool:

curl -X POST -d "id=343&order_id=ORDER-1415020039&status=paid&price_amount=1050.99&price_currency=USD&receive_currency=EUR&receive_amount=926.73
&pay_amount=4.81849315&pay_currency=BTC&created_at=2014-11-03T13:07:28%2B00:00" http://localhost/accept-Bitcloudpay-callback.php?token=5d02161be9bfb6192a33
<?php

// Your custom order_id is defined when you creating new order: https://bitcloudpay.com/developers/docs/create-order
// Also don't forget to prevent SQL injection
$result = mysql_query("SELECT * FROM orders WHERE id = " . $_POST['order_id']);
$order = mysql_fetch_assoc($result);

// token is your random secure string (for example: 5d02161be9bfb6192a33) for each order
if ($_POST['token'] == $order['token']) {
  // Handle Bitcloudpay order status https://bitcloudpay.com/developers/docs/order-statuses
  $status = NULL;
  if ($_POST['status'] == 'paid') {
    if ($_POST['price_amount'] >= $order['amount']) {
      $status = 'paid';
    }
  }
  else {
    $status = $_POST['status'];
  }

  if (!is_null($status)) {
      mysql_query("UPDATE orders SET status = '".$status."' WHERE id = ".$_POST['order_id']);
  }
}

Get Exchange Rate

Current exchange rate for any two currencies, fiat or crypto. This endpoint is public, authentication is not required.

Definition

https://api.bitcloudpay.com/v2/rates/merchant/:from/:to

Path Params

from: string

ISO Symbol. Example: EUR, USD, BTC, ETH, etc.

to: string

ISO Symbol. Example: EUR, USD, BTC, ETH, etc.

Result Format 200 OK

7469.5

List Exchange Rates

Current Bitcloudpay exchange rates for Merchants and Traders. This endpoint is public, authentication is not required.

Definition

https://api.bitcloudpay.com/v2/rates

Result Format 200 OK

{
  "merchant": {
    "BTC": {
      "EUR": "7449.99",
      "USD": "9139.34",
      "ETH": "13.18044023"
    },
    "EUR": {
      "BTC": "0.00013351",
      "USD": "1.2317",
      "ETH": "0.00175954"
    }
  },
  "trader": {
    "buy": {
      "BTC": {
        "EUR": "7449.99",
        "USD": "9139.34",
        "ETH": "13.18044023"
      },
      "EUR": {
        "BTC": "0.00013351",
        "USD": "1.2317",
        "ETH": "0.00175954"
      }
    },
    "sell": {
      "BTC": {
        "EUR": "7449.99",
        "USD": "9139.34",
        "ETH": "13.18044023"
      },
      "EUR": {
        "BTC": "0.00013351",
        "USD": "1.2317",
        "ETH": "0.00175954"
      }
    }
  }
}

Ping

A health check endpoint for Bitcloudpay API. This endpoint is public, authentication is not required.

Result Format 200 OK

{
  ping: "pong",
  time: "2017-12-13T19:07:18+00:00"
}

IP Addresses

Get IP addresses of Bitcloudpay servers

Parameters

Query Params

separator:stringnew line (\n)

(optional) Separator of ip addresses. Default new line (\n).

Examples

curl "https://api.bitcloudpay.com/v2/ips-v4?separator=%7C"

Result Format 200 OK

52.28.22.118|35.156.68.160