Abonnements

Les abonnements permettent d'organiser des débits réguliers sur la carte du client selon un montant et une périodicité prédéfinis.

Lors de la création d'un abonnement, une commande pour le paiement initial est enregistrée et un lien vers la page de paiement est retourné. Après le paiement initial réussi, l'abonnement devient actif, et les paiements suivants s'effectuent automatiquement avec la périodicité définie dans les paramètres billingIntervalValue et billingIntervalUnit.

Cette section décrit les méthodes de création d'abonnement, d'obtention de la liste des abonnements et des informations détaillées sur l'abonnement, d'annulation d'abonnement et de mise à jour des paramètres de débits réguliers.

Description du processus

1. Le client choisit un abonnement dans la boutique en ligne et clique sur le bouton S'abonner.

2. Le serveur de la boutique en ligne reçoit la demande d'abonnement.

3. Le serveur de la boutique en ligne demande l'enregistrement d'abonnement en envoyant un appel API POST /v1/subscriptions au service d'abonnements.

4. Le service d'abonnements crée un nouvel abonnement et envoie une réponse au serveur de la boutique en ligne. La réponse contient le paramètre checkoutUrl (URL de paiement vers laquelle la boutique en ligne doit rediriger le client à l'étape 5) et le paramètre subscriptionId (numéro unique d'abonnement).

5. La boutique en ligne redirige le client vers l'URL reçue dans le paramètre checkoutUrl. La redirection peut s'effectuer aussi bien dans la fenêtre courante que dans une nouvelle.

6. Le service d'abonnements affiche la page de paiement.

7. Le client saisit le numéro de sa carte, sa date d'expiration et CVV/CVC et clique sur Créer l'abonnement.

8. Le service d'abonnements traite la demande de paiement.

9. Le client est redirigé vers la page finale.

10. La boutique en ligne envoie une demande POST /v1/subscriptions/details au service d'abonnements pour vérifier le statut de l'abonnement et s'assurer que le paiement initial s'est déroulé avec succès. La demande contient le paramètre subscriptionId reçu à l'étape 4.

11. Le service d'abonnements selon la planification indiquée lors de la création d'abonnement vérifie pour quels abonnements il faut effectuer des débits répétés.

12. Les débits répétés sont effectués avec le moyen de paiement lié à l'étape 7.

URL de base :

• https://dev.bpcbt.com/wheel/v1/subscriptions — pour l'environnement de test ;
• https://dev.bpcbt.com/wheel/v1/subscriptions — pour l'environnement de production

Lors de l'exécution de la requête, il est nécessaire d'utiliser l'en-tête : Content-Type: application/json;charset=UTF-8, méthode POST.

Statuts d'abonnement

Création d'abonnement

Pour créer un abonnement, utilisez la méthode POST /v1/subscriptions. Une commande est enregistrée, un abonnement est créé avec le statut INITIATED et un lien vers la page de paiement pour le paiement initial est renvoyé.

Corps de la requête

Exemple de requête de création d'abonnement

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": 643,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Monthly subscription",
    "successUrl": "https://example.com/success",
    "failUrl": "https://example.com/fail"
  }'

Exemple de réponse réussie

{
  "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": 643,
    "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"
  }
}

Exemples de réponses avec erreur

400 Bad Request — erreur de validation ou échec d'enregistrement dans la passerelle

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

Liste des abonnements

Pour obtenir la liste des abonnements, la méthode POST /v1/subscriptions/list est utilisée. La méthode retourne une liste paginée des abonnements du marchand avec filtrage et tri.

Corps de la requête

Exemple de requête de liste d'abonnements

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

Exemple de réponse réussie

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

Exemples de réponses avec erreur

500 Internal Server Error

{ "error": "Internal server error" }

Détails de l'abonnement

Pour obtenir des informations complètes sur l'abonnement, la méthode POST /v1/subscriptions/details est utilisée. La méthode renvoie les paramètres de l'abonnement et la liste des paiements associés.

Pour un abonnement actif, le premier élément dans payments renvoie le paiement d'activation (paiement primaire). Les éléments suivants sont les débits récurrents.

Corps de la requête

Exemple de requête des détails d'abonnement

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

Exemple de réponse réussie

{
  "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": "Abonnement mensuel",
  "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"
}

Exemples de réponses avec erreur

404 Not Found — abonnement non trouvé ou appartient à un autre commerçant

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

500 Internal Server Error

{ "error": "Internal server error" }

Annulation d'abonnement

Pour annuler un abonnement, utilisez la méthode POST /v1/subscriptions/deactivate. La méthode fait passer l'abonnement au statut CANCELLED et termine le processus récurrent associé.

L'annulation répétée d'un abonnement déjà annulé retourne une erreur 422.

Corps de la demande

Exemple de demande d'annulation d'abonnement

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

Exemple de réponse réussie

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

Exemples de réponses avec erreur

404 Not Found

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

422 Unprocessable Entity — l'abonnement est déjà annulé

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

500 Internal Server Error

{ "error": "Internal server error" }

Mise à jour de l'abonnement

Pour mettre à jour l'abonnement, la méthode POST /v1/subscriptions/update est utilisée. La méthode modifie le montant et/ou l'intervalle de prélèvement. Si le champ optionnel n'est pas transmis, la valeur actuelle de ce champ est conservée.

Un abonnement avec le statut CANCELLED ne peut pas être mis à jour.

Corps de la requête

Exemple de requête de mise à jour d'abonnement

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

Exemple de réponse réussie

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

Exemples de réponses avec erreur

404 Not Found

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

422 Unprocessable Entity — abonnement annulé

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

500 Internal Server Error

{ "error": "Internal server error" }