For any question, we are one click away

Contact us
Search by keyword
/

Subscriptions

Subscriptions let you set up recurring charges from a customer's card for a preset amount and interval.

When a subscription is created, an order is registered for the initial payment and a link to the payment page is returned. After the initial payment succeeds, the subscription becomes active, and subsequent payments are charged automatically at the interval set in the billingIntervalValue and billingIntervalUnit parameters.

This section describes the methods for creating a subscription, getting a list of subscriptions and detailed information about a subscription, cancelling a subscription, and updating the recurring charge parameters.

Process description


Group 2Store

  1. The customer selects a subscription in the online store and clicks Subscribe.

  2. The online store's server receives the subscription request.

  3. The online store's server requests subscription registration by calling the POST /v1/subscriptions API method on the subscription service.

  4. The subscription service creates a new subscription and sends a response to the online store's server. The response contains the checkoutUrl parameter (the payment URL to which the online store must redirect the customer in step 5) and the subscriptionId parameter (the unique subscription number).

  5. The online store redirects the customer to the URL received in the checkoutUrl parameter. The redirect can be performed either in the current window or in a new one.

  6. The subscription service displays the payment page.

  7. The customer enters their card number, expiration date, and CVV/CVC, and clicks Confirm subscription.

  8. The subscription service processes the payment request.

  9. The customer is redirected to the finish page.

  10. The online store sends a POST /v1/subscriptions/details request to the subscription service to check the subscription status and make sure the initial payment succeeded. The request contains the subscriptionId parameter received in step 4.

  11. On the schedule set when the subscription was created, the subscription service checks which subscriptions are due for a repeat charge.

  12. Repeat charges are made using the payment instrument bound in step 7.

Base URL:

When sending the request, you should use the header: Content-Type: application/json;charset=UTF-8, method POST.

Subscription statuses

StatusDescription
INITIATEDCreated, awaiting initial payment
ACTIVEActive, recurring payments are being processed
UNPAIDPayment failed, retry pending
PAYMENT_FAILEDThe first payment failed
CANCELLEDCancelled (terminal status)

Creating a subscription

To create a subscription, use the POST /v1/subscriptions method. An order is registered, a subscription is created with the INITIATED status, and a link to the payment page for the initial payment is returned.

Request body

usernamestringrequired
Merchant's API account login.
passwordstringrequired
Merchant's API account password.
customerIdstringrequired
Customer number (ID) in the merchant's system.
amountnumberrequired
Payment amount in minor currency units (e.g. in cents).
currencynumberrequired
Numeric ISO 4217 code (e.g. 978 for EUR)
billingIntervalValuenumberrequired
Interval between recurring charges, in the units specified in billingIntervalUnit. Must be an integer greater than 0.
billingIntervalUnitstringrequired
One of: DAYS / WEEKS / MONTHS / YEARS
successUrlstringrequired
The address to which the user is to be redirected if the payment is successful. The address must be specified in full, including the protocol used.
failUrlstringrequired
The address to which the user is to be redirected if the payment fails. The address must be specified in full, including the protocol used.
emailstringrequired*
Mandatory if phone is not specified.
phonestringrequired*
+?[0-9\\s\\-()]{7,20}. Mandatory if email is not specified.
orderNumberstringoptional
Order number (ID) in the merchant's system; must be unique for each order.
descriptionstringoptional
Subscription description in any format. It is not allowed to include personal data or payment data (such as card numbers) in this field, because the description is not masked anywhere.

Example of a subscription creation request

curl --request POST \
  --url https://dev.bpcbt.com/wheel/v1/subscriptions \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "customerId": "customer-123",
    "email": "customer@example.com",
    "phone": "+79001234567",
    "amount": 10000,
    "currency": 978,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Monthly subscription",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail"
  }'

Example of a success response

{
  "checkoutUrl": "https://dev.bpcbt.com/payment/merchants/ecom2/payment.html?mdOrder=02ea2f54-96a1-7ba5-8cfd-c56c026fc629&language=en&subscription=true",
  "subscription": {
    "subscriptionId": "fe10e4c1-015d-4762-8309-89713438e78a",
    "merchantLogin": "merchant_login",
    "customerId": "customer-123",
    "amount": 10000,
    "currency": 978,
    "email": "customer@example.com",
    "phone": "+79001234567",
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Monthly subscription",
    "status": "INITIATED",
    "mdOrder": "02ea2f54-96a1-7ba5-8cfd-c56c026fc629",
    "bindingId": null,
    "activeTill": null,
    "nextChargeAt": null,
    "created": "2026-07-13T15:37:45.359553+03:00"
  }
}

Examples of responses with errors

400 Bad Request — validation error or payment gateway registration failure

{ "error": "Either email or phone is required" }
{ "error": "Amount must be greater than zero" }
{ "error": "Payment Gateway registration failed: ..." }

500 Internal Server Error

{ "error": "Internal server error" }

List of subscriptions

To get a list of subscriptions, use the POST /v1/subscriptions/list method. The method returns a paginated list of the merchant's subscriptions with filtering and sorting.

Request body

