subscriptions | Qostiq

Qostiq Wallet subscription functionality

Scheme of using Qostiq Wallet subscription functionality:

Request /auth_token/request to create a subscription. A URL will be returned in response to this request, to which the client must be redirected to confirm their subscription.
After the client confirms the subscription, a unique token will be sent to the URL specified in the shop settings, which will be used in further requests.
Request to perform an action allowed for the specified token (for example, a request to withdraw fiat funds /bill/recurrent).
If it is necessary to disable the subscription and deactivate the token, execute the request /auth_token/revoke.

You can create several subscriptions for one Qostiq Wallet using different external_id values. external_id values are visible to clients.

Create subscription request [/auth_token/request]

URL: https://core.qostiq.com/auth_token/request

Method: POST

Required parameters: external_id, now, scopes, shop_id

This request creates a subscription entity that needs to be confirmed by the client.

Attention! You must use unique external_id values. If you try to create a subscription with an already existing external_id, the previously created subscription will be updated.

Request example:

{
    "external_id": "test_external_id",
    "now": 1691584193,
    "scopes": ["bill_recurrent"],
    "shop_id": 6,
    "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
}

Where,

Parameter	Description	Format	Example
`external_id`	subscription number or name (visible to the client)	String	"test_external_id"
`now`	request time	Integer	1691584193
`scopes`	subscription type	Array	["bill_recurrent"] - value for receiving a token for subscription payments
`shop_id`	shop ID in Qostiq	Integer	6
`sign`	signature	String	"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"

Sample response:

