Subscription Flow
This guide provides a structured process for managing subscriptions via the API.
1. Get Available Subscriptions
Endpoint:
GET reg/subscription/details/available
Retrieves a list of available subscription plans that a user can subscribe to.
Response Example:
{
"amount": 0,
"currency": "string",
"description": "string",
"details":{
"feature" : [ "EXCHANGE", "SEND_CRYPTO", "DEPOSIT_CRYPTO", "PAYIN", "VIRTUAL_CARD" ],
"tariffDetails" : [ {
"key" : "depositCryptoFee",
"label" : "Deposit crypto fee",
"order" : 0,
"value" : "0%"
}, {
"key" : "sendFee",
"label" : "Send crypto fee",
"order" : 1,
"value" : "0.3%"
} ]
},
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"initialPaymentAmount": 0,
"level": 0,
"mostPopular": true,
"name": "string",
"subscriptionInterval": "DAYS30",
"trialAvailable": true
}
2. Start Subscription
Endpoint:
POST reg/subscription
Starts a new subscription for a user and returns an invoice ID in the response.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
anyCurrency | boolean | ✅ | Indicates whether the subscription can be paid in any currency. |
subscriptionDetailsId | string | Unique identifier of the subscription details form. |
Response Example:
{
"desc": "string",
"id": "string",
"payUrl": "string",
"result": 0,
}
The invoice ID retrieved by this endpoint will be used during the following steps of getting the subscription.
The new subscription started on this step can already be retrieved by using Get current subscription endpoint along with the invoice ID in order to make initial payment.
Subscription Statuses
| Status | Description |
|---|---|
INIT | Subscription started but not yet paid. No access granted. |
ACTIVE | Subscription is active, successfully paid, and access granted. Monthly payments occur. |
DEACTIVATING | User has canceled the subscription, but it remains active until the next billing cycle. |
CANCELLED | Subscription is fully canceled, and access is revoked. |
3. Get Invoice by ID
Endpoint:
Retrieves an invoice by its ID if it is available for the user.
Path Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
id | string | ✅ | the invoice ID. |
Response Example:
{
"status" : "INIT",
"payments" : [ ],
"lastModifiedDate" : "2025-04-22T10:16:56.773584Z",
"recurrentInvoiceId" : "c2cc3212-7bd5-44f7-a6b0-50ba2beedf11",
"externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
"id" : "8ff3635a-0f80-40a1-8eb3-555802c0635d",
"amount" : 3,
"currency" : "usd",
"type" : "ORIGINAL",
"alignable" : true
}
Optional. Apply Discount to Invoice
Endpoint:
GET /acquiring/invoice/{invoiceId}/discount
Enables clients to apply promotional discounts before finalizing the payment.
Path Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
Query Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
discountCode | string | ✅ | the discount code to be applied to the invoice, which may provide a percentage or fixed discount. |
Response Example:
{
"status" : "INIT",
"payments" : [ ],
"discountCode" : "WELCOME100",
"amountBeforeDiscount" : 102,
"lastModifiedDate" : "2025-04-22T10:22:47.441401859Z",
"recurrentInvoiceId" : "034cd818-18ca-4896-bfe2-cc7c445320cb",
"externalClientId" : "8a7b9019-bec5-4580-9b34-31a0b8fb613f",
"id" : "fea628c5-fa29-4f54-98ef-e4a2ede4d755",
"amount" : 0.00000000,
"currency" : "usd",
"type" : "ORIGINAL",
"alignable" : true
}
Once you use this endpoint, response body retrieved by Get Invoice by ID endpoint will be changed — as the discountCode and AmountBeforeDiscount parameters will be updated.
4. Initialize Payment
Endpoint:
POST /invoice/payment
Initializes the payment for the subscription.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
type | string | ✅ | Payment provider type (only PLATFORM one is available). |
accountId | string | ✅ | Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint. |
currency | string | ✅ | Currency used for the payment. |
anyCurrency | boolean | ✅ | Flag indicating whether multiple currencies are supported. |
Response Example:
{
"accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
"id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
"invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
"status" : "INIT",
"type" : "PLATFORM",
"amount" : 15,
"description" : "Invoice payment",
"last_modified_date" : "2025-04-07T21:32:11.716207540Z",
"created_date" : "2025-04-07T21:32:11.716207540Z"
}
5. Confirm Invoice Payment
Endpoint:
POST payment/pay
Confirms the payment of the invoice.
Body Parameters:
| Name | Type | Required | Description |
|---|---|---|---|
invoiceId | string | ✅ | the invoice ID. |
type | string | ✅ | Payment provider type (only PLATFORM one is available). |
paymentId | string | ✅ | Unique identifier for the payment from Step 4. |
accountId | string | ✅ | Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint. |
currency | string | ✅ | Currency used for the payment. |
anyCurrency | boolean | ✅ | Flag indicating whether multiple currencies are supported. |
Response Example:
{
"accountId" : "59341629-5f86-47a5-a867-1c4225f119b0",
"id" : "8caf4504-d6b0-461b-9b67-53dacee85156",
"invoiceId" : "a90f36dd-57af-4f5e-a2f5-086631f9edac",
"status" : "PROCESSING",
"type" : "PLATFORM",
"amount" : 15,
"description" : "Invoice payment",
"last_modified_date" : "2025-04-07T21:32:14.700515749Z",
"created_date" : "2025-04-07T21:32:11.716208Z"
}
Once you pay the invoice, you will need to use OAuth2.0 and Retrieve User Information endpoints — in order to refresh your token and update the userScopes and scope parameters.
Updated 2 days ago