Cryptocurrency invoice
To connect to the cryptocurrency account and payways to a shop, you need to contact the supervising manager or support@qostiq.com.
Make sure that your shop is activated and configured to work via the API: shop ID is received, interaction URL is specified, secret key is generated and IP addresses of your services are specified. Limits of payways and the payway name are specified in the personal account — shop settings — payment methods / withdrawal directions.
Scheme of work with cryptocurrency payments
- The shop makes a request to create and receive an up-to-date cryptocurrency address specifying the blockchain and payment currency (
paywayparameter) for transfers from the client, which receives the response in thedata.addressparameter. - The shop displays to the customer the address received in the parameter
data.address. - The client makes a cryptocurrency transfer in the blockchain and currency corresponding to the
paywayparameter to the specifieddata.address. - The Qostiq system sends the merchant notifications to the URL used for cryptocurrency transactions with the payment status. Funds transferred by the user and received by the recipient (in the recipient's currency and network), minus the Qostiq service fee, are credited to the shop's balance.
- The shop processes the notification and provides the customer with the service.
Attention! It is recommended to get the current address before each client payment, as a previously created address can be blocked. Payments made to a blocked address will not be credited to the shop balance.
Attention! Payments that do not fit the minimum or maximum amount specified in the payway settings will not be credited to the shop.
Invoice: address create [/crypto/shop_address/create]
URL: https://core.qostiq.com/crypto/shop_address/create
Method: POST
Mandatory parameters: client, now, payway, shop_id
Description
This request returns the cryptocurrency address (data.address) to which the client transfers funds.
Attention! It is recommended to get the current address before each deposit since a previously generated address may be blocked. Payments made to a blocked address will not be credited to the shop balance.
The response parameter data.cross_chains indicates all available blockchains and currencies for the given address in which a payment can be made.
Attention! The transaction to the address must be in both the currency and the network specified in the response parameter data.cross_chains. For example, "cross_chains": {"BSC":["BNB","USDT"], "Ethereum":["USDT","ETH"]} means that you can send a USDT token or ETH currency in Ethereum network, or USDT or BNB currency in Binance Smart Chain network. Transactions sent in a different currency or in a different blockchain will not be credited to the shop.
Example request:
{
"client": "client@example.com",
"now": 1655730715,
"payway": "usdt_bep20",
"shop_id": 6,
"sign": "8bcbc318875fed556e78072a12b516dba00f6c5014ae13ed6c6163764c22f8cb"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
client | Client for which the address is generated (recommended to use the client's email) | String | "client@example.com" |
now | request time, in the format unixtimestamp | Integer | 1655730715 |
payway | Payment direction, specifies blockchain and payment currency | String | "usdt_bep20" |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "214984e6277a5a2f95d9eed15d7722f427c40559b02fdb3f6399e2f845683d11" |
Example response:
{
"data": {
"address": "0x685f0875ea0a55fd3c355f1f9a850a644a71d626",
"blockchain": "BSC",
"cross_chains": {
"BSC": ["BNB", "USDT"],
"Ethereum": ["USDT", "ETH"],
"Polygon": ["MATIC"]
},
"currency": "BNB"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
data.address — the address generated for the specified client to which the client will make a payment;
data.blockchain — the blockchain in which the address was generated in accordance with "payway";
data.cross_chains — the array of blockchains and currencies for a given address in which payments can be made;
data.currency — the currency in which the address was generated in accordance with "payway".
Invoice: notification after payment [/crypto_invoice/callback]
Method: POST, Content-Type=application/json
After the customer has paid to the formed address, the Qostiq system sends a notification to the URL crypto interaction specified in the settings.
Notifications are sent from IP addresses:
- 34.90.243.164
- 34.147.48.238
- 34.90.176.128
- 34.90.34.134
- 35.242.192.50
Attention! When receiving a notification, be sure to check: transaction number on the Qostiq system — payment_id, to avoid duplicate payments check the uniqueness of the received payment_id (as for one payment multiple notifications may be sent); signature — sign; type of operation — callback_type; transaction status — status; client who owns the payment address — client.
Example notification:
{
"additional_info": {},
"address": "0x81ededbaf330af77567d7ae71a52c8eb602140b0",
"callback_type": "crypto_invoice",
"client": "client@example.com",
"client_price": "0.000200000000000000",
"created": "2022-06-22 09:19:06",
"description": null,
"payment_id": 34,
"payway": "bnb_bep20",
"processed": "2022-06-22 09:19:16",
"ps_currency": "BNB",
"ps_data": {
"ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07",
"transaction_hash": "0x8cec449fd6ebbe34c78987a903a92a8a2e07d499d8851c22cc197d141e41c96c"
},
"shop_amount": "0.000200000000000000",
"shop_currency": "BNB",
"shop_id": 6,
"shop_order_id": null,
"shop_refund": "0.000194000000000000",
"sign": "f8ec782aa4d1332532cc7ac5364ef979f593079505529d895e1f2c4a7cd0e024",
"status": "success"
}
Where,
additional_info — additional fields required to create a payment;
address — address where the payment was made;
callback_type — type of transaction for which the notification came, "crypto_invoice" for a payment;
client — client for which the payment was made; was specified in the create address request;
client_price — the amount paid by the client in the currency of the payment system;
created — date and time when the payment was created;
processed — date and time of payment status change (success or rejection);
description — payment description;
payment_id — unique payment identifier in the Qostiq system;
payway — Qostiq payment direction through which the user paid;
ps_currency — currency of the payment direction through which the user paid;
ps_data.ps_payer_account — address from which the payment was made;
ps_data.transaction_hash — payment hash in the blockchain;
shop_amount — amount of the created payment, in the currency of the payment;
shop_currency — transaction currency;
shop_id — unique identifier of the store where payment is made;
shop_order_id — not used on push payments;
shop_refund — the amount of credit to the balance of the shop, in the currency of the account;
status — transaction status;
sign — signature.
To avoid duplicate payments, when you receive a callback, you must always check the uniqueness of the received payment_id, because for one payment multiple notifications can be sent.
Example of a string to generate a signature:
{}:0x81ededbaf330af77567d7ae71a52c8eb602140b0:crypto_invoice:client@example.com:0.000200000000000000:2022-06-22 09:19:0:34:bnb_bep20:2022-06-22 09:19:16:BNB:{}:0.000200000000000000:BNB:6:0.000194000000000000:successTestkey1
The signature is formed using the same algorithm as for all requests, but all parameters whose value is not null and not an empty string are involved in forming the signature.
If the notification is received and processed correctly, it is necessary to return http status 200 and the message body OK. Otherwise notifications will be sent repeatedly, at increasing intervals, a total of 25 attempts, the last at the end of the day.
Invoice: status request [/crypto/invoice/status]
URL: https://core.qostiq.com/crypto/invoice/status
Method: POST
Mandatory parameters: invoice_id, now, shop_id
This request allows you to find out the current invoice status using the transaction number that comes in the notification as a parameter payment_id.
Example request:
{
"invoice_id": 183,
"now": 1655802380,
"shop_id": 6,
"sign": "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
now | request time, in the format unixtimestamp | Integer | 1655802380 |
invoice_id | unique payment number in the Qostiq system, specified in the callback in the parameter payment_id | Integer | 183 |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "bc21703c682f0b9f53d4b554cfd55d8a25fc75c0e386fe589033aa0f49f35d07" |
Example response:
{
"data": {
"additional_info": {},
"address": "0xc8717eea12a90853c854f1df77d36180ce7f99e3",
"client": "TestClient_denisov",
"client_price": "2.0",
"created": "2022-07-18 07:13:06",
"description": null,
"payment_id": 183,
"payway": "usdt_bep20",
"processed": "2022-07-18 07:13:26",
"ps_currency": "USDT",
"ps_data": {
"ps_payer_account": "0xf8227aa7af9b5166af69581c703a4398387b2b07",
"refunded_address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
"transaction_hash": "0x764274c5548d0ace9eaeed1a0209307a147a78f399a36deacc2857538c95be15"
},
"shop_amount": "2.0",
"shop_currency": "USDT",
"shop_id": 6,
"shop_order_id": null,
"shop_refund": "1.96",
"status": 7
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
additional_info — additional fields required to create a payment;
address — address where the payment was made;
client — client for which the payment was made; was specified in the create address request;
client_price — the amount paid by the client in the currency of the payment system;
created — date and time when the payment was created;
processed — date and time of payment status change (success or rejection);
description — payment description;
payment_id — unique payment identifier in the Qostiq system;
payway — Qostiq payment direction through which the user paid;
ps_currency — currency of the payment direction through which the user paid;
ps_data.ps_payer_account — address from which the payment was made;
ps_data.refunded_address — address to which the refund is done (in case the payment was refunded);
ps_data.transaction_hash — payment hash in the blockchain;
shop_amount — amount of the created payment, in the currency of the payment;
shop_currency — transaction currency;
shop_id — unique identifier of the store where payment is made;
shop_order_id — not used on push payments;
shop_refund — the amount of credit to the balance of the shop, in the currency of the account;
status — transaction status;
sign — signature.
Attention! The status request should be done no more often than once every 10 seconds.
Invoice statuses [/invoice/status]
| Status | Value | Description | Final? | Action |
|---|---|---|---|---|
waiting | 1 | waiting for the callback with final status | No, you can't provide the service | The operation was created in Qostiq, wait for the final status |
success | 2 | final successful status | Yes, it is possible to provide the service | To provide a service |
rejected | 3 | final unsuccessful status | Yes, you can't provide the service | Cancel the payment (if it was previously created) |
captured | 4 | funds are temporarily held | No, you can't provide the service | Don't provide the service, funds cannot be credited to the shop balance, please contact support |
risky | 5 | risky transaction, payment received did not pass risk level check | No, you can't provide the service | Payment does not correspond to the security settings, you need to refund the payment with API request /crypto/invoice/refund/create, from your personal account or contact support |
refunding | 6 | invoice in the process of return | No, you can't provide the service | Refund in progress |
refunded | 7 | returned to the payer | Yes, you can't provide the service | Payment was refunded to the payer |
Invoice: pre-calculation refund [/crypto/invoice/refund/try]
URL: https://core.qostiq.com/crypto/invoice/refund/try
Method: POST
Mandatory parameters: address, invoice_id, now, shop_id
This request specifies the possibility of returning a risky payment and shows information about the amount and currency of the refund.
Refunds are made for the amount of the transfer received client_price, minus the blockchain commission for the transfer.
Attention!
To make a refund, the store must clarify with the customer the address to which the customer will receive the refund, as the address from which the payment was made is often not the personal address of the customer. Refunds are not allowed to Qostiq system addresses.
Example request:
{
"address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
"invoice_id": 134,
"now": "1657543247",
"shop_id": 6,
"sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
address | Address to which the refund will be performed (need to check with the client) | String | "0xf8227AA7aF9B5166AF69581C703A4398387B2B07" |
now | request time, in the format unixtimestamp | Integer | 1655730715 |
invoice_id | unique payment number in the Qostiq system, specified in the payment_id parameter in the callback | Integer | 134 |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an" |
Example response:
{
"data": {
"blockchain": "BSC",
"shop_currency": "BNB",
"shop_write_off": 0.00198,
"ps_currency": "BNB",
"ps_refund": "0.002"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
data.blockchain — blockchain in which the refund will be performed;
data.shop_currency — the currency of the shop's debit on returns;
data.shop_write_off — the amount written off from the shop to refund;
data.ps_currency — refund currency;
data.ps_refund — amount sent for refund.
Invoice: refund creation [/crypto/invoice/refund/create]
URL: https://core.qostiq.com/crypto/invoice/refund/create
Method: POST
Mandatory parameters: address, invoice_id, now, shop_id
This request specifies the possibility of refunding a risky invoice and shows information about the amount and currency of the return.
Refunds are made for the amount of the transfer received client_price, minus the blockchain commission for the transfer.
Attention!
To make a refund, the store must clarify with the customer the address to which the customer will receive the refund, as the address from which the payment was made is often not the personal address of the customer. Refunds are not allowed to Qostiq system addresses.
Example request:
{
"address": "0xf8227AA7aF9B5166AF69581C703A4398387B2B07",
"invoice_id": 134,
"now": "1657543247",
"shop_id": 6,
"sign": "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
address | Address to which the refund will be performed (need to check with the client) | String | "0xf8227AA7aF9B5166AF69581C703A4398387B2B07" |
now | request time, in the format unixtimestamp | Integer | 1655730715 |
invoice_id | unique payment number in the Qostiq system, specified in the payment_id parameter in the callback | Integer | 134 |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "b13a78dd63hdjdg8jn92ndndksvjhpxnwidu9293bnc729djucbe93ncb6900an" |
Example response:
{
"data": {
"Id": "41",
"blockchain": "BSC",
"shop_currency": "BNB",
"shop_write_off": 0.00198,
"ps_currency": "BNB",
"ps_refund": "0.002"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Refund is successful if a unique return number data.id was received in response to the return creation request.
Where,
data.id — refund transaction number on the Qostiq system;
data.blockchain — blockchain in which the refund will be performed;
data.shop_currency — the currency of the shop's debit on returns;
data.shop_write_off — the amount written off from the shop to refund;
data.ps_currency — refund currency;
data.ps_refund — amount sent for refund.