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

Limits and Quotas

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

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]

Parameters [Body Params - POST]

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]

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]

Invoice Status

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

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:

Common Issues

Unable to create invoice / unable to send a request to CoinPay24 API