Skip to main content

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"
}
ParameterDescriptionFormatExample
shop_idshop ID in Qostiq systemInteger5
shop_amountbill amountNumber (no more than 2 characters after the dot)1, 1.0, 1.00 or "1.00"
shop_currencybill currency (shop admission)Integer980 — UA Hryvnia, 840 — US Dollar, 978 — Euro
payer_currencypayer currency (write-off currency from the payer in Qostiq system, can be different from the shop currency)Integer980 — UA Hryvnia, 840 — US Dollar, 978 — Euro
signsignatureString"a7f5bcbb774cea9d9886cbb3ce2f8731359e356a7d759437b4e9e31da1152109"
shop_order_idbill ID on the shop's sideString"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"
descriptionbill description (optional)String"test bill"
payer_accountemail 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.

ParameterDescriptionFormatExample
failed_urlURL, to which the payer will be redirected after unsuccessful paymentString"https://qostiq.com/failed"
success_urlURL, to which the payer will be redirected after successful paymentString"https://qostiq.com/success"
callback_urlURL for notification of successful paymentString"https://qostiq.com/callback_url_kvt"
callback_rejected_urlURL for notification of unsuccessful paymentString"https://qostiq.com/callback_rejected_url_kvt"
lifetimebill lifetime, in minutesString"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,

ParameterDescription
datainfo about the created bill
idunique bill ID in Qostiq system
lifetimebill lifetime, in minutes, by default: 43200 minutes
payer_accountpayer account (if passed in the request)
payer_currencycurrency in which the payer must pay the bill
payer_priceamount to be paid by the payer to settle the bill
shop_currencybill currency (shop admission)
shop_amountbill amount (from the shop)
shop_idshop ID
shop_order_idbill ID on shop's side
urlURL 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

ParameterDescription
messageerror description
error_codeerror 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 amount is passed);

  • free amount - your customer is allowed to choose an amount to be credited to the shop (if amount is 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"
}
ParameterDescriptionFormatExample
shop_idyour shop identifier in the Qostiq systemInteger6
currencycurrency of the invoice (crediting to the store)Integer980 — UA Hryvnia, 840 — US Dollar, 978 — Euro
nowrequest time in timestamp formatInteger1687520474
signsignature, see Signature formation rules (sign)String"771952b72a0869945d62373b46a79feabc5a674b34cf78de5dc7c4c36981cf87"
shop_order_idbill ID on the shop's sideString"dc5a286e-6c5e-43e8-8c68-926fa15d09ec"

Also, additional parameters can be passed in the request; they are not involved in signature formation.

ParameterDescriptionFormatExample
amountbill amount; if this parameter is present, the client will not be able to change the payment amountNumber (no more than 2 characters after the dot)1, 1.0, 1.00 or "1.00"
emailpayer's wallet email in Qostiq systemString"example@mail.com"
failed_urlURL to which the payer will be redirected after unsuccessful paymentString"https://qostiq.com/failed"
success_urlURL to which the payer will be redirected after successful paymentString"https://qostiq.com/success"
callback_urlURL for notification of successful paymentString"https://qostiq.com/callback_url_kvt"
callback_rejected_urlURL for notification of unsuccessful paymentString"https://qostiq.com/callback_rejected_url_kvt"
lifetimebill lifetime for payment, in minutes (90 by default)String"43200"
langpayment 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,

ParameterDescription
datainfo about the created bill
idunique bill identifier in the Qostiq system
lifetimebill lifetime for payment, in minutes, by default: 43200 minutes
payer_accountpayer account (if passed in the request)
payer_currencycurrency in which the payer must pay the bill
payer_priceamount to be paid by the payer to settle the bill
shop_currencybill currency (shop admission)
shop_amountbill amount (from the shop)
shop_idshop identifier
shop_order_idbill ID on shop's side
urlURL 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

ParameterDescription
messageerror description
error_codeerror 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"
}
ParameterDescriptionFormatExample
nowdate of requestString"2021-05-01 16:56:25.009469"
shop_idshop ID in Qostiq systemInteger1092
shop_order_idbill ID on the side of your serviceString"234234232323"
signsignatureString"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,

ParameterDescription
client_pricepayment amount
createddate of creation
descriptionbill description
is_uniquepayment ID uniqueness
payment_idpayment ID in Qostiq system
paywaypayway
processeddate of processing
ps_currencybill currency
ps_dataadditional data from the paysystem, such as payer account
shop_amountbill amount from the shop
shop_currencybill currency from the shop
shop_idshop ID in Qostiq system
shop_order_idbill ID on shop's side
shop_refundcredited amount on the shop's balance, in bill's currency
statusbill 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]

StatusValueDescriptionFinal?
1WaitingPayment is pending user actionNo
2PaidPayment is paid by the clientYes
3CanceledPayment is cancelled by the clientYes
4ExpiredBill is expiredYes

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,

ParameterDescriptionFormatExample
amountreceive or write-off amount (depends on amount_type)Number (no more than 2 characters after the dot)1.00 or 1
amount_typetype of the amount, possible options: receive_amount – amount to be received, writeoff_amount — amount to be written off the shop's balanceString"receive_amount" or "writeoff_amount"
payee_currencyreceiving currency on the Qostiq accountInteger980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge
shop_currencywrite-off currency from the shopInteger980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge
shop_idshop ID from which the payment is madeInteger5
signrequest signatureString"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,

ParameterDescription
account_info_config.payee_accountinformation about the account, including a regular expression that the account must match
payee_amountamount to be received in payee_currency
payee_currencyreceiving currency for payee_amount
shop_currencywrite-off currency from the shop of write_off_amount
write_off_amountwrite-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,

ParameterDescriptionFormatExample
payee_accountpayee account in Qostiq system, can be a wallet ID or user's emailString"201487668051" or "qostiq@qostiq.com"
amountreceive or write-off amount (depends on amount_type)Number (no more than 2 characters after the dot)1.00 or 1
amount_typetype of the amount, possible options: receive_amount – amount to be received, writeoff_amount — amount to be written off the shop's balanceString"receive_amount" or "writeoff_amount"
payee_currencyreceiving currency on the Qostiq accountInteger980 — UA Hryvnia, 840 — US Dollar, 978 — Euro, 398 — KZ Tenge
shop_currencywrite-off currency from the shopInteger840 — US Dollar, 978 — Euro, 980 — UA Hryvnia, 398 — KZ Tenge
shop_idshop ID from which the payment is madeInteger5
shop_payment_idunique payment ID on the shop's sideString"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,

ParameterDescription
balanceshop balance after the successful transfer creation
idunique transfer ID in Qostiq system
payee_amountamount to be received in payee_currency
payee_currencyreceiving currency for payee_amount
shop_currencywrite-off currency from the shop of shop_write_off amount
shop_payment_idunique payment ID on shop's side
write_off_amountwrite-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

ParameterDescriptionFormatExample
nowdate of requestString"2018-06-15 09:58:01.01"
shop_payment_idunique payment ID on the shop's sideString"h8fj38dkh-hf8k-4f8d-9c8c-jd8dh38dksn92"
shop_idshop ID in Qostiq systemInteger5
signsignatureString"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
}