{
    "data": {
        "redirect_url": "https://wallet.test-qostiq.com/subscription-request/27d5c54568e944abb2b5a64b845d13eb"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

It is necessary to perform a browser redirect (HTTP GET) to the address specified in the redirect_url parameter to confirm the subscription. Upon confirmation, a subscription activation notification will be sent.

Important:

redirect_url is opened only via GET method
redirect_url is not an API endpoint
Sending POST requests to redirect_url is not supported

Example of create subscription request [POST]

Request (application/json)

{
    "external_id": "external_id",
    "now": 1691584193,
    "scopes": [
        "bill_recurrent"
    ],
    "shop_id": 6,
    "sign": "912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"
}

Response 201 (application/json)

{
    "data": {
        "redirect_url": "https://wallet.test-qostiq.com/subscription-request/27d5c54568e944abb2b5a64b845d13eb"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Activation and cancellation notification [/auth_token/callback]

After the client activates the subscription, a notification with a token will be sent to the URL, which will be used to make subsequent payments.

The URL is specified in the personal profile in the shop settings — URL for auth token notifications.

A notification will also be sent if the client cancels the subscription.

Example of subscription activation notification:

{
    "callback_type": "auth_token",
    "created": "2023-08-09 15:50:50",
    "external_id": "external_id",
    "scopes": [
        "bill_recurrent"
    ],
    "shop_id": 6,
    "sign": "7dh39fkd7cf1b1db2175606447c60e6d9b5c84219471f7239329a4c9a29",
    "status": 1,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98"
}

Where:

Parameter	Description
`callback_type`	notification type, value `auth_token` for subscription activation notification
`created`	subscription activation time
`external_id`	subscription identifier
`scopes`	subscription type, value `["bill_recurrent"]` for payment subscription activation
`sign`	callback signature
`status`	token status: `1` — token active (subscription activated), `2` — token inactive (subscription cancelled)
`token`	subscription token, used for subsequent requests, e.g. making payments without confirmation

Subscription cancellation notification [POST]

Upon correct receipt and processing of the notification, return http status 200 and message body OK. Otherwise notifications will be resent with increasing intervals, 25 attempts total, the last one after one day.

Request (application/json)

{
    "callback_type": "auth_token",
    "created": "2023-08-09 14:42:46",
    "external_id": "external_id",
    "scopes": [
        "bill_recurrent"
    ],
    "shop_id": 6,
    "sign": "11d94f04959e153cd719ab7029f767d8e6ea853af4f26a4f0f77a7b238c1e78f",
    "status": 2,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98"
}

Response 200 (application/json)
```
  OK
```

Creating a fiat payment by subscription [/bill/recurrent]

URL: https://core.qostiq.com/bill/recurrent

Method: POST

Mandatory parameters: amount, currency, now, shop_id, shop_order_id, token

This request creates a charge from the client's wallet in favor of the shop without client confirmation.

Example request:

{
    "amount": "10",
    "currency": 840,
    "now": 1691658477,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d",
    "sign": "97a4dd349871cc80aef906cee468d8b942c0197848e3ed86a6f9f58a8725e180"
}

Where,

Parameter	Description	Format	Example
`amount`	payment amount	Number (no more than 2 characters after the dot)	1, 1.0, 1.00 or "1.00"
`currency`	payment currency	Integer	840 — US Dollar, 980 — UA Hryvnia, 978 — Euro, 398 — KZ Tenge
`shop_id`	shop ID in Qostiq system	Integer	6
`now`	request time	Integer	1691584193
`token`	subscription token received in response to the subscription creation request	String	"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
`scopes`	subscription type	Array	["bill_recurrent"] - value for receiving a token for subscription payments
`shop_order_id`	bill ID on the side of your service	String	"123456789"
`sign`	signature	String	"912b985f18959620bb981485132016b58fc344361a51a24eda27687613141f7f"

Example response:

{
    "data": {
        "id": 2177,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where response parameters:

Parameter	Description
`id`	unique payment ID within fiat payments from Qostiq wallet
`status`	payment status, where value `2` — payment is successful

In case of timeout or other error on subscription debit request, make a payment status request by shop operation number — parameter shop_order_id.

Creating a fiat payment by subscription [POST]

Request (application/json)

{
    "amount": "10",
    "currency": 840,
    "now": 1691658477,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d",
    "sign": "97a4dd349871cc80aef906cee468d8b942c0197848e3ed86a6f9f58a8725e180"
}

Response 200 (application/json)

{
    "data": {
        "id": 2177,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Creating a cryptocurrency payment by subscription [/crypto/bill/recurrent]

URL: https://core.qostiq.com/crypto/bill/recurrent

Method: POST

Mandatory parameters: amount, currency, now, shop_id, shop_order_id, token

This request creates a charge from the client's wallet in favor of the shop without client confirmation.

Example request:

{
    "amount": "10",
    "currency": "USDT",
    "now": 1691669000,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d",
    "sign": "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"
}

Where,

Parameter	Description	Format	Example
`amount`	payment amount	String or number, see "Amount declaration" for decimal places	"1.00000001" or 1.00000001, or "10"
`currency`	payment currency	String	"USDT"
`shop_id`	shop ID in Qostiq system	Integer	6
`now`	request time	Integer	1691669000
`token`	subscription token received in response to the subscription creation request	String	"f1cebac7-e05b-4c94-bb26-a222b976cb2d"
`scopes`	subscription type	Array	["bill_recurrent"] - value for receiving a token for subscription payments
`shop_order_id`	bill ID on the side of your service	String	"test payment"
`sign`	signature	String	"ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"

Example response:

{
    "data": {
        "id": 1579,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where response parameters:

Parameter	Description
`id`	unique payment ID within cryptocurrency payments from Qostiq wallet
`status`	payment status, where value `2` — payment is successful

In case of timeout or other error on subscription debit request, make a payment status request by shop operation number — parameter shop_order_id.

Cryptocurrency subscription payment request [POST]

Request (application/json)

{
    "amount": "10",
    "currency": "USDT",
    "now": 1691669000,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "token": "f1cebac7-e05b-4c94-bb26-a222b976cb2d",
    "sign": "ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"
}

Response 200 (application/json)

{
    "data": {
        "id": 1579,
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Cancel subscription request [/auth_token/revoke]

URL: https://core.qostiq.com/auth_token/revoke

Method: POST

Mandatory parameters: now, shop_id, token

This request allows you to close an active subscription.

Example request:

{
    "shop_id": 6,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98",
    "now": 1691671996,
    "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d"
}

Where:

Parameter	Description	Format	Example
`shop_id`	shop ID in Qostiq system	Integer	6
`now`	request time	Integer	1691671996
`token`	subscription token received in response to the subscription creation request	String	"44c6703d-9f98-434d-936f-9e6784976c98"
`sign`	signature	String	"ac3503d0b2e21c4716c96fbd58f32da678cf0a179a34bdf60ce5f36016efa2a2"

Example response on successful subscription cancellation — subscription token is returned:

{
    "data": {
        "token": "44c6703d-9f98-434d-936f-9e6784976c98"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

If the subscription is already cancelled, an error will be received:

{
    "data": null,
    "error_code": 10,
    "message": "Auth token (44c6703d-9f98-434d-936f-9e6784976c98) not found",
    "result": false
}

Cancel subscription request [POST]

Request (application/json)

{
    "shop_id": 6,
    "token": "44c6703d-9f98-434d-936f-9e6784976c98",
    "now": 1691671996,
    "sign": "8f15f065b07f6a2150277d57e125f3133ae4f9cab31f3529aaa8d6daa97b0c1d"
}

Response 200 (application/json)

{
    "data": {
        "token": "44c6703d-9f98-434d-936f-9e6784976c98"
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Fiat subscription payment status request [/bill/shop_order_status]

This method allows you to find out the current status of a fiat payment from 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`	request time	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.

Fiat subscription payment 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
}

Cryptocurrency subscription payment status request [/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. It allows you to find out the current status of a created payment.

Example of request:

{
    "now": 1691676646,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "sign": "97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1"
}

Where,

Parameter	Description	Format	Example
`now`	request time in unix timestamp format	Integer	1691676646
`shop_id`	shop ID in Qostiq system	Integer	6
`shop_order_id`	bill ID on the shop's side	String	"test payment"
`sign`	signature, see Signature formation rules for crypto operations (sign)	String	"97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1"

Example of response:

{
    "data": {
        "created": "2023-08-10 12:03:20",
        "description": "",
        "is_unique": false,
        "payer_currency": "USDT",
        "payer_price": "1.0",
        "payment_id": 1579,
        "processed": "2023-08-10 12:03:20",
        "ps_data": {
            "ps_payer_account": "31645670435"
        },
        "shop_amount": "1.0",
        "shop_currency": "USDT",
        "shop_id": 6,
        "shop_order_id": "test payment",
        "shop_refund": "0.97",
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Where,

Parameter	Description
`created`	payment creation date
`description`	payment description
`is_unique`	uniqueness of shop's payment number (`shop_order_id`)
`payer_currency`	currency for debiting `payer_price` from the client's wallet
`payer_price`	amount debited from the client's wallet in `payer_currency`
`payment_id`	unique operation number on Qostiq side, returned as `id` in response to payment creation request `/crypto/bill/create`
`processed`	time of receiving payment's final status
`ps_data.ps_payer_account`	payer's wallet number
`shop_amount`	payment amount in `shop_currency`
`shop_currency`	payment currency
`shop_id`	shop number
`shop_order_id`	payment number on the shop's side
`shop_refund`	payment credit to shop in `shop_currency`
`status`	payment status, see Payment statuses

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. Uniqueness of shop_order_id is checked depending on the shop settings, it is recommended to enable this feature and pass a unique value to avoid duplicate billing.

Cryptocurrency subscription payment status request [POST]

Request

{
    "now": 1691676646,
    "shop_id": 6,
    "shop_order_id": "test payment",
    "sign": "97a8d477e41d7e61af1a65ac9c662d1b28064aa4248a4eebb641deb5524e37f1"
}

Response 200 ()

{
    "data": {
        "created": "2023-08-10 12:03:20",
        "description": "",
        "is_unique": false,
        "payer_currency": "USDT",
        "payer_price": "1.0",
        "payment_id": 1579,
        "processed": "2023-08-10 12:03:20",
        "ps_data": {
            "ps_payer_account": "31645670435"
        },
        "shop_amount": "1.0",
        "shop_currency": "USDT",
        "shop_id": 6,
        "shop_order_id": "test payment",
        "shop_refund": "0.97",
        "status": 2
    },
    "error_code": 0,
    "message": "Ok",
    "result": true
}

Subscription payment statuses [/bill/status]

`status` value	Name	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
}

Errors when using subscription functionality [/error]

Request	`error_code`	`message`	Description
/bill/recurrent /crypto/bill/recurrent /auth_token/revoke	`10`	`Auth token ({token}) not found`	Token does not exist or is inactive
/bill/recurrent /crypto/bill/recurrent	`9`	`Insufficient payer (id=6) balance`	Insufficient funds on the client's wallet for debit
/bill/recurrent /crypto/bill/recurrent	`44`	`Limit exceeds`	Client's subscription payment limit exceeded

Error response request [POST]

Request

{
    "amount": "1",
    "currency": 840,
    "shop_id": 6,
    "token": "0b2808dc-3b6e-48d0-ac9b-64e31b756182",
    "now": 1692098067,
    "shop_order_id": "test payment",
    "sign": "8a461f70b3a8d4f5e2668f9de4ad17c8d1759f891333caf03ae9f50d5015618d"
}

Response 200 ()

{
    "data": null,
    "error_code": 44,
    "message": "Limit exceeds",
    "result": false
}

Qostiq Wallet subscription functionality​

Create subscription request [/auth_token/request]​

Example of create subscription request [POST]​

Activation and cancellation notification [/auth_token/callback]​

Subscription cancellation notification [POST]​

Creating a fiat payment by subscription [/bill/recurrent]​

Creating a fiat payment by subscription [POST]​

Creating a cryptocurrency payment by subscription [/crypto/bill/recurrent]​

Cryptocurrency subscription payment request [POST]​

Cancel subscription request [/auth_token/revoke]​

Cancel subscription request [POST]​

Fiat subscription payment status request [/bill/shop_order_status]​

Fiat subscription payment status request [POST]​

Cryptocurrency subscription payment status request [/crypto/bill/shop_order_status]​

Cryptocurrency subscription payment status request [POST]​

Subscription payment statuses [/bill/status]​

Bill status request with non-unique shop_order_id [POST]​

Errors when using subscription functionality [/error]​

Error response request [POST]​

Qostiq Wallet subscription functionality

Create subscription request [/auth_token/request]

Example of create subscription request [POST]

Activation and cancellation notification [/auth_token/callback]

Subscription cancellation notification [POST]

Creating a fiat payment by subscription [/bill/recurrent]

Creating a fiat payment by subscription [POST]

Creating a cryptocurrency payment by subscription [/crypto/bill/recurrent]

Cryptocurrency subscription payment request [POST]

Cancel subscription request [/auth_token/revoke]

Cancel subscription request [POST]

Fiat subscription payment status request [/bill/shop_order_status]

Fiat subscription payment status request [POST]

Cryptocurrency subscription payment status request [/crypto/bill/shop_order_status]

Cryptocurrency subscription payment status request [POST]

Subscription payment statuses [/bill/status]

Bill status request with non-unique shop_order_id [POST]

Errors when using subscription functionality [/error]

Error response request [POST]