usernamestringrequired
Merchant's API account login.
passwordstringrequired
Merchant's API account password.
statusesstring[]optional
A list of subscription statuses to filter by. The possible values are listed in the Subscription statuses section.
customerIdstringoptional
Customer number (ID) in the merchant's system to filter subscriptions by.
amountFromnumberoptional
The minimum subscription amount in minor currency units. The boundary value is included in the result.
amountTonumberoptional
The maximum subscription amount in minor currency units. The boundary value is included in the result.
createdFromstringoptional
The date and time the subscription was created, starting from which records are to be returned. Specified in ISO 8601 format.
createdTostringoptional
The date and time the subscription was created, up to which records are to be returned. Specified in ISO 8601 format.
sortFieldstringoptional
The field to sort the list by. Possible values: CUSTOMER_ID, SUBSCRIPTION_ID, CREATED, UPDATED, AMOUNT, STATUS, NEXT_CHARGE_AT. Default value: CREATED.
sortDirectionstringoptional
The sort direction. Possible values: ASC, DESC. Default value: DESC.
pagenumberoptional
The page number, starting from 0. Default value: 0.
sizenumberoptional
The number of records per page. Default value: 20.

Example of a subscription list request

curl --request POST \
  --url https://dev.bpcbt.com/wheel/v1/subscriptions/list \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "statuses": ["ACTIVE", "UNPAID"],
    "customerId": null,
    "amountFrom": 5000,
    "amountTo": null,
    "createdFrom": "2026-01-01T00:00:00+03:00",
    "createdTo": null,
    "sortField": "CREATED",
    "sortDirection": "DESC",
    "page": 0,
    "size": 20
  }'

Example of a success response

{
  "items": [
    {
      "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
      "merchantLogin": "merchant_login",
      "customerId": "customer-123",
      "amount": 10000,
      "currency": 978,
      "email": "customer@example.com",
      "status": "ACTIVE",
      "billingIntervalValue": 1,
      "billingIntervalUnit": "MONTHS",
      "activeTill": "2026-12-31T23:59:59+03:00",
      "created": "2026-01-01T10:00:00+03:00"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "page": 0,
  "size": 20
}

Examples of responses with errors

500 Internal Server Error

{ "error": "Internal server error" }

Subscription details

To get complete information about a subscription, use the POST /v1/subscriptions/details method. The method returns the subscription parameters and a list of related payments.

For an active subscription, the first element in payments is the activation payment (the initial payment). The subsequent elements are recurring charges.

Request body

usernamestringrequired
Merchant's API account login.
passwordstringrequired
Merchant's API account password.
subscriptionUuidstringrequired
The subscription UUID received when the subscription was created.

Example of a subscription details request

curl --request POST \
  --url https://dev.bpcbt.com/wheel/v1/subscriptions/details \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionUuid": "550e8400-e29b-41d4-a716-446655440000"
  }'

Example of a success response

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "merchantLogin": "merchant_login",
  "customerId": "customer-123",
  "amount": 10000,
  "currency": 978,
  "email": "customer@example.com",
  "phone": "+79001234567",
  "billingIntervalValue": 1,
  "billingIntervalUnit": "MONTHS",
  "description": "Monthly subscription",
  "status": "ACTIVE",
  "mdOrder": "abc12345-0000-0000-0000-000000000000",
  "bindingId": "binding-id-12345",
  "activeTill": "2026-12-31T23:59:59+03:00",
  "nextChargeAt": "2026-07-01T10:00:00+03:00",
  "created": "2026-01-01T10:00:00+03:00"
}

Examples of responses with errors

404 Not Found — the subscription was not found or belongs to another merchant

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }

Cancelling a subscription

To cancel a subscription, use the POST /v1/subscriptions/deactivate method. The method sets the subscription to the CANCELLED status and terminates the associated recurring process.

Cancelling an already cancelled subscription again returns a 422 error.

Request body

usernamestringrequired
Merchant's API account login.
passwordstringrequired
Merchant's API account password.
subscriptionIdstringrequired
The UUID of the subscription to cancel.
forcebooleanoptional
The subscription cancellation method. false — wait until the end of the current billing period; true — cancel immediately. Default value: false.

Example of a subscription cancellation request

curl --request POST \
  --url https://dev.bpcbt.com/wheel/v1/subscriptions/deactivate \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "force": false
  }'

Example of a success response

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED"
}

Examples of responses with errors

404 Not Found

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

422 Unprocessable Entity — the subscription is already cancelled

{ "error": "Subscription already cancelled: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }

Updating a subscription

To update a subscription, use the POST /v1/subscriptions/update method. The method changes the charge amount and/or interval. If an optional field is not passed, the current value of that field is kept.

A subscription with the CANCELLED status cannot be updated.

Request body

usernamestringrequired
Merchant's API account login.
passwordstringrequired
Merchant's API account password.
subscriptionIdstringrequired
The UUID of the subscription to update.
amountnumberoptional
The new recurring charge amount in minor currency units. Must be an integer greater than 0.
billingIntervalValuenumberoptional
The new interval between recurring charges, in the units specified in billingIntervalUnit. Must be an integer greater than 0.
billingIntervalUnitstringoptional
The new unit for the recurring charge interval. Possible values: DAYS, WEEKS, MONTHS, YEARS.

Example of a subscription update request

curl --request POST \
  --url https://dev.bpcbt.com/wheel/v1/subscriptions/update \
  --header 'content-type: application/json;charset=UTF-8' \
  --data '{
    "username": "merchant_login",
    "password": "merchant_password",
    "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 15000,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS"
  }'

Example of a success response

{
  "subscriptionId": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACTIVE",
  "amount": 15000,
  "billingIntervalValue": 1,
  "billingIntervalUnit": "MONTHS"
}

Examples of responses with errors

404 Not Found

{ "error": "Subscription not found: 550e8400-e29b-41d4-a716-446655440000" }

422 Unprocessable Entity — the subscription is cancelled

{ "error": "Cannot update cancelled subscription: 550e8400-e29b-41d4-a716-446655440000" }

500 Internal Server Error

{ "error": "Internal server error" }
Categories:
SubscriptionsAPI V1
Categories
Search results
Navigate
Select
Close
Categories
Search results