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.

Read about how to view subscriptions in your Personal Area here.

Process description

<?xml version="1.0" encoding="UTF-8"?>

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:

• https://dev.bpcbt.com/wheel/v1/subscriptions — for the test environment;

• https://dev.bpcbt.com/wheel/v1/subscriptions — for the production environment

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

Subscription statuses

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

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

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

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

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

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