NAV
shell

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

  1. In the first step of connecting the customer to the payment getway, you must call to CoinPay24 system to create an invoice

  2. 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.

  3. 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:

To review your API Requests, login to your CoinPay24 account, then go to API » Requests.

API Request attributes:

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

id

coinpay24 invoice (invoice) ID.

invoice_id

Custom invoice ID of the merchant. Should be used to identify invoice or invoice number.

status

coinpay24 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 coinpay24 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 coinpay24 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 invoice 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 invoice information is retrieved using GET or LIST, latest value will be shown.

created_at

Invoice creation time.

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.

token

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.

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:

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)