Coinpayments API docs defines a standard, language-agnostic interface to CoinPayments API. The platform allows merchants to integrate the payment system into their own websites or applications, allowing their customers to pay for goods or services with cryptocurrency. The API documentation provides the necessary information for developers to integrate the payment system into their own platforms, including details on how to authenticate requests, what parameters to include in requests and responses, and how to handle errors. Overall, the API is designed to provide a simple and secure way for merchants to accept cryptocurrency payments from their customers. In these docs you'll find everything you need to leverage CoinPayments for your applications.

Also, while studying documentation, you can test it in Postman. For this, you can download API collection here. For information on authentication with the Postman collection, please, visit this section.

CoinPayments provides a multi-currency wallet that enables businesses and individuals to store, send, and receive a wide range of digital currencies and tokens. The free-to-set-up wallet is available on web and mobile, enabling account management online and on the go.

Some of the key features of the website include:

1. Support for multiple popular cryptocurrencies, allowing customers to pay with the digital currency of their choice.
2. Generate invoices and manually share them with buyers through a link or via email.
3. Callback Addresses feature allows merchant to receive payment without specifying the amount or time in advance.
4. Real-time updates using Webhooks, The API provides updates on the status of transactions, allowing merchants and customers to track the progress of their payments.
5. Advanced security measures to ensure that all transactions are safe and secure.

This section provides an overview of the common errors that you may encounter when utilizing CoinPayment API. By familiarizing yourself with these errors, you will be better equipped to handle potential issues and troubleshoot effectively. Understanding these errors will contribute to a smoother integration process and ensure a more seamless payment experience for your users.

Unauthorized

This error occurs when an invalid clientId or clientSecret is used to generate API signature to authenticate requests. It may also occur if a clientId is valid but the integration is either deleted or the user's account does not exist. or an invalid or incorrect client secret is provided. In such cases, the API returns an "Unauthorized" error.

Insufficient Funds

This error can occur in different scenarios, such as during withdrawal to an external address or when converting a coin to another, whether to an internal or external address. It arises when the user's wallet does not have enough balance to cover the requested transaction amount.

Invalid Address

When sending a request to create a withdrawal or a conversion, if the provided address is not valid or formatted incorrectly, this error is triggered. Users should double-check the address they provided and ensure it follows the required format. here are examples of Valid addresses

Valid UTXO-Based Coin Addresses:

• Bitcoin (BTC): 1BvBMSEYstWetqTFn5Au4m4GFg7xJaNVN2
• Bitcoin Cash (BCH): bitcoincash:qr7uq7uvujmzhcv29tw92q0hs7fwpht4fvl4a4kj9a
• Litecoin (LTC): LZx9pzGfH6mKSzVsJZnryeVrRzt6X8uZ9r

Valid Token Coin Addresses:

• Ethereum (ETH): 0x7E5F4552091A69125d5DfCb7b8C2659029395Bdf
• ERC-20 Tokens (e.g., DAI, USDT): 0x6B175474E89094C44Da98b954EedeAC495271d0F

Invalid or Unsupported Currency:

This error occurs when the requested invoice, withdrawal, conversion involves an invalid or unsupported currency. It could be due to the currency not being listed or supported on the platform. Users can utilize the currencies API included in the documentation to list all supported currencies and verify if their intended currency is supported before initiating the transaction.

Bad request ( Input validation errors ):

This error occurs when there are issues with the validation of fields in the request's payload. For example, if a required field is not sent, or if the fields have invalid values or incorrect types. The API response for a validation error includes a description of the error and may provide details about the missing fields or the specific issues with the payload.

The API provides access to our platform's data and functionality, but in order to maintain the stability and performance of our services, rate limits have been implemented. Rate limits are set to prevent excessive use of the API and to ensure fair usage among all integrations. Currently, the rate limit is capped at a maximum of 70 requests per second.

CoinPayments API uses SHA-256 which is a way of authenticating an API request to ensure that it comes from a trusted source. In this scheme, the API server generates a unique signature for each request using the SHA-256 hashing algorithm.

Prerequisites

To Integrate Coin Payments API you need to obtain CLIENT ID and CLIENT SECRET. If you have already created your credentials, you may skip to next section.

First, you need to create an account.

Then log into your account.

Once you're logged into your account, click on Integrations 👇

API integrations 🏗

Add integration ➕

Give a name and a URL to your integration - more on the URL later.

Warning It is strongly recommended that you save your credentials after they are shown to you. Your credentials will only be displayed once, and if you lose them, you will not be able to access the API. Please take the time to save your credentials in a secure location so that you can use them in the future.

