Introduction
The CoinPay24 API is designed as an easy starting point for online businesses and merchants that wish to accept cryptocurrencies as a payment method. CoinPay24 handles the payment flow from checkout to settlement, allowing businesses to use this innovative 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, Litecoin, Ether and other coins, unique addresses for each invoice, 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. Merchant API credentials can be created from your CoinPay24 account, where you can also add your payout details based on your preferred option for receiving settlements.
API Overview
-
In the first step of connecting the customer to the payment getway, you must call to CoinPay24 system to create an invoice
-
CoinPay24 checks if the invoice data is valid.
1. If the invoice is valid, CoinPay24 responds with 200 HTTP status and returns invoice data. After receiving 200 HTTP status, you should redirect the customer to payment_url address to go through the payment process.
2. If the invoice is not valid, CoinPay24 returns 422 (or another) error HTTP status and an error message.
-
When the customer pays the invoice, coinpay24 sends Payment Notification to your callback_url, which is defined when creating the invoice (see Create invoice). CoinPay24 also sends Payment Callback when invoice status is changed to canceled, expired or to any other invoice status. (All data will be send via the post method).
Environments
Live: | https://api.coinpay24.com/v1 |
Limits and Quotas
Invoices | 1000 per hour per userid (contact support to increase) This default value is the number of invoices that can be created per hour. Reaching the limit will prevent further invoices 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 CoinPay24 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 CoinPay24 API (examples: Create Invoice, Get Invoice).
Payment Callbacks (Payment Notifications)
Payment Callback (Payment Notification) is a response which is sent after the invoice status changes (see Invocies Statuses). CoinPay24 sends the Payment Callback to merchant's callback_url, which is set during invoice creation (see Create Invoice).
To review your Payment Callbacks, login to your CoinPay24 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 CoinPay24 to merchant's callback_url.
To review your API Requests, login to your CoinPay24 account, then go to API » Requests.
API Request attributes:
- Action - Which API method was queried.
- Response - HTTP status returned by CoinPay24.
- Parameters - Parameters used to query the CoinPay24 API.
- Response - Parameters returned by CoinPay24.
API Authentication
curl -v -H "X-API-KEY: Token YOUR_APP_TOKEN" "https://api.coinpay24.com/v1/invoices/15012"
After register to CoinPay24, you can view your exclusive token and use your token to connect to the api
Provide Token to HTTP X-API-KEY Header.
Create Invoice
curl -X "POST" "https://api.coinpay24.com/v1/invoices/create" \
-H 'X-API-KEY: YOUR_API_KEY' \
-H 'Content-Type: application/x-www-form-urlencoded; charset=utf-8' \
--data-urlencode "title=Order #62315" \
--data-urlencode "price_amount=380.00" \
--data-urlencode "price_currency=USD" \
--data-urlencode "callback_url=https://example.com/callback" \
--data-urlencode "success_url=http://example.com/success" \
--data-urlencode "cancel_url=http://example.com/cancel" \
--data-urlencode "order_id=62315" \
--data-urlencode "description=1 x Xbox360 "
The above command returns JSON structured like this:
{
"created_at": "2021-05-14T17:37:18+00:00",
"payment_url": "https://coinpay24.com/invoice/39b3c1d8984385b44489dcac27ef0d0e",
}
HTTP Request
POST https://api.coinpay24.com/v1/invoices/create
Query Parameters
Parameter | Type | Description |
---|---|---|
order_id required |
string | Merchant's custom order ID or invoice ID. Example: D542121. |
amount required |
double | Invoice amount (the amount that the customer will pay) |
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, BTC, ETH, etc. |
title | string | Max 150 characters. Example: product title (Apple iPhone 6), invoice id (MyShop invoice #12345), cart id (Cart #00004335). |
description | string | Merchant's custom invoice ID. We recommend using a unique invoice ID. Example: invoice-12345. |
callback_url | string | Send an automated message to Merchant URL when invoice status is changed. Example: http://example.com/payments/callback |
cancel_url | string | Redirect to Merchant URL when buyer cancels the invoice. Example: http://example.com/cart. |
success_url | string | Redirect to Merchant URL after successful payment. Example: http://example.com/account/invoices. |
Checkout
curl -H "X-API-KEY: Token YOUR_APP_TOKEN" -X POST -d "pay_currency=BTC" https://api.coinpay24.com/v1/invoices/512472/checkout
The above command returns JSON structured like this:
{
"id": 1723,
"order_id": "",
"pay_amount": "0.000023",
"pay_currency": "BTC",
"payment_address": "3FZbgi29cpjq2GjdwV8eyHuJJnkLtktZc5",
"payment_url": "http://coinpay24.com/pay/4949cf0afccb4cc293427af1890cc664",
"price_amount": "0.01",
"price_currency": "USD",
"status": "pending",
"created_at": "2018-05-04T21:46:07+00:00",
"expire_at": "2018-05-04T22:11:58+00:00"
}
Placing created invoice 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! The currency selected must be active in your coinpay24 panel and also supported by coinpay24.com
HTTP Request
POST https://api.coinpay24.com/v1/invoices/:id/checkout
Parameters [Path Params - GET]
Parameter | Type | Description |
---|---|---|
id required |
Int | CoinPay24 Invoice ID |
Parameters [Body Params - POST]
Parameter | Type | Description |
---|---|---|
pay_currency required |
Int | Payment cryptocurrency. Possible values: BTC, LTC, etc. |
purchaser_fullname |
string | Full Name of the purchaser (payee) provided will be pre-filled on the invoice. |
purchaser_email |
string | Email address of the purchaser (payee) provided will be pre-filled on the invoice. |
Get Inoivce
curl -H "X-API-KEY: Token YOUR_APP_TOKEN" https://api.coinpay24.com/v1/invoices/6587512
The above command returns JSON structured like this:
{
"id": 1195824,
"status": "paid",
"price_currency": "EUR",
"price_amount": "10.0",
"pay_currency": "BTC",
"pay_amount": "0.001281",
"created_at": "2018-04-24T23:43:14+00:00",
"expire_at": "2018-04-25T00:05:40+00:00",
"payment_address": "38gmr5MujyDxcEhaqFfC5P9K6bhJo548gu",
"order_id": "62315",
"underpaid_amount": "0",
"overpaid_amount": "0",
"payment_url": "https://coinpay24.com/invoice/39b3c1d8984385b44489dcac27ef0d0e"
}
Retrieving information of a specific invoice by CoinPay24 invoice ID.
HTTP Request
POST https://api.coinpay24.com/v1/invoices/:id
Parameters [Path Params - GET]
Parameter | Type | Description |
---|---|---|
id required |
Int | CoinPay24 Invoice ID |
List Invoices
curl -H "X-API-KEY: Token YOUR_APP_TOKEN" https://api.coinpay24.com/v1/invoices?per_page=2&page=1&sort=created_at_desc
curl -H "X-API-KEY: Token YOUR_APP_TOKEN" https://api.coinpay24.com/v1/invoices?created_at[from]=2018-09-01&created_at[to]=2018-09-30
The above command returns JSON structured like this:
{
"current_page": 1,
"per_page": 2,
"total_invoices": 940,
"total_pages": 470,
"invoices": [
{
"id": 1195862,
"status": "new",
"price_currency": "USD",
"price_amount": "2000.0",
"created_at": "2018-04-25T13:28:16+00:00",
"order_id": "111",
"payment_url": "https://coinpay24.com/invoice/8743c1d8984387414489dcac27ef0014"
},
{
"id": 1195824,
"status": "paid",
"price_currency": "EUR",
"price_amount": "10.0",
"pay_currency": "BTC",
"pay_amount": "0.001281",
"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://coinpay24.com/invoice/39b3c1d8984385b44489dcac27ef0d0e"
}
]
}
Retrieving information of all placed invoices.
HTTP Request
GET https://api.coinpay24.com/v1/invoices
Parameters [Path Params - GET]
Parameter | Type | Description |
---|---|---|
per_page |
Int | How many invoices per page. Max: 100. Default: 100. |
page |
Int | Default: 1 |
sort |
Int | Sort invoices by field. Available sort options: created_at_asc, created_at_desc. Default: created_at_desc. |
created_at[from]: Optional |
Int | Where invoice creation time is equal or greater. Example: 2018-09-01 |
created_at[to]: Optional |
Int | Where invoice creation time is equal or less. Example: 2018-09-30 |
Invoice Status
Status | Description |
---|---|
new | Newly created invoice. The shopper has not yet selected payment currency. |
pending | 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. |
Payment Callback
// print_r($_POST) Array ( [id] => 343 [invoice_id] => 14037 [status] => paid [price_amount] => 1050.99 [price_currency] => USD [pay_amount] => 4.81849315 [pay_currency] => BTC [created_at] => 2014-11-03T13:07:28+00:00 [ipn_secret] => C3D3C97A2F1F70FEAB23C470AFB404F3C59B3BE01DA31264D06F12A3F5D94F11985EFEB882813100F5CF8AC5DD7D6833AC0093303DC0765FC0DCDDEFF5CF175D )
Payment callback (Payment notification) will be sent to merchant's callback_url when invoice status is changed to pending confirming, paid, invalid, canceled, refunded or expired.
Callback sends data below
Name | Value |
---|---|
|
coinpay24 invoice (invoice) ID. |
|
Custom invoice ID of the merchant. Should be used to identify invoice or invoice number. |
|
coinpay24 payment status. |
|
The price set by the merchant; for example, 499.95. |
|
The currency code which defines the currency in which the merchant's goods/services are priced; for example, USD, CHF, BTC (see supported currencies). |
|
The currency code which defines the currency in which the merchant's settlements will be paid. Currency conversions are done by coinpay24 automatically. For example: EUR, USD, BTC, USDT, etc. |
|
The amount which will be credited to the merchant when the invoice is paid. It is calculated by taking the |
|
The amount of cryptocurrency (defined by |
|
The cryptocurrency in which the payment was made; for example, BTC, LTC, ETH. |
|
The amount of cryptocurrency (defined by |
|
The amount of cryptocurrency (defined by |
|
Invoice creation time. Fields |
|
Your custom token (or generated by coinpay24) 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
Callback Retry Time
coinpay24 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, coinpay24 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.
Errors
The Kittn API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The kitten requested is hidden for administrators only. |
404 | Not Found -- The specified kitten could not be found. |
405 | Method Not Allowed -- You tried to access a kitten with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The kitten requested has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many kittens! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |
Common Issues
Unable to create invoice / unable to send a request to CoinPay24 API
Reason | Solution |
---|---|
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 invoice, etc. | You can see the details of a specific API request issue by logging in to your CoinPay24 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 CoinPay24 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 CoinPay24 API is working incorrectly, or is outdated | Please check your library version |
Your server cannot reach CoinPay24.com | Check if CoinPay24.com is available and if your server can reach it (also see Status Page) |