Abonnements

Les abonnements permettent d'organiser des prélèvements réguliers de fonds 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 est enregistrée pour le paiement initial et un lien vers la page de paiement est renvoyé. Après le succès du paiement initial, l'abonnement devient actif, et les paiements suivants sont effectués 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 prélèvements réguliers.

Pour savoir comment consulter les abonnements dans l'Espace personnel, lisez ici.

Description du processus

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

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 une 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 (adresse 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 obtenue dans le paramètre checkoutUrl. La redirection peut s'effectuer aussi bien dans la fenêtre actuelle 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 le CVV/CVC et clique sur Souscrire l'abonnement.

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

9. Le client est redirigé vers la page de fin.

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 obtenu à l'étape 4.

11. Le service d'abonnements selon le planning indiqué lors de la création de l'abonnement vérifie pour quels abonnements il faut effectuer des prélèvements répétés.

12. Les prélèvements répétés sont effectués avec le moyen de paiement attaché à 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, on utilise 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 retourné.

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": 978,
    "billingIntervalValue": 1,
    "billingIntervalUnit": "MONTHS",
    "description": "Abonnement mensuel",
    "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=fr&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": "Abonnement mensuel",
    "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 de paiement

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