NAV
cURL PHP

REST API Overview

CryptoPay provides a standards-based REST interface which enables application developers to interact in a powerful, yet secure way with their CryptoPay account. Using the CryptoPay API, clients can create and manage invoices, and much more.

Concepts

Api Contracts

CryptoPay considers the following types of API changes to be non-breaking and backwards-compatible:

exposing a new resource type adding a new method to an existing resource type adding an optional property to an existing resource type adding an optional query parameter to an existing resource method deprecating an existing resource method and providing an alternative

Environments

There are two environments available for merchants to use the following API.

To access these APIs, merchants need to combine the base URL + endpoint and make sure to have API credentials for the corresponding environments.

Environment Base URL API Credentials
Test https://test.cryptopay.io test account
Production https://cryptopay.io production account

API Tokens

Each API call must be accompanied by an API Token which grants access to the requested capability. You can generate multiple API tokens, each with different capabilities, that may grant broad or narrow privileges.

Access Control

To use any non-public API endpoint a token will need to be sent with the API request. You can generate a token via the Settings -> API Tokens page.

Making Requests

Requests to the CryptoPay REST API follow a RESTful convention using standard HTTP verbs against various CryptoPay resources to return JSON formatted responses.

Each request should include in the HTTP headers:

To make an API request send an HTTP request with a HTTP method to a resource URI and include in the body JSON parameters of the following (plus any additional parameters needed):

For more information about specific resource URIs, please visit the resource documentation.

REST API Resources

Invoices

Resource

Example of invoice resource:

{
  "data": {
    "id": "Hpqc63wvE1ZjzeeH4kEycF",
    "url": "https://cryptopay.io/invoice?id=Hpqc63wvE1ZjzeeH4kEycF",
    "status": "complete",
    "price": 10,
    "currency": "USD",
    "orderId": "20220510_81634",
    "description": "Big Bulk Item 12",
    "invoiceTime": 1620669854224,
    "expirationTime": 1620670754224,
    "currentTime": 1620747087868,
    "amountPaid": 700700,
    "displayAmountPaid": "0.007007",
    "exceptionStatus": false,
    "targetConfirmations": 6,
    "transactions": [
      {
        "amount": 700700,
        "confirmations": 6,
        "receivedTime": "2021-05-10T18:05:12.472Z",
        "txid": "0bdcb930b91d63eb10ec11e27a060d4dd25380d229c4b28a29a1456e0aa60128",
        "outputIndex": 1
      }
    ],
    "redirectURL": "https://merchantwebsite.com/shop/return",
    "paymentSubtotals": {
      "BTC": 17500,
    },
    "paymentTotals": {
      "BTC": 29800,
    },
    "paymentDisplayTotals": {
      "BTC": "0.000298",
    },
    "paymentDisplaySubTotals": {
      "BTC": "0.000175",
    },
    "exchangeRates": {
      "BTC": {
        "USD": 57204.993195,
      },
    },
    "transactionCurrency": "BTC",
  }
}

Invoices are time-sensitive payment requests addressed to specific buyers. An invoice has a fixed price, typically denominated in fiat currency. It also has an equivalent price in the supported cryptocurrencies, calculated by CryptoPay, at a locked exchange rate with an expiration time of 15 minutes.

Name Type
data object

Create an invoice

This endpoint creates an invoice.

HTTP Request

curl -X POST \
-H "Content-Type: application/json" \
--url "https://cryptopay.io/api/invoices" \
-d @- <<'EOF'
{
"currency": "USD",
"price": 10,
"orderId": "20220525_12345",
"notificationURL": "https://merchantwebsite.com/shop/notifications",
"redirectURL": "https://merchantwebsite.com/shop/return",
"token": "AKnJyeLF1BjAfgfDbVUzHXk64N1WuDq3R9xtZouQFhSv"
}
EOF

POST https://cryptopay.io/api/invoices

Body

Name Type Presence
currency
ISO 4217 3-character currency code. This is the currency associated with the price field
string M
price number M
orderId
Can be used by the merchant to assign their own internal Id to an invoice. If used, there should be a direct match between an orderId and an invoice id
string O
notificationUrl string O
redirectUrl string O

HTTP Response

On the right side, you will find an example of the invoice object returned in the response you will get from the CryptoPay server. A description of all invoice fields is available in the resource section.

Retrieve an invoice

This endpoint retrieves an invoice.

HTTP Request

curl -X GET \
-H "Content-Type: application/json" \
--url "https://cryptopay.io/api/invoices/G3viJEJgE8Jk2oekSdgT2A?token=AKnJyeLF1BjAfgfDbVUzHXk64N1WuDq3R9xtZouQFhSv"

GET https://cryptopay.io/api/invoices/:invoice-id

HTTP Response

On the right side, you will find an example of the invoice object returned in the response you will get from the CryptoPay server. A description of all invoice fields is available in the resource section.

Notifications

Currently, CryptoPay makes notifications in the form of webhooks (HTTP POST callbacks). The primary purpose of payment notification is to alert the merchant’s ecommerce server that the status of a resource (invoice) has changed. The messages are sent to the notificationURL field when creating the invoice. The body of the payment notifications sent by CryptoPay is a JSON-formatted string (Content-Type: application/json).

Handling

  1. The payment notification shall be used as a trigger to verify the status of a specific invoice. This can be done by fetching the corresponding invoice, since invoice id is provided in the body of the payment notification.

  2. The CryptoPay server expects an HTTP 200 response with an empty body. Any other HTTP response is considered by CryptoPay as a failed delivery. The CryptoPay server attempts to send payment notifications multiple times until the send is either successful or the CryptoPay server gives up.

  3. Make sure to not rely on whitelisting CryptoPay’s sending IP addresses, as these IP addresses are subject to change without notice.

  4. Make sure to use HTTPS for your notificationURL.

Invoices

Headers

Header Value
Accept application/json
Content-Type application/json

Example of webhook notification:

{
  "id": "1Bmjx2cap7jmaG4AipSHjv"
}

Body

Name Type
id CryptoPay invoice id string