API documentation merchant.cryptex.net
- Introduction
- Preparation steps
- Cryptex Merchant Interface Workflow
- Possible payment statuses
- Description of API requests
Introduction
Cryptex Merchant is a cryptocurrency payment gateway for online shops, services etc. With the service, selling goods and providing services for digital assets will become as easy as regular payments through fiat payment gateways.
To integrate CryptexPay into the system, businesses don't need to do any complicated configuration on their end — just connect the payment gateway via API to the CRM and website, and all information will be available in the merchant's personal account on https://merchant.cryptex.net. In this way, any online retailer or service provider can significantly expand its geographical reach, and unlike fiat payment gateways, cryptocurrency conversion occurs with lower fees than automatic exchange of national fiat currencies.
Preparation steps
You need to register your account at https://merchant.cryptex.net/ru/auth/signup to access your Merchant account. Only 1 shop/service can be linked to one account.
After registration you are automatically redirected to the settings page and a unique Key for your service is generated.
You need to fill in the following fields on the settings page to work through the Merchant:
The currency you wish to accept via merchant.
Contact information that will be displayed on the pages during the payment. There are 3 types of contacts available: email, Jabber, Telegram. In total, no more than 5 contacts.
The name of the store is the name of your service, which will be displayed on the payment pages in Merchant.
Store URL — the address of your service.
The URL of a successful payment is the Web address to which the Merchant will redirect the Buyer when the payment is successful.
Webhook URL of successful payment — the address for sending notifications about successful payment.
Cryptex Merchant Interface Workflow
To accept online payments, the Seller's website must redirect the Buyer to Cryptex Merchant to pay for goods or services ordered on the Seller's website. Upon successful completion of the payment, the Buyer will be redirected back to the Seller's website.
The process of accepting payments through Merchant consists of the following steps:
The order page on the seller's website. The Buyer chooses goods or services in the e-shop and decides to buy. The seller displays the total amount of the purchase and the Buyer proceeds to pay for his order by clicking on the corresponding link. The seller's website sends a POST request to create a payment and redirects the Buyer to Cryptex Merchant. The request must include the store's key (key specified in Merchant's personal account), order amount, currency (currency, USD), order identification number (order id). In response to the request, the payment identification number (payment_id) is generated The seller's website sends a POST request to create a payment and redirects the Buyer to Cryptex Merchant. The request must include the store's key (key specified in Merchant's personal account), order amount, currency (currency, USD), order identification number (order id). In response to the request, the payment identification number (payment_id) is generated.
The payment currency selection page on the Merchant website is available at https://merchant.cryptex.net/pay/{payment_id}. Currencies available for payment are show to the Buyer, and also the order date, the order number, the name of the Seller's website. The Buyer can also return back to the site from which he switched, in which case the Buyer will be redirected back to the seller's website using the link that was specified in the Seller's personal account as a return. If the buyer has chosen the currency for payment, a request is sent to receive the address and go to the next page.
The page of the selected payment currency. The buyer is shown the address to which he must transfer funds, the amount of the payment and the generated QR code for payment. As soon as the address has been generated, a countdown starts during which the Buyer can make a payment (60 minutes). If the funds were not received within the specified period of time, the payment is considered expired, it is necessary to return back to the Seller's website and repeat the request. The buyer can go back to the choice of currencies, but if the funds were sent to 1 of the generated addresses, the Merchant begins to track the process of receiving them through the network and currency selection becomes unavailable.
Payment waiting page. As soon as information about an incoming transaction to the specified address appears in Merchant, the timer stops and the loader appears — the required number of confirmations is expected for the successful completion of the payment.
Successful payment page. As soon as the required number of confirmations has been received, the payment is considered successfully completed, the funds are credited to the specified address. The Buyer is redirected back to the Seller's website, the Seller is notified of the successful payment by the link specified in the personal account.
The surcharge page. If the Buyer has sent an amount that is insufficient for the successful completion of the payment, it will be credited to the specified address, and the remaining part to pay will be displayed on the surcharge page. The payment waiting timer starts again, 23 hours are allotted for depositing the remaining amount. If the payment has not been closed within the specified time, it is considered expired.
Expired payment page. If the Buyer has not deposited funds to the specified address within the specified time, the payment receives the expired status, and the Buyer sees the corresponding page with information that the address issued to him is no longer valid. The page also displays the Seller's contact details specified in the personal account and a button to return to the Seller's website.
If the funds were sent, but they were not received by Merchant within the specified period of time and the payment is considered expired, the Buyer must contact the Seller directly via specified contacts.
We strongly recommend posting information on the Seller's website about the time allotted for the transfer of funds in order to avoid delays in the generated payments.
All funds transferred by the Buyer are credited to the Seller's balance in the Merchant's personal account in the corresponding cryptocurrencies. The seller can withdraw funds to his cryptocurrency wallet or exchange them on the Cryptex exchange for fiat funds and withdraw them in any other ways presented.
The Buyer solves the issues related to the refund directly through the Seller's website and through the contacts specified in the Merchant's personal account.
Possible payment statuses
If no payment has been made, the payment status is Created.
If there are transactions unconfirmed by the network on the way, the status changes to In progress.
If there are confirmed payments, there are no payments in transit, but the amount is insufficient, Extra pay status will be shown. When this status is shown, the time for extra payment is extended to 24 hours.
If there are enough confirmed payments, the status changes to Closed.
If, after the time allowed for payment, no sufficient amount has been received to close the payment, the status will change to Expired.
Description of API requests
1. Creating a payment
POST https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/
Request body
Param | Type | Description |
|---|---|---|
shop* | string($uuid) | Store key assigned on Cryptex platform |
currency* | string | Currency (fiat) in which the payment is created (currently USD only) |
amount* | string($decimal) | Payment amount in a certain currency |
order_id* | string(pattern: ^[\w-]{1,30}$) | Order ID in the store |
details | string | Further information |
* — required fields
Answer
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | ID of the created payment |
shop | string($uuid) | Store key assigned on Cryptex platform |
amount | string($decimal) | Payment amount in currency currency |
order_id | string(pattern: ^[\w-]{1,30}$) | Order ID in the store |
details | string | Further information |
Example
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": "98eaf08f-374d-40ee-92e7-4754f6a5bd48",
"amount": "664.000",
"details": "string",
"order_id": "jajf9999djd"
}
2. Getting detailed information about the payment
GET https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/{payment_id}
Parameters
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Payment ID |
Answer
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | ID of the created payment |
shop | string($uuid) | Information about the store |
order_id | string(pattern: ^[\w-]{1,30}$) | Order ID in the store |
status | string | Payment status |
amount_usd | string | The amount of the payment in fiat when creating |
amount_crypto | number | The amount of payment in cryptocurrency, based on the exchange rate |
amount_crypto_paid | number | The amount in cryptocurrency paid and confirmed by the payment network |
amount_crypto_remaining | number | The amount in cryptocurrency that needs to be paid |
details | object | Information about the payment currency, address and exchange rate |
deposits | array of objects | Transaction information: txid, amount, status and number of network confirmations |
time_to_expire | number | Time to payment expiration in seconds |
created_at | string($date-time) | Date of creation |
payment_time | object | Time allotted for payment, in minutes |
Example
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": {
"name": "my shop",
"success_url": "https://example.com",
"shop_url": "https://example.com",
"accepted_currencies": [
{
"name": "LTC",
"full_name": "Litecoin",
"logo": null,
"deposit_time": 10
},
{
"name": "BTC",
"full_name": "Bitcoin",
"logo": "https://merchant.ctuptex.net/api/v2/merchant/merchant-currency/currency_logos/some_logo.png",
"deposit_time": 40
}
],
"contacts": [
{
"contact_type": "Email",
"contact": "abc@mail.com"
},
{
"contact_type": "Telegram",
"contact": "@some"
},
{
"contact_type": "Jabber",
"contact": "some_jid"
}
]
},
"order_id": "jajf9999djd",
"status": "Created",
"amount_usd": "664.000",
"amount_crypto": 2.73251029,
"amount_crypto_paid": 2.5,
"amount_crypto_remaining": 0.23251029,
"details": {
"name": "LTC",
"full_name": "Litecoin",
"address": "08jwiodkjvoiwdj0",
"qr_code": null,
"course": "243.00"
},
"deposits": [
{
"amount": "2.50000000",
"status": "Closed",
"txid": null,
"confirmations": 0
}
],
"withdrawal": null,
"time_to_expire": 0,
"created_at": "2021-12-10T12:53:18.098141+03:00",
"payment_time": 60
}
3. Generating a crypto address for a payment
POST https://merchant.cryptex.net/api/v2/merchant/merchant-invoices/{payment_id}/get_address/
Parameters
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Payment ID |
Request body
Param | Type | Description |
|---|---|---|
currency | string | The letter code of the currency from the list of possible cryptocurrency payments |
Answer
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | ID of the created payment |
shop | string($uuid) | Information about the store |
order_id | string(pattern: ^[\w-]{1,30}$) | Order ID in the store |
status | string | Payment status |
amount_usd | string | The amount of the payment in fiat when creating |
amount_crypto | number | The amount of payment in cryptocurrency, based on the exchange rate |
amount_crypto_paid | number | The amount in cryptocurrency paid and confirmed by the payment network |
amount_crypto_remaining | number | The amount in cryptocurrency that needs to be paid |
details | object | Information about the payment currency, address and exchange rate |
deposits | array of objects | Transaction information: txid, amount, status and number of network confirmations |
time_to_expire | number | Time to payment expiration in seconds |
created_at | string($date-time) | Date of creation |
payment_time | object | Time allotted for payment, in minutes |
Example
{
"payment_id": "a725c5fe-5fb4-4e6f-805a-187d79d861f5",
"shop": {
"name": "my shop",
"success_url": "https://example.com",
"shop_url": "https://example.com",
"accepted_currencies": [
{
"name": "LTC",
"full_name": "Litecoin",
"logo": null,
"deposit_time": 10
},
{
"name": "BTC",
"full_name": "Bitcoin",
"logo": "https://merchant.cryptex.net/api/v2/merchant/merchant-currency/currency_logos/some_logo.png",
"deposit_time": 40
}
],
"contacts": [
{
"contact_type": "Email",
"contact": "abc@mail.com"
},
{
"contact_type": "Telegram",
"contact": "@some"
},
{
"contact_type": "Jabber",
"contact": "some_jid"
}
]
},
"order_id": "jajf9999djd",
"status": "Created",
"amount_usd": "664.000",
"amount_crypto": 2.73251029,
"amount_crypto_paid": 2.5,
"amount_crypto_remaining": 0.23251029,
"details": {
"name": "LTC",
"full_name": "Litecoin",
"address": "08jwiodkjvoiwdj0",
"qr_code": null,
"course": "243.00"
},
"deposits": [
{
"amount": "2.50000000",
"status": "Closed",
"txid": null,
"confirmations": 0
}
],
"withdrawal": null,
"time_to_expire": 0,
"created_at": "2021-12-10T12:53:18.098141+03:00",
"payment_time": 60
}
Hook
After successful receipt of payment from the client, a POST request with detailed information about the payment will be sent to the webhook_success_url of the store.
Request body
Param | Type | Description |
|---|---|---|
payment_id | string($uuid) | Payment ID |
orderId | string | Order ID in the store |
status | string | Payment status |
currency | string | The letter code of the currency from the list of possible cryptocurrency payments |
amount | string($decimal) | Payment amount in cryptocurrency |
amountUsd | string($decimal) | Payment amount in fiat |
rate | string($uuid) | Payment acceptance rate |
createdAt | timestamp | Payment creation date |
closedAt | timestamo | Payment closing date |
IMPORTANT! After receiving the hook, you need to request payment information via /api/v2/merchant/merchant-invoices/{payment_id}, because the hook request can be forged!