Operations with Qostiq wallet
Creating a bill [/bill/create]
Bill - This method allows to create bills for payment using Qostiq wallets.
URL: https://core.qostiq.com/bill/create
Method: POST
Mandatory parameters: shop_amount, shop_currency, shop_id, shop_order_id, payer_currency
Uniqueness of shop_order_id is checked depending on the shop settings, we recommend to use this feature and pass the unique value to your shop to avoid duplicate billing.
The request can pass additional parameters, for example, description – bill description, or payer_account – email/ID of the payer's wallet in Qostiq system.
Example of request:
{
"description": "Test Bill",
"payer_currency": 980,
"shop_amount": "23.15",
"shop_currency": 980,
"shop_id": "112",
"shop_order_id": 4239,
"sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575"
}
| Parameter | Description | Format | Example |
|---|---|---|---|
shop_id | shop ID in Qostiq system | Integer | 5 |
shop_amount | bill amount | Number (no more than 2 characters after the dot) | 1, 1.0, 1.00 or "1.00" |
shop_currency | bill currency (shop admission) | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro |
payer_currency | payer currency (write-off currency from the payer in Qostiq system, can be different from the shop currency) | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro |
sign | signature | String | "a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109" |
shop_order_id | bill ID on the shop's side | String | "h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92" |
description | bill description (optional) | String | "test bill" |
payer_account | email or ID of the payer's wallet in Qostiq system (optional) | String or integer | "support@qostiq.com" or 201494711279 |
Also, additional parameters can be passed in the request; they do not participate in signature formation.
| Parameter | Description | Format | Example |
|---|---|---|---|
failed_url | URL, to which the payer will be redirected after unsuccessful payment | String | "https://qostiq.com/failed" |
success_url | URL, to which the payer will be redirected after successful payment | String | "https://qostiq.com/success" |
callback_url | URL for notification of successful payment | String | "https://qostiq.com/callback_url_kvt" |
callback_rejected_url | URL for notification of unsuccessful payment | String | "https://qostiq.com/callback_rejected_url_kvt" |
lifetime | bill lifetime, in minutes | String | "43200" |
Important! Success URL, Fail URL, URL for notifications, URL Reject notifications that are listed in the shop settings have a higher priority than the ones in the request, so they have to be deleted from the shop settings.
Example of response:
{
"data": {
"created": "Wed, 06 Dec 2017 14:30:44 GMT",
"id": 25,
"lifetime": "43200",
"payer_account": null,
"payer_currency": 980,
"payer_price": 23.15,
"shop_amount": 23.15,
"shop_currency": 980,
"shop_id": 3,
"shop_order_id": 4239,
"shop_refund": 23.15,
"url": "https://wallet.qostiq.com/en/bill/pay/WtvoXPzcphd"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
| Parameter | Description |
|---|---|
data | info about the created bill |
id | unique bill ID in Qostiq system |
lifetime | bill lifetime, in minutes, by default: 43200 minutes |
payer_account | payer account (if passed in the request) |
payer_currency | currency in which the payer must pay the bill |
payer_price | amount to be paid by the payer to settle the bill |
shop_currency | bill currency (shop admission) |
shop_amount | bill amount (from the shop) |
shop_id | shop ID |
shop_order_id | bill ID on shop's side |
url | URL to which the user can be redirected to pay the bill |
Warning! When specifying payer_account, the bill will be created and linked to the user. The user will be able to view the list of unpaid bills in the personal profile and pay them. For the convenience of payment, you can redirect the user to url from the response request. It is necessary to redirect the user to url from the response, if payer_account was not passed.
Example of error while creating a bill:
{
"data": null,
"message": "invalid sign",
"error_code": 1,
"result": false
}
Where
| Parameter | Description |
|---|---|
message | error description |
error_code | error code |
Create a Qostiq bill [POST]
- Request (application/json)
{
"description": "Test Bill",
"payer_currency": 980,
"shop_amount": "23.15",
"shop_currency": 980,
"shop_id": "112",
"shop_order_id": 4239,
"sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575"
}
- Response 200 ()
{
"data":
{
"created": "Wed, 06 Dec 2017 14:35:43 GMT",
"id": 26,
"lifetime": 43200,
"payer_account": null,
"payer_currency": 980,
"payer_price": 23.15,
"shop_amount": 23.15,
"shop_currency": 980,
"shop_id": 3,
"shop_order_id": 4239,
"url": "https://wallet.qostiq.com/en/bill/pay/kdrNIrMtuhb"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Creating a Bill v.2 with free payment option [/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/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 pass additional parameters, for example, description – bill description, or email – payer's wallet email in Qostiq system.
Request example:
{
"currency": 840,
"shop_id": 6,
"now": 1687520474,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"sign": "771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87"
}
| Parameter | Description | Format | Example |
|---|---|---|---|
shop_id | your shop identifier in the Qostiq system | Integer | 6 |
currency | currency of the invoice (crediting to the store) | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro |
now | request time in timestamp format | Integer | 1687520474 |
sign | signature, see Signature formation rules (sign) | String | "771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87" |
shop_order_id | bill ID on the shop's side | String | "dc5a286e-6c5e-43e8-8c68-926fa15d09ec" |
Also, additional parameters can be passed in the request; they are not involved in signature formation.
| Parameter | Description | Format | Example |
|---|---|---|---|
amount | bill amount; if this parameter is present, the client will not be able to change the payment amount | Number (no more than 2 characters after the dot) | 1, 1.0, 1.00 or "1.00" |
email | payer's wallet email in Qostiq system | String | "example@mail.com" |
failed_url | URL to which the payer will be redirected after unsuccessful payment | String | "https://qostiq.com/failed" |
success_url | URL to which the payer will be redirected after successful payment | String | "https://qostiq.com/success" |
callback_url | URL for notification of successful payment | String | "https://qostiq.com/callback_url_kvt" |
callback_rejected_url | URL for notification of unsuccessful payment | String | "https://qostiq.com/callback_rejected_url_kvt" |
lifetime | bill lifetime for payment, in minutes (90 by default) | String | "43200" |
lang | payment page language (available: English "en", Polish "pl", Russian "ru", Ukrainian "uk") | String | "en" |
Important! Success URL, Fail URL, URL notifications, URL Reject notifications listed in the shop settings have a higher priority than those in the request, so they have to be deleted from the shop settings.
Response example:
{
"data": {
"created": "Fri, 23 Jun 2023 11:44:50 GMT",
"id": 1914,
"lifetime": "90",
"payer_account": null,
"payer_currency": 840,
"payer_price": null,
"shop_amount": null,
"shop_currency": 840,
"shop_id": 6,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"shop_refund": null,
"url": "https://wallet.qostiq.com/en/bill/pay/ba534fbd7bad42e09c47ce70c06b4886"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
| Parameter | Description |
|---|---|
data | info about the created bill |
id | unique bill identifier in the Qostiq system |
lifetime | bill lifetime for payment, in minutes, by default: 43200 minutes |
payer_account | payer account (if passed in the request) |
payer_currency | currency in which the payer must pay the bill |
payer_price | amount to be paid by the payer to settle the bill |
shop_currency | bill currency (shop admission) |
shop_amount | bill amount (from the shop) |
shop_id | shop identifier |
shop_order_id | bill ID on shop's side |
url | URL to which the user can be redirected to pay the bill |
Attention! If you specify email, the bill will be created and linked to the user for payment. The user will be able to view the list of unpaid bills in the personal profile and pay it. For the convenience of payment, you can redirect the user to url from the response. It is necessary to redirect the user to url from the response, if you did not pass email.
Example of bill error:
{
"data": null,
"message": "invalid sign",
"error_code": 10,
"result": false
}
Where
| Parameter | Description |
|---|---|
message | error description |
error_code | error code |
Create Qostiq Bill v.2 [POST]
- Request (application/json)
{
"currency": 840,
"shop_id": 6,
"now": 1687520474,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"sign": "771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87"
}
- Response 200 ()
{
"data": {
"created": "Fri, 23 Jun 2023 11:44:50 GMT",
"id": 1914,
"lifetime": 90,
"payer_account": null,
"payer_currency": 840,
"payer_price": null,
"shop_amount": null,
"shop_currency": 840,
"shop_id": 6,
"shop_order_id": "dc5a286e-6c5e-43e8-8c68-926fa15d09ec",
"shop_refund": null,
"url": "https://wallet.qostiq.com/en/bill/pay/ba534fbd7bad42e09c47ce70c06b4886"
},
"error_code": 0,
"message": "Ok",
"result": true
}
Bill status request [/bill/shop_order_status]
This method allows you to find out the current status of the payment made with the Qostiq wallet.
URL: https://core.qostiq.com/bill/shop_order_status
Method: POST
Mandatory parameters: now, shop_id, shop_order_id
Example of request:
{
"now": "2021-05-01 16:56:25.009469",
"shop_id": 1092,
"shop_order_id": "234234232323",
"sign": "b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976"
}
| Parameter | Description | Format | Example |
|---|---|---|---|
now | date of request | String | "2021-05-01 16:56:25.009469" |
shop_id | shop ID in Qostiq system | Integer | 1092 |
shop_order_id | bill ID on the side of your service | String | "234234232323" |
sign | signature | String | "b9b838e0b1baedcf7dd60711b1afab246c3496b5cc3433df0c5a2e2d07fea976" |
Example of response:
{
"data": {
"client_price": 1.16,
"created": "2020-10-20 14:01:28",
"description": "",
"is_unique": true,
"payment_id": 852095,
"payway": "qostiq_usd",
"processed": "2020-10-20 14:01:33",
"ps_currency": 980,
"ps_data": {
"ps_payer_account": "201538122124"
},
"shop_amount": 1.1,
"shop_currency": 980,
"shop_id": 1092,
"shop_order_id": "234234232323",
"shop_refund": 1.1,
"status": 2
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
| Parameter | Description |
|---|---|
client_price | payment amount |
created | date of creation |
description | bill description |
is_unique | payment ID uniqueness |
payment_id | payment ID in Qostiq system |
payway | payway |
processed | date of processing |
ps_currency | bill currency |
ps_data | additional data from the paysystem, such as payer account |
shop_amount | bill amount from the shop |
shop_currency | bill currency from the shop |
shop_id | shop ID in Qostiq system |
shop_order_id | bill ID on shop's side |
shop_refund | credited amount on the shop's balance, in bill's currency |
status | bill status |
Warning! Status request must be done no more often than once every 10 seconds.
If shop_order_id is not unique in the bill operations within the shop, the response will include "is_unique":false and the method will return the info about the last created bill.
Bill status request [POST]
- Request (application/json)
{
"now": "2021-05-01 16:56:25.009469",
"shop_id": "1092",
"shop_order_id": "234234232323",
"sign": "ad7fbe8df102bc70e28deddba8b45bb3f4e6cafdaa69ad1ecc0e8b1d4e770575"
}
- Response 200 ()
{
"data": {
"client_price": 1.16,
"created": "2020-10-20 14:01:28",
"description": "",
"is_unique": true,
"payment_id": 852095,
"payway": "qostiq_usd",
"processed": "2020-10-20 14:01:33",
"ps_currency": 980,
"ps_data": {
"ps_payer_account": "201538122124"
},
"shop_amount": 1.1,
"shop_currency": 980,
"shop_id": 1092,
"shop_order_id": "234234232323",
"shop_refund": 1.1,
"status": 2
},
"error_code": 0,
"message": "Ok",
"result": true
}
Bill operation status [/bill/status]
| Status | Value | Description | Final? |
|---|---|---|---|
| 1 | Waiting | Payment is pending user action | No |
| 2 | Paid | Payment is paid by the client | Yes |
| 3 | Canceled | Payment is cancelled by the client | Yes |
| 4 | Expired | Bill is expired | Yes |
Bill status request with non-unique shop_order_id [POST]
- Request (application/json)
{
"now": "2021-05-01 16:56:25.009469",
"shop_id": "112",
"shop_order_id": "123billtest",
"sign": "6fb934f7e00d205cb5ebb62117d9b74029d84c2ffc7c87fe5b38ac5196fecf02"
}
- Response 200 ()
{
"data": {
"client_price": 1.0,
"created": "2021-06-09 13:47:05",
"description": "",
"is_unique": false,
"payment_id": 19732961,
"payway": "qostiq_usd",
"processed": null,
"ps_currency": 980,
"ps_data": {
"ps_payer_account": "201538122124"
},
"shop_amount": 1.0,
"shop_currency": 980,
"shop_id": 1092,
"shop_order_id": "123billtest",
"shop_refund": 0.93,
"status": 4
},
"error_code": 0,
"message": "Ok",
"result": true
}
Preliminary calculation of the payout to the wallet: Transfer [/transfer/try]
Transfer/try. This method is not required to create a payout to the wallet. It returns additional info to create a transfer and preliminary calculations of fees and conversion.
URL: https://core.qostiq.com/transfer/try
Method: POST
Mandatory parameters: amount, amount_type, payee_currency, shop_currency, shop_id
Example of request:
{
"amount": 1.11,
"amount_type": "receive_amount",
"payee_currency": 978,
"shop_currency": 840,
"shop_id": 6,
"sign": "cea33ec0eeeef9866b01d51c7bbe55b4d3c3f2e18f681d7629940b816ff35a2b"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
amount | receive or write-off amount (depends on amount_type) | Number (no more than 2 characters after the dot) | 1.00 or 1 |
amount_type | type of the amount, possible options: receive_amount – amount to be received, writeoff_amount — amount to be written off the shop's balance | String | "receive_amount" or "writeoff_amount" |
payee_currency | receiving currency on the Qostiq account | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge |
shop_currency | write-off currency from the shop | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge |
shop_id | shop ID from which the payment is made | Integer | 5 |
sign | request signature | String | "cea33ec0eeeef9866b01d51c7bbe55b4d3c3f2e18f681d7629940b816ff35a2b" |
Example of response:
{
"data": {
"account_info_config": {
"payee_account": {
"comment": {
"en": "Enter Wallet Number or Email",
"ru": "Введите номер кошелька или email"
},
"example": "31557414711",
"label": {
"en": "Wallet Number or Email",
"ru": "Введите номер кошелька или email"
},
"regex": "^3[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$"
}
},
"info": {},
"payee_amount": 1.11,
"payee_currency": 978,
"shop_currency": 840,
"write_off_amount": 1.19
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
| Parameter | Description |
|---|---|
account_info_config.payee_account | information about the account, including a regular expression that the account must match |
payee_amount | amount to be received in payee_currency |
payee_currency | receiving currency for payee_amount |
shop_currency | write-off currency from the shop of write_off_amount |
write_off_amount | write-off amount from the shop in shop_currency |
Preliminary payout calculation [POST]
To show the request, change Production to Mock Server in the right window
- Request (application/json)
{
"amount": "1.11",
"amount_type": "receive_amount",
"payee_currency": "978",
"shop_currency": "840",
"shop_id": "6",
"sign": "cea33ec0eeeef9866b01d51c7bbe55b4d3c3f2e18f681d7629940b816ff35a2b"
}
- Response 200 ()
{
"data": {
"account_info_config": {
"payee_account": {
"comment": {
"en": "Enter Wallet Number or Email",
"ru": "Введите номер кошелька или email"
},
"example": "31557414711",
"label": {
"en": "Wallet Number or Email",
"ru": "Номер кошелька или email"
},
"regex": "^3[\\d]{10}$|^([a-zA-Z0-9_-]+\\.)*[a-zA-Z0-9_-]+@[a-zA-Z0-9_-]+(\\.[a-zA-Z0-9_-]+)*\\.[a-zA-Z]{2,6}$"
}
},
"info": {},
"payee_amount": 1.11,
"payee_currency": "978",
"shop_currency": "840",
"write_off_amount": 1.19
},
"error_code": 0,
"message": "Ok",
"result": true
}
Withdrawing funds to the wallet: Transfer [/transfer/create]
Transfer - The Transfers operation is used to withdraw funds from the shop to the personal account of the user in Qostiq currency.
URL: https://core.qostiq.com/transfer/create
Method: POST
Mandatory parameters: amount, amount_type, payee_account, payee_currency, shop_currency, shop_id, shop_payment_id
Shop_payment_id must be unique for each new transfer.
The request can pass additional parameters, such as description – payout description.
Example of request:
{
"amount": 10,
"amount_type": "receive_amount",
"payee_account": "201497141132",
"payee_currency": 980,
"shop_currency": 980,
"shop_id": 112,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
"sign": "cd30ba2b6e29f508edf40582e17a9a602a43be9b527238b1b0a6777e226381f4"
}
Where,
| Parameter | Description | Format | Example |
|---|---|---|---|
payee_account | payee account in Qostiq system, can be a wallet ID or user's email | String | "201487668051" or "qostiq@qostiq.com" |
amount | receive or write-off amount (depends on amount_type) | Number (no more than 2 characters after the dot) | 1.00 or 1 |
amount_type | type of the amount, possible options: receive_amount – amount to be received, writeoff_amount — amount to be written off the shop's balance | String | "receive_amount" or "writeoff_amount" |
payee_currency | receiving currency on the Qostiq account | Integer | 980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge |
shop_currency | write-off currency from the shop | Integer | 840 — US Dollar, 978 — Euro, 980 — UA Hryvnia, 398 — KZ Tenge |
shop_id | shop ID from which the payment is made | Integer | 5 |
shop_payment_id | unique payment ID on the shop's side | String | "h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92" |
Example of response:
{
"data": {
"balance": 0.9,
"id": 3,
"payee_account": 201497141132,
"payee_amount": 10,
"payee_currency": 980,
"shop": 112,
"shop_currency": 980,
"write_off_amount": 10
},
"error_code": 0,
"message": "Ok",
"result": true
}
Where,
| Parameter | Description |
|---|---|
balance | shop balance after the successful transfer creation |
id | unique transfer ID in Qostiq system |
payee_amount | amount to be received in payee_currency |
payee_currency | receiving currency for payee_amount |
shop_currency | write-off currency from the shop of shop_write_off amount |
shop_payment_id | unique payment ID on shop's side |
write_off_amount | write-off amount from the shop in shop_currency |
Warning! Transfers do not have a status since, if it was created and a transfer ID is received in the response, then the transfer is considered successful and no additional requests are required.
Transfer funds from the shop balance [POST]
To show the request, change Production to Mock Server in the right window
- Request (application/json)
{
"amount": 10,
"amount_type": "receive_amount",
"payee_account": "201497141132",
"payee_currency": 980,
"shop_currency": 980,
"shop_id": 112,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561324",
"sign": "cd30ba2b6e29f508edf40582e17a9a602a43be9b527238b1b0a6777e226381f4"
}
- Response 200 ()
{
"data": {
"balance": 88.91,
"id": 12,
"payee_account": 201497141132,
"payee_amount": 10,
"payee_currency": 980,
"shop": 112,
"shop_currency": 980,
"write_off_amount": 10
},
"error_code": 0,
"message": "Ok",
"result": true
}
Transfer status request [/transfer/shop_payment_status]
Transfer status request is performed by the shop payment ID.
In case of time-out or other errors on the request to create a transfer, you can make a transfer status request using this method. If ID and transfer data were returned in the response, that means that the transfer was successfully created and processed. Otherwise, an error will be returned that the transfer was not found and you have to repeat a transfer creation request.
URL: https://core.qostiq.com/transfer/shop_payment_status
Method: POST
Mandatory parameters: now, shop_payment_id, shop_id
| Parameter | Description | Format | Example |
|---|---|---|---|
now | date of request | String | "2018-06-15 09:58:01.01" |
shop_payment_id | unique payment ID on the shop's side | String | "h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92" |
shop_id | shop ID in Qostiq system | Integer | 5 |
sign | signature | String | "a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109" |
Example of request:
{
"shop_id": 112,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322",
"now": "2018-01-23 16:45:14.145107",
"sign": "e76c5ed9431d18ad6c01ea123241fe88330714c97bdd184860a80cb675c1e016"
}
Example of response, if transfer was created and processed:
{
"data": {
"id": 3,
"payee_currency": 980,
"receive_amount": 1,
"shop_currency": 980,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322",
"write_off_amount": 1
},
"error_code": 0,
"message": "Ok",
"result": true
}
Example of response, if transfer was not created (not found):
{
"data": null,
"error_code": 7,
"message": "Transfer (shop_payment_id=test) wasn't found",
"result": false
}
Transfer status request [POST]
- Request (application/json)
{
"shop_id": 112,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322",
"now": "2018-01-23 16:45:14.145107",
"sign": "e76c5ed9431d18ad6c01ea123241fe88330714c97bdd184860a80cb675c1e016"
}
- Response 200 ()
{
"data": {
"id": 3,
"payee_currency": 980,
"receive_amount": 1,
"shop_currency": 980,
"shop_payment_id": "55ac443d-958b-40e3-8956-e04e72561322",
"write_off_amount": 1
},
"error_code": 0,
"message": "Ok",
"result": true
}
- Response 200 (error)
{
"data": null,
"error_code": 7,
"message": "Transfer (shop_payment_id=test) wasn't found",
"result": false
}