---

In order to properly sign an authenticated request for the CoinPayments v2 API, the following headers must be included:

• X-CoinPayments-Client
• X-CoinPayments-Timestamp
• X-CoinPayments-Signature

The following sections are instructions for properly populating these headers.

---

X-CoinPayments-Client

Populate this header with your clientId.

Example value cc7caaa431d54ad6accfd28b20170ee4

---

X-CoinPayments-Timestamp

Before we Populate this header with the current time as a UNIX timestamp, exclude the milliseconds epoch, example:

const date = new Date().toISOString().split(".")[0];

Example value: 2022-12-19T19:27:04

---

Construct the request queryString

To create an API signature, you first need to construct the query string which is made of the following attributes concatenated together

• method
• url
• clientId
• date

Example ( Javascript )

const queryString = `\ufeff${method}${url}${clientId}${date}${JSON.stringify(requestPayload)}`;

For requests with no request body, replace last attribute by an empty string: Example ( Javascript )

const queryString = `\ufeff${method}${url}${clientId}${''}`;

---

X-CoinPayments-Signature

Next step is to use your clientSecret to generate the signature using SHA-256 encryption algorithm as follows:

const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

Example value: oW7d1ktvK7R6741oACgVR3bysGTPY8tqren0WTmmEk0=

---

Here is a complete example of how to generate an API signature for making a call to the create wallet API:

const clientId = 'd0ccc52b8204460783d375e278082de2';
const clientSecret = 'WYEB+hN+89waO76QeO9T7IIqhdo/60GHrdYu2vEa7Tg=';
const url = `https://api.coinpayments.com/api/v1/merchant/wallets`;
const method = 'POST';
const date = new Date().toISOString().split('.')[0];

const createWalletDto = {
  currencyId: 2,
  label: 'Online Shop Wallet',
  webhookUrl: 'https://mysite.com/api/v1/payment/notification',
};

const queryString = `\ufeff${method}${url}${clientId}${date}${JSON.stringify(createWalletDto)}`;


const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

const headers = {
  'X-CoinPayments-Client': clientId,
  'X-CoinPayments-Timestamp': date,
  'X-CoinPayments-Signature': signature,
};


/** Make API call using axios ( you may choose any http client ) */
const axiosoptions = {
  url,
  headers,
  method,
  data: createWalletDto,
};

const response = await this.httpsService.request(options).toPromise();
console.log(response);

---

When setting up authentication with Postman to test out our API collection, follow these steps:

1. Set up environment variables:

• Use https://api.coinpayments.com/api/v1/ as baseUrl.
• Provide your clientID and clientSecret from your API integration.

2. Provide the following script in the collection Pre-request Script section:

---

const clientId = pm.environment.get('clientId');
const clientSecret = pm.environment.get('clientSecret');

const date = new Date().toISOString().split('.')[0];

const queryString = `\ufeff${pm.request.method}${pm.variables.replaceIn(pm.request.url.toString())}${clientId}${date}${pm.request.body}`;
const hash = CryptoJS.HmacSHA256(queryString, CryptoJS.enc.Utf8.parse(clientSecret));
const signature = CryptoJS.enc.Base64.stringify(hash);

pm.request.headers.add({
    key: 'X-CoinPayments-Client',
    value: clientId
})

pm.request.headers.add({
    key: 'X-CoinPayments-Timestamp',
    value: date
})

pm.request.headers.add({
    key: 'X-CoinPayments-Signature',
    value: signature
})

---

In order to perform most API requests regarding payment/wallet management, the merchant has to provide a currency ID in the request. CoinPayments exposes currencies API endpoints allowing merchants to view the list of available cryptocurrencies in the system and learn about their details and capabilities.

Each currency supported by CoinPayments has a specific ID assigned to it. Besides, CoinPayments supports both native coins and tokens. In order to allow managing tokens of the same blockchain, CoinPayments API contains information on both - ID of the coin blockchain, where token belongs, and the smart contract address of the token. This information is returned in the format 'coinID:smartContract'. For example, if ID of ETH is "35", then for ERC20 USDT it would be "35:0x55d398326f99059ff775485246999027b3197955".

Currency IDs are used for creating and listing merchant wallets. When creating a wallet, if only native currency ID is specified, the wallet is created for the same native currency. In case a wallet for the token is required, merchant must additionally indicate the token contract address when creating a wallet. See Create Wallet.

