Introduction
This guide helps developers easily incorporate features for processing crypto payments
into their online storefronts. The Digital Crypto Pay REST API provides a seamless user
experience and gives merchants a safe and effective way to accept payments in various
cryptocurrencies.
This documentation equips you with the knowledge to:
Authenticate and secure your API requests.
Create purchase orders with detailed configuration options.
Understand the structure of callback responses for purchase status updates.
Before integrating, we advise you to go through this guide to become acquainted with the
features and parameters accessible for the API.
Authentication
The Digital Crypto Pay REST API for merchants uses API keys combined with signatures to
authenticate requests. Each merchant will receive a combination of an API key and an API
secret, which they will then use to authenticate API requests.
Signature
The signature is generated using the HMAC-SHA256 algorithm. It combines the request
body, a timestamp, and the API_SECRET (provided to the merchant) into a single string.
This string is then hashed using SHA-256. The timestamp is also included in the request as
a separate header.
Below is a code snippet for generating signature used in Digital Crypto Pay REST APIs
Creating purchases
Purchases can only be created by merchants using API key and signature authentication. Upon
successful purchase creation, the response will include a URL that the user needs to open to
continue the payment flow. The merchant will be notified of any status changes for the created
purchase via webhooks.
URL: /v1/api/purchase/init
METHOD: POST
HEADERS:
X-API-KEY: string
X-SIGNATURE: string
TIMESTAMP: string
BODY:
RESPONSE:
Headers
Request must have headers for merchant authentication.
Header | Description |
| X-API-KEY | API key provided by Digital Crypto Pay, used for Merchant identification |
| X-SIGNATURE | Cryptographic signature for authenticating request payload, with API-SECRET |
| TIMESTAMP | UNIX timestamp when signature was calculated. |
Body
Field | Type | Required | Description | Example |
| totalPrice | Big Decimal | Yes | Total price of the purchase order. Should have value in fiat currency | 100.00 |
| fiatCurrency | string | Yes | Fiat currency in which order should be created. Allowed values for now are: [“EUR”] | “EUR” |
| cryptoAllowedCurrencies | array of strings | No | Crypto currencies accepted by the merchant. | [“USDT”, “BTC”] |
| cryptoAllowedSlippage | Big Decimal | Yes | Slippage part | 0.05 |
| externalOrderId | string | Yes | OrderId defined by the merchant that will be returned in the webhook and can be used for easier order tracing | “98765” |
| externalOrderReference | string | Yes | Order reference defined by the merchant that will be returned in the webhook and can be used for easier order tracing | “order-ref1234” |
| externalOrderTermsAndCon ditionsURL | string | Yes | URL to Terms and conditions that will be shown to the customer in the payment process. | “https://fake. url.com?for=te rms_and_condit ions” |
| transactionStatusWebhook URL | string | Yes | URL that be triggered on each status change of the pruchase order. | “https://fake. url.com?for=tr ansactionstatuswebhook” |
| timeout | int | Yes | The number of seconds before payment will auto-close. | 900 |
| lineItems | Array of ListITem | No | Collection of line items that can be shown in the UI to shopper when paying the order | [<ListItem> |
| KYC | KYC | No | KYC object for current shopper that trusted merchants can provide so that identification part on Digital Crypto Payment part is skipped. | KYC |
ListItem:
NN
Field | Type | Required | Description | Example |
| name | String | Yes | Name of single line item | “fake line item” |
| description | String | No | Decription of single line item | “Detailed description for fake line item instead of lorem ipsum” |
| quantity | Integer | Yes | Quantity of single line item | 1 |
| price | Big Decimal | Yes | Price of single line item | 100 |
KYC:
Field | Type | Required | Description | Example |
| String | Yes | Shopper’s email | “user@fakemail.provider” | |
| phoneNumber | String | Yes | Shopper’s phone number | “+1234566789” |
| firstName | String | Yes | Shopper’s first name | “Fake” |
| lastName | String | Yes | Shopper’s last name | “User” |
| countryTax | String | Yes | Country where the shopper is considered a tax resident for tax purposes | “IT” |
Callback for purchase stage changes
Callbacks will be called each time a status of purchase order changes. Callbacks will use URL defined in the body of the request for creating the purchase order.
METHOD: POST
HEADERS:
X-SIGNATURE: string
X-TIMESTAMP: string
Body:
Body:
Field | Type | Required | Description |
| data | <Data> | Yes | Details of related pruchase order |
| type | String | Yes | Event type for which the webhook was triggered |
| externalCustomerId | String | Yes | external customer Id |
Data:
Field | Type | Required | Description |
| id | UUID | Yes | internal Id of the purchase order |
| createdAt | datetime | Yes | Date and time when the purchase order was created |
| updatedAt | datetime | Yes | Date and time hwen the purchase order was updated last |
| totalPrice | bigDecimal | Yes | Total price of the order |
| fiatCurrency | string [EUR,USD] | Yes | Fiat currency for the purchase order |
| quoteCurrencyAmount | bigDecimal | Yes | Crypto currency equivalent of the purchase order price |
| feeAmount | bigDecimal | Yes | Fee amount |
| extraFeeAmount | bigDecimal | Yes | Additional fee amount |
| networkFeeAmount | bigDecimal | Yes | Fee used for transaction |
| areFeesIncluded | [true,false] | Yes | Indicates if the fees are included in the original price, or if they were added on |
| flow | [buy,direct] | Yes | Indicates if shopper bought crypto to pay merchant with it or if shopper paid with crypto directly |
| status | [confirmed, completed, cancelled, failed] | Yes | Status of the purchase order |
| walletAddress | string | Yes | Merchant’s wallet address |
| cryptoTransactionId | string | Yes | Id of the crypto transaction |
| failureReason | string | No | Reason of the failure in case the status is “Failed” |
| bankTransferReference | string | No | Bank transfer reference when flow is “buy” |
| currency | string | Yes | Purchase order fiat currency |
| customerId | string | Yes | Id of the shopper |
| eurRate | bigDecimal | No | Rate for EUR conversion |
| usdRate | bigDecimal | No | Rate for USD conversion |
| externalTransactionId | string | Yes | TransactionId |
| stages | List of Stage | Yes | List of stages that this order came through so far |
| country | string | Yes | Country of the shopper |
| externalOrderId | string | Yes | OrderId provided by the merchant on order creation request |
| externalOrderReference | string | Yes | Order reference provided by the merchant on order creation request |