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:
Content-Type: application/json
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):
token
(like mentioned above, obtained in your web panel)
For more information about specific resource URIs, please visit the resource documentation.
REST API Resources
Invoices
Resource
Example of invoice resource:
{
"data": {
"id": "1Ba89hBacPtLgQ3Cqu7aR8"
"url": "https://cryptopay.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
"status": "confirmed",
"price": 20,
"currency": "USD",
"orderId": "INV-202201001",
"createdStamp": 1670556426,
"redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
"expireStamp": 1670560026,
"paymentWallet": "Trust Wallet",
"paymentCurrency": "BTC",
"paymentAmount": "0.001214",
"paymentAddress": "bc1qxy2kgdygjraqtzq2n0yrf2593p83kkfjhx0wlh",
"exchangeRates": {
"BTC": {
"USD": "22853.530000"
}
},
"transactions": [{
"txid": "6f8dc09bac7127eaa7845b400f35fb045ba43bd71c41c832f87d38fa120d8e5c",
"vout": "6",
"amount": "0.001214",
"confirmations": 1
}],
"exceptionStatus": false,
"paymentTotals": "0.001214",
"underpayAllowed": false,
"overpayAllowed": false,
"amountPaidInvoicingCurrency": "20.00",
}
}
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 for an expiration time set by merchant.
Name | Type |
---|---|
id Invoice resource id |
string |
url Web address of invoice |
string |
status Invoice status can have the following values:
|
string |
price Fixed price amount for the checkout, in the "currency" of the invoice object. |
string |
currency ISO 4217 3-character currency code. This is the currency associated with the price field. |
string |
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 |
createdStamp UTC timestamp (in seconds) of invoice creation |
number |
redirectUrl The shopper will be redirected to this URL when clicking on the Return button after a successful payment or when clicking on the Close button. Make sure you include "http://" or "https://" in the url. |
string |
expireStamp UTC timestamp (in seconds) of invoice expiration |
number |
paymentWallet Name of the wallet, that shopper has selected he is doing payment from. |
string |
paymentCurrency This field will be populated with the cryptocurrency selected to pay the Cryptopay invoice, current supported values are "BTC".. If not yet selected, this field will not be returned. This is the currency associated with the "paymentAmount" field. |
string |
paymentAmount The amount in cryptocurrency the shopper is supposed to pay to fulfill the invoice. This is associated with "paymentCurrency" field. |
string |
paymentAddress The crypto address that shopper is supposed to send funds to. |
string |
exchangeRates Currency exchange rates that were used to calculate payment amount from invoice price. |
object |
transactions Initially empty when the invoice is created. This array will be populated with the crypto currency transactions linked to the invoice. |
array |
↳ txid Crypto transaction hash. |
string |
↳ vout Crypto transaction Vout. |
string |
↳ amount Amount. |
string |
↳ confirmations Number of confirmations. |
number |
exceptionStatus Exception status can have the following values:
|
false or string |
paymentTotals The total amount paid on this invoice. If invoice is paid in full with exact amount, this should be the same as paymentAmount |
string |
underpayAllowed Whether underpay was allowed on this invoice. |
boolean |
overpayAllowed Whether overpay was allowed on this invoice. |
boolean |
amountPaidInvoicingCurrency If underpay or overpay was allowed and underpay or overpay happened (see field exceptionStatus), this will be total amount that client has sent in the invoicing currency. |
string |
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": 20,
"orderId": "INV-202201001",
"notificationUrl": "https://merchant.com/shop/notifications",
"redirectUrl": "https://merchant.com/shop/return",
"token": "CP.tUt3MJFzfDSeuK1UGeVNa59q",
"email": "[email protected]"
}
EOF
<?php
$resourceUrl = 'https://cryptopay.io/api/invoices';
$postData = json_encode([
'currency' => 'USD',
'price' => 20,
'orderId' => 'INV-202201001',
'notificationUrl' => 'https://merchant.com/shop/notifications',
'redirectUrl' => 'https://merchant.com/shop/return',
'token' => 'CP.tUt3MJFzfDSeuK1UGeVNa59q',
'email' => '[email protected]'
]);
$curlHandle = curl_init($resourceUrl);
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, [
'Content-Type: application/json'
]);
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'POST');
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, stripslashes($postData));
$result = curl_exec($curlHandle);
$resultData = json_decode($result, TRUE);
curl_close($curlHandle);
echo $resultData;
?>
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 |
email The email of user can be assigned by merchant. In this case, Cryptopay will not be asking customer to enter his email during the checkout but will use this email provisioned by merchant. |
string |
O |
HTTP Response
{
"data": {
"id": "1Ba89hBacPtLgQ3Cqu7aR8"
"url": "https://cryptopay.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
"status": "new",
"price": 20,
"currency": "USD",
"orderId": "INV-202201001",
"createdStamp": 1670556426,
"redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
"expireStamp": 1670560026,
}
}
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/1Ba89hBacPtLgQ3Cqu7aR8?token=CP.yOhKIHdof5bvNKCibE6MNgREeysr4"
<?php
$resourceUrl = "https://cryptopay.io/api/invoices";
$invoiceId = "1Ba89hBacPtLgQ3Cqu7aR8";
$token = "CP.yOhKIHdof5bvNKCibE6MNgREeysr4";
$curlHandle = curl_init($resourceUrl . '/' . $invoiceId . '?token=' . $token);
curl_setopt($curlHandle, CURLOPT_CUSTOMREQUEST, 'GET');
curl_setopt($curlHandle, CURLOPT_HTTPHEADER, [
'Content-Type: application/json'
]);
$result = curl_exec($curlHandle);
$resultData = json_decode($result, TRUE);
curl_close($curlHandle);
echo $resultData;
?>
GET https://cryptopay.io/api/invoices/:invoice-id
HTTP Response
{
"data": {
"id": "1Ba89hBacPtLgQ3Cqu7aR8"
"url": "https://cryptopay.io/invoice?id=1Ba89hBacPtLgQ3Cqu7aR8",
"status": "confirmed",
"price": 20,
"currency": "USD",
"orderId": "INV-202201001",
"createdStamp": 1670556426,
"redirectUrl": "https:\/\/merchant.com\/payment\/123456\/return",
"expireStamp": 1670560026,
"paymentWallet": "Trust Wallet",
"paymentCurrency": "BTC",
"paymentAmount": "0.001214",
"paymentAddress": "bc1qxy2kgdygjraqtzq2n0yrf2593p83kkfjhx0wlh",
"exchangeRates": {
"BTC": {
"USD": "22853.530000"
}
},
"transactions": [{
"txid": "6f8dc09bac7127eaa7845b400f35fb045ba43bd71c41c832f87d38fa120d8e5c",
"vout": "6",
"amount": "0.001214",
"confirmations": 1
}],
"exceptionStatus": false,
"paymentTotals": "0.001214",
"underpayAllowed": false,
"overpayAllowed": false,
"amountPaidInvoicingCurrency": "20.00",
}
}
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
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.
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.
Make sure to not rely on whitelisting Cryptopay’s sending IP addresses, as these IP addresses are subject to change without notice.
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 |