Subscription Flow

This guide provides a structured process for managing subscriptions via the API.

Step 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
  }

Step 2. Start Subscription

Endpoint:

POST /reg/subscription

Starts a new subscription for a user and returns an invoice ID in the response.

Body Parameters:

NameTypeRequiredDescription
anyCurrencyboolean✅Indicates whether the subscription can be paid in any currency.
subscriptionDetailsIdstringUnique 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

StatusDescription
INITSubscription started but not yet paid. No access granted.
ACTIVESubscription is active, successfully paid, and access granted. Monthly payments occur.
DEACTIVATINGUser has canceled the subscription, but it remains active until the next billing cycle.
CANCELLEDSubscription is fully canceled, and access is revoked.

Step 3. Get Invoice by ID

Endpoint:

GET /acquiring/invoice/{id}

Retrieves an invoice by its ID if it is available for the user.

Path Parameters:

NameTypeRequiredDescription
idstring✅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 step: Apply Discount to Invoice

Endpoint:

PUT /acquiring/invoice/{invoiceId}/discount

Enables clients to apply promotional discounts before finalizing the payment.

Path Parameters:

NameTypeRequiredDescription
invoiceIdstring✅the invoice ID.

Query Parameters:

NameTypeRequiredDescription
discountCodestring✅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.


Step 4. Initialize Payment

Endpoint:

POST /invoice/payment

Initializes the payment for the subscription.

Body Parameters:

NameTypeRequiredDescription
invoiceIdstring✅the invoice ID.
typestring✅Payment provider type (only PLATFORM one is available).
accountIdstring✅Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
currencystring✅Currency used for the payment.
anyCurrencyboolean✅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"
}

Step 5. Confirm Invoice Payment

Endpoint:

POST /payment/pay

Confirms the payment of the invoice.

Body Parameters:

NameTypeRequiredDescription
invoiceIdstring✅the invoice ID.
typestring✅Payment provider type (only PLATFORM one is available).
paymentIdstring✅Unique identifier for the payment from Step 4.
accountIdstring✅Identifies the CHECKING type of account in the wallet service. All accounts can be retrieved using List all accounts endpoint.
currencystring✅Currency used for the payment.
anyCurrencyboolean✅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.