Also, currency IDs and contract addresses are used when creating transactions from a merchant wallet. For example, the body of the spend request specifically indicates the "toCurrency" ID and "from" and "to" contract addresses. This allows CoinPayments to indicate whether the said transaction is a regular withdrawal of funds or a transaction that additionally requires conversion. See Spend Request.

Below, you will find the detailed information on currency-related endpoints and their field values.

API for rates supported by CoinPayments.

CoinPayments exposes invoices API endpoints allowing merchants to implement a payment gateway on their platform, and let buyers pay for goods and services in a wide selection of cryptocurrencies.

With CoinPayments invoices API you may:

1. Create invoice links for payment collection.
2. Build custom white label checkout solutions for your business.
3. Create buy-now buttons for quick buyers' checkout. CoinPayment’s invoices API is built around “invoice” entity. In other words, under the hood it generates an invoice with all the buyer’s and merchant’s data plus information on the product/service. Thus, merchants will be flexible in managing payments with the help of this data via a set of available endpoints.

Below you will find information on how payment flow is organized for each of the above-mentioned approaches.

Payment Flow for Invoice Links

Let us consider a subscription use case, where you have a platform that provides services with a subscription payment model. Every month you need to send out invoices to your users with the reminder to pay for the subscription and ability to collect this payment in crypto. In order to automate this flow, you may want to use CoinPayments API. Here are the steps that should take place in order for a payment to occur:

1. Merchant adds details on services for which invoice is issued, indicates user’s details like name, payment address and email, if provided.
2. With the help of createInvoice endpoint merchant generates an invoice entity with the data from step 1.
3. As a response to the createInvoice endpoint, merchant receives:

• an invoice Id to further check invoice status
• a link to the invoice document with the active payment button that would lead user to payment checkout.

Note: In order this request could work properly, merchant must make sure to eliminate the following attribute from the request:

   "payment": {
     "paymentCurrency": "1004:somecontractaddress"
     "refundEmail": "user@example.com"
   }

Providing the 'refundEmail' and 'paymentCurrency' will initiate the White Labeling flow disclosed below. Leaving 'payment' attribute empty will cause an error.

