Cryptocurrency payments with Qostiq Wallet
Crypto bill - This method allows you to bill cryptocurrency for payment using cryptocurrency balance from Qostiq wallets.
Pre-calculation of payment from the Qostiq Wallet [/crypto/bill/try]
URL: https://core.qostiq.com/crypto/bill/try
Method: POST
Mandatory parameters: now, payer_currency, shop_amount, shop_currency, shop_id, shop_order_id
This request is optional to create an invoice for a cryptocurrency payment from your Qostiq wallet. The request clarifies the possibility of creating a payment with the specified parameters, returns the amounts debited from the customer's wallet and received by the store after calculating the commission or conversion.
Example request:
{
"now": 1666266703,
"payer_currency": "USDT",
"shop_amount": "1",
"shop_currency": "USDT",
"shop_id": 13,
"shop_order_id": "test_bill_01",
"sign": "af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
now | request time, in the format unixtimestamp | Integer | 1666266703 |
payer_currency | the currency of debiting the client's wallet | String | "USDT" |
shop_amount | transaction amount in cryptocurrency | String or number, see "Specifying the operation amount" for details | "1.00000001" or 1.00000001 |
shop_currency | the currency of receipt of funds to the balance of the shop | String | "USDT" |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
shop_order_id | payment identifier on the shop side | String | "test_bill_01" |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "af6c9c845d855013237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" |
Example response:
{
"data": {
"payee_currency": "USDT",
"payer_fee": "0.0",
"payer_price": "1.0",
"shop_amount": "1.0",
"shop_currency": "USDT",
"shop_refund": "0.97"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
data.payee_currency — currency of debiting the payment amount from the client;
data.payer_fee — the amount of commission paid by the client on the transaction in payee_currency;
data.payer_price — the amount of debit from the balance of the client's wallet for the operation in payee_currency;
data.shop_amount — invoiced amount in currency shop_currency;
data.shop_currency — currency of the payment amount crediting to the shop;
data.shop_refund — the amount of credit to the balance of the shop in currency shop_currency.
Creating a payment from Qostiq Wallet [/crypto/bill/create]
URL: https://core.qostiq.com/crypto/bill/create
Method: POST
Mandatory parameters: now, payer_currency, shop_amount, shop_currency, shop_id, shop_order_id
This request creates a payment that the client can pay using the Qostiq Wallet.
The uniqueness of shop_order_id is checked depending on the shop settings, we recommend enabling this function and passing a unique value for your store to avoid duplicate billing for payment.
The request can pass additional parameters, such as payer_account — email/purse number of the payer's account in the Qostiq system.
Example request:
{
"now": 1666687437,
"payer_currency": "USDT",
"shop_amount": "1",
"shop_currency": "USDT",
"shop_id": 13,
"shop_order_id": "test_bill_01",
"sign": "8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
now | request time, in the format unixtimestamp | Integer | 1666687437 |
payer_currency | the currency of debiting the client's wallet | String | "USDT" |
shop_amount | transaction amount in cryptocurrency | String or number, see "Specifying the operation amount" for details | "1.00000001" or 1.00000001 |
shop_currency | the currency of receipt of funds to the balance of the shop | String | "USDT" |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
shop_order_id | payment identifier on the shop side | String | "test_bill_01" |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "8j2b0fn48dbsklhdhf8jd4hf80d0f91fe1569f9ee6e6125332714c322f744" |
Also, additional parameters can be passed in the request; they are not involved in signature formation.
| Parameter | Description | Format | Example |
|---|---|---|---|
description | billing description | String | "test bill description" |
payer_account | email or number of the payer's wallet in the Qostiq system to which the invoice will be billed | String or integer | "client@shop.com" or 301494711279 |
failed_url | URL to which the payer will be redirected after rejecting the invoice | String | "https://shop.com/failed" |
success_url | URL to which the payer will be redirected after successful payment of the bill | String | "https://shop.com/success" |
crypto_callback_url | URL address where notification of the final status of the invoice will be sent | String | "https://shop.com/crypto_callback_url" |
lifetime | bill validity time, in minutes (default is 90 minutes) | String | "90" |
Important! Success_URL, Fail_URL, Crypto_callback_url specified in the shop settings have a higher priority than those passed in the request, so you must remove them from the store settings.
Example response:
{
"data": {
"created": "Tue, 25 Oct 2022 08:43:57 GMT",
"id": 78,
"lifetime": 90,
"payer_account": null,
"payer_currency": "USDT",
"payer_price": "1.0",
"shop_amount": "1.0",
"shop_currency": "USDT",
"shop_id": 13,
"shop_order_id": "test_bill_01",
"shop_refund": "0.97",
"url": "https://wallet.qostiq.com/ru/crypto/bill/pay/950db2bd333840b9b4b2360baccbfc2f"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
created — date of payment creation;
id — unique bill transaction number on the side of the Qostiq system;
lifetime — payment lifetime in minutes;
payer_account — the number of the wallet to which the payment is linked;
payer_currency — the currency of the bill payment from the client's wallet;
payer_price — the amount of the bill payment from the client's wallet;
shop_amount — the amount of the billed payment;
shop_currency — the currency in which the transaction amount is credited to the shop;
shop_id — shop identifier in the Qostiq system;
shop_order_id — transaction number on the shop side;
shop_refund — the amount of credit to the balance of the shop in currency shop_currency;
url — URL to redirect the client to pay the payment.
Creating a Bill v.2 with free payment option [/crypto/bill/create/v2]
Bill v.2 — new method allows you to issue bills for payment using Qostiq wallets in 2 variants:
-
fixed amount — you decide how much should your customer pay for the services provided (if
amountis passed); -
free amount — your customer is allowed to choose an amount to be credited to the shop (if
amountis not passed).
URL: https://core.qostiq.com/crypto/bill/create/v2
Method: POST
Mandatory parameters: currency, now, shop_id, shop_order_id
The uniqueness of shop_order_id is checked depending on the shop settings, it is recommended to enable this feature and pass a unique value for your shop to avoid duplicate billing.
The request can also pass additional parameters, for example description — bill description, or email — email of the payer's wallet in the Qostiq system.
Example request:
{
"currency": "USDT",
"now": 1687520474,
"shop_id": 6,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"sign": "3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
now | request time, in the format unixtimestamp | Integer | 1687520474 |
currency | currency of withdrawal of funds from the client's wallet | String | "USDT" |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
shop_order_id | payment identifier on the shop side | String | "dc5a286e-6c5e-43e8-8c68-926fa15d09ec" |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "3cbafdf3c4abe41969a994c28e3472cff1bd4711e4ab58f142b88655fef6cf27" |
Also, additional parameters can be passed in the request; they are not involved in signature formation.
| Parameter | Description | Format | Example |
|---|---|---|---|
amount | transaction amount in cryptocurrency | String or number, see "Specifying the operation amount" for details | "1.00000001" or 1.00000001 |
description | billing description | String | "test bill description" |
failed_url | URL to which the payer will be redirected after rejecting the invoice | String | "https://shop.com/failed" |
success_url | URL to which the payer will be redirected after successful payment of the bill | String | "https://shop.com/success" |
crypto_callback_url | URL address where notification of the final status of the invoice will be sent | String | "https://shop.com/crypto_callback_url" |
lifetime | bill validity time, in minutes (default is 90 minutes) | String | "90" |
email | payer's wallet email in the Qostiq system | String | "example@mail.com" |
lang | payment page language (available: English — "en", Polish — "pl", Russian — "ru", Ukrainian — "uk") | String | "en" |
Important! Success_URL, Fail_URL, Crypto_callback_url specified in the shop settings have a higher priority than those passed in the request, so you must remove them from the store settings.
Example response:
{
"data": {
"created": "Tue, 25 Oct 2022 08:43:57 GMT",
"id": 1446,
"lifetime": 90,
"payer_account": null,
"payer_currency": "USDT",
"payer_price": null,
"shop_amount": null,
"shop_currency": "USDT",
"shop_id": 6,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"shop_refund": null,
"url": "https://wallet.qostiq.com/ru/crypto/bill/pay/950db2bd333840b9b4b2360baccbfc2f"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
created — date of payment creation;
id — unique bill transaction number on the side of the Qostiq system;
lifetime — payment lifetime in minutes;
payer_account — the number of the wallet to which the payment is linked;
payer_currency — the currency of the bill payment from the client's wallet;
payer_price — the amount of the bill payment from the client's wallet;
shop_amount — the amount of the billed payment;
shop_currency — the currency in which the transaction amount is credited to the shop;
shop_id — shop identifier in the Qostiq system;
shop_order_id — transaction number on the shop side;
shop_refund — the amount of credit to the balance of the shop in currency shop_currency;
url — URL to redirect the client to pay the payment.
Requesting payment status from Qostiq Wallet [/crypto/bill/shop_order_status]
URL: https://core.qostiq.com/crypto/bill/shop_order_status
Method: POST
Mandatory parameters: now, shop_id, shop_order_id
This request is not mandatory. The request allows you to find out the current status of the invoice.
Example request:
{
"now": 1666688539,
"shop_id": 13,
"shop_order_id": "test_bill_01",
"sign": "hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
now | request time, in the format unixtimestamp | Integer | 1666688539 |
shop_id | shop identifier in the Qostiq system | Integer | 6 |
shop_order_id | payment identifier on the shop side | String | "test_bill_01" |
sign | signature, see Signature formation rules for crypto operations (sign) | String | "hsd8dhf88kdpc8sn9c237f25sdhf80d0f91fe1569f9ee6e6125332714c322f744" |
Example response:
{
"data": {
"created": "2022-10-25 08:43:57",
"description": "",
"is_unique": false,
"payer_currency": "USDT",
"payer_price": "1.0",
"payment_id": 78,
"processed": null,
"ps_data": {
"ps_payer_account": null
},
"shop_amount": "1.0",
"shop_currency": "1.0",
"shop_id": "1.0",
"shop_order_id": "1.0",
"shop_refund": "0.97",
"status": 1
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
created — payment creation date;
description — description of the payment;
is_unique — the uniqueness of the payment number on the shop side — shop_order_id;
payer_currency — currency of debiting the payment amount payer_price from the customer's wallet;
payer_price — the amount of debit from the client's wallet in currency payer_currency;
payment_id — unique transaction number on the Qostiq side, returned in the id parameter to the request to create a payment /crypto/bill/create;
processed — the time of final payment status;
ps_data.ps_payer_account — payer's wallet number;
shop_amount — the amount of the billed payment in the currency shop_currency;
shop_currency — payment currency;
shop_id — shop identifier in the Qostiq system;
shop_order_id — shop's transaction number;
shop_refund — the amount of payment credit to the shop in currency shop_currency;
status — payment status, see Payment statuses for details.
Attention! The status query should be done no more often than once every 10 seconds.
If shop_order_id is not unique for bill transactions within the shop, the response contains "is_unique":false and the method returns information on the last Bill created.
The uniqueness of shop_order_id is checked depending on the shop settings, we recommend enabling this function and passing a unique value for your store to avoid duplicate invoicing for payment.
Notification after payment from Qostiq Wallet [/crypto/bill/callback]
Method: POST, Content-Type=application/json
After the payment or rejection of the invoice by the client, the Qostiq system sends a notification to the shop to the specified crypto interaction URL or to the passed crypto_callback_url in the payment creation request.
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; signature — sign; type of operation — callback_type; transaction status — status.
Example notification:
{
"callback_type": "crypto_bill",
"client_price": "0.1",
"created": "2022-10-21 13:25:30",
"description": null,
"payment_id": 71,
"payway": "qostiq_usdt",
"processed": "2022-10-21 13:25:53",
"ps_currency": "USDT",
"ps_data": {
"ps_payer_account": "31645670659"
},
"shop_amount": "0.1",
"shop_currency": "USDT",
"shop_id": 59,
"shop_order_id": "16384496",
"shop_refund": "0.097",
"sign": "5d66740075e54cb90a1ed9e4352a957b2a7cf4955e40638e5df4a54c8f89d780",
"status": "success"
}
Where,
callback_type — type of operation for which the notification came, "crypto_bill" for a payment from the Qostiq wallet;
client_price — the amount paid by the customer in the currency "ps_currency";
created — date and time when the payment was created;
processed — date and time of the final payment status (success or rejected);
description — payment description;
payment_id — unique transaction number on the Qostiq side, returned in the id parameter to the request to create a payment /crypto/bill/create;
payway — the payment direction in the Qostiq system, through which the user paid;
ps_currency — currency of the payment direction through which the user paid;
ps_data.ps_payer_account — wallet number of the customer who paid or canceled the invoice;
shop_amount — the amount of the created invoice, in the currency of payment;
shop_currency — payment currency;
shop_id — shop identifier in the Qostiq system;
shop_order_id — payment identifier on the shop side;
shop_refund — the amount of payment credit to the shop in currency shop_currency;
status — payment status, see Payment statuses for details;
sign — signature.
The signature is formed using the same algorithm as all operations, but all parameters whose value is not null and not an empty string are involved in forming the signature.
Example of a string to generate a signature:
crypto_bill:0.1:2022-10-21 13:25:30:71:qostiq_usdt:2022-10-21 13:25:53:USDT:{"ps_payer_account": "31645670659"}:0.1:USDT:59:16384496:0.097:successTestkey1
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.
Payment statuses from the Qostiq wallet [/crypto/bill/status]
| Status | Value | Description | Final? |
|---|---|---|---|
| 1 | waiting | Bill created, awaiting payment | No |
| 2 | success — value comes in the callback | The bill is paid | Yes, funds are credited to the balance of the shop |
| 3 | rejected — value comes in the callback | The customer canceled the bill | Yes, funds are not credited to the balance of the shop |
| 4 | expired | The time limit for possible payment of the bill has expired | Yes, funds are not credited to the balance of the shop |