4. Invoice is added to merchant's account transaction history where merchant will be able to track payment status.
5. Merchant sends out the link to the invoice to the buyer.
6. Buyer enters their email for potential refunds, selects the currency for payment.
7. The buyer is presented with a payment address, total amount of cryptocurrency to-be-deposited, and a timer within which the transaction has to be completed.
8. At the same time currency of payment is reflected in the transaction details of the payment in the merhant's transaction history.
9. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending invoice payment notifications for each status change thereof (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

Payment Flow for Integrated Checkout with White Labeling

Let us consider a case where you have an online shop and you want to accept payment for goods in cryptocurrency. With CoinPayments API you will be able to allow buyers to request goods and pay with the cryptocurrency all at your website and under your own branding. Here are the steps that should take place in order payment could occur:

1. Buyer selects product/service on the merchant’s site and adds them to the shopping cart. At the checkout, buyer indicates their details like name, payment address and email and clicks "Pay".
2. By clicking "Pay", buyer launches the payment flow. In this flow, buyer's email provided when creating the order, is recorded as the 'RefundEmail' in the 'creteInvoice' request for possible refunds in case of over- and underpayment.

   {
     ...
     "Payment": {
    "RefundEmail": "norefunds@in.crypto"
     }
   }
   

At the same time, the 'createInvoice' endpoint generates an invoice entity including:

• 'invoiceId' to get payment address and check payment status
• list of available currencies for payment with currency description, payment amount and fees
• payment expiration timestamp.

3. If merchant wants to allow buyer to select currency at checkout, payment address is obtained with the help of 'getPaymentAddressByCurrency' endpoint, once buyer chooses the currency for payment. If merchant's website has preset currency for all goods and services, the same endpoint must be triggered at step 2., once buyer clicks "Pay". As a result, buyer is presented with the following data:

• a currency id
• a payment address
• total amount of the selected cryptocurrency to be deposited
• timer for completing the transaction.

3.a. A merchant can combine steps 2 and 3 into one, i.e. create an invoice for the shopping cart content already with the payment in the specific cryptocurrency. For this, when creating invoice, merchant should provide id of the 'PaymentCurrency' in the 'Payment' entity of the 'CreateInvoice' request:

{
  ...
  "Payment": {
    "RefundEmail": "test@gmail.com",
    "PaymentCurrency": "1004:somecontractaddress"
    }
  }

The indication of the cryptocurrency id will trigger creation of the invoice together with payment and HotWallet (address for buyer).

4. After that merchant can check the status of the payment with the help of getPaymentStatus endpoint that includes:

• status of payment
• how much was detected and confirmed on blockchain
• how much was detected but not confirmed yet.

5. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending payment notifications for each status change (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

A merchant can simplify the payment process for the buyer by incorporating payment details like payment amount, currency and payment address into a QR code. Below is an example of a script to create a QR code:

---

<div id="canvas"></div>
<script type="text/javascript" src="https://unpkg.com/qr-code-styling@1.5.0/lib/qr-code-styling.js"></script>
<script type="text/javascript">
  const generateQRData = (currency, address, tag, amount) => {
    switch (currency.name) {
      case 'Bitcurrency SV':
        return `bitcurrency:${address}?sv&amount=${amount}`;
      case 'Tether USD (Omni)':
        return `bitcurrency:${address}?amount=${amount}&req-asset=${currency.id}`;
      case 'BinanceCoin':
        return `bnb:${address}?sv&amount=${amount}&req-asset=${currency.id}`;
      case 'Tether USD (ERC20)':
        return `ethereum:${address}?value=${amount}&req-asset=${currency.id.slice(currency.id.indexOf(':') + 1)}`;
      case 'Tether USD (TRC20)':
        return `tron:${address}?value=${amount}&req-asset=${currency.id.slice(currency.id.indexOf(':') + 1)}`;
      default:
        return `${currency?.name?.toLowerCase().replace(/ /g, '')}:${address}?amount=${amount}${tag ? `&tag=${tag}` : ''}`;
    }
  };

  const color = "#2A5ED5";
  const corner = "#000000";
  const margin = 5;

  const qrCode = new QRCodeStyling({
    width: 200,
    height: 200,
    dotsOptions: {
      color: color,
      type: "square"
    },
    backgroundOptions: {
      color: "transparent",
      gradient: null
    },
    cornersSquareOptions: {
      type: "square",
      color: corner
    },
    cornersDotOptions: {
      type: "square",
      color: corner
    },
    imageOptions: {
      crossOrigin: "anonymous",
      imageSize: 0.5,
      margin: margin
    }
  });

  qrCode.append(document.querySelector('#canvas'));
  qrCode.update({
    data: generateQRData(currency, address, tag, amount)
  });
  </script>

---

Payment Flow for Integrated Checkout with Buy-Now Button

Let us consider another case for an online shop where you want to accept payment for goods in cryptocurrency and want to allow your buyers to make quick purchases by clicking on the Buy-Now button next to the good or service you offer. With CoinPayments API you will be able to allow buyers to request goods and pay with the cryptocurrency in a matter of a few clicks. Here are the steps that should take place in order payment could occur:

1. Buyer detects product/service on the merchant’s site and wants to order them immediately, so they click on the "Pay with CoinPayments" button next to the product/service.
2. By clicking "Pay with CoinPayments", buyer launches the payment flow. As a first step of the flow, buyer is requested to provide their email. The email is recorded as the 'RefundEmail' in the creteInvoice request for possible refunds in case of over- and underpayment. At the same time, the createInvoice endpoint generates an invoice entity including:

• invoiceId to get payment address and check payment status
• list of available currencies for payment with currency description, payment amount and fees
• payment expiration timestamp.

3. If merchant wants to allow buyer to select currency at checkout, payment address is obtained with the help of getPaymentAddressByCurrency endpoint, once buyer chooses the currency for payment. If merchant's website has preset currency for all goods and services, the same endpoint must be triggered once buyer clicks "Pay". As a result, buyer is presented with a payment address, total amount of the selected cryptocurrency to be deposited, and a timer within which the transaction has to be completed.
4. After that merchant can check the status of the payment with the help of 'getPaymentStatus' endpoint that includes:

• status of payment
• how much was detected and confirmed on blockchain
• how much was detected but not confirmed yet.

5. Additionally, if the merchant has webhooks set-up, CoinPayments will be sending payment notifications for each status change (e.g. invoiceCreated, invoicePending, invoicePaid, invoiceCompleted, invoiceCancelled, invoiceTimedOut).

Payment Settings

Funds that merchants receive via payments are primarily deposited to the CoinPayments system balance. From there, Coinpayments conducts payouts to the merchant's balance. CoinPayments UI provides the merchant with a possibility to set up mode and frequency for paying out funds from CoinPayments balance to the merchant's own balance. The settings are set up by currency.

Below, you will find the detailed information on each of the invoices endpoints and their field values. Endpoints are the same for both described use-cases with the slight difference in utilizing certain fields in schemas. All such differences will be outlined explicitly.