Abonnements à la demande

​

Vue d’ensemble

• Créer un abonnement à la demande (autoriser un mandat avec un prix initial optionnel)
• Déclencher des charges ultérieures avec des montants personnalisés
• Suivre les résultats à l’aide de webhooks

​

Prérequis

• Compte marchand Dodo Payments et clé API
• Secret de webhook configuré et un point de terminaison pour recevoir des événements
• Un produit d’abonnement dans votre catalogue

​

Comment fonctionne la demande

1. Vous créez un abonnement avec l’objet on_demand pour autoriser un moyen de paiement et éventuellement collecter un prélèvement initial.
2. Plus tard, vous créez des prélèvements contre cet abonnement avec des montants personnalisés en utilisant le point de terminaison dédié aux prélèvements.
3. Vous écoutez les webhooks (par ex. payment.succeeded, payment.failed) pour mettre à jour votre système.

​

Créer un abonnement à la demande

​

Créer un abonnement à la demande

import DodoPayments from 'dodopayments';

const client = new DodoPayments({
  bearerToken: process.env.DODO_PAYMENTS_API_KEY,
  environment: 'test_mode', // defaults to 'live_mode'
});

async function main() {
  const subscription = await client.checkoutSessions.create({
    product_cart: [{ product_id: 'pdt_123', quantity: 1 }],
    billing_address:  { city: 'SF', country: 'US', state: 'CA', street: '1 Market St', zipcode: '94105' },
    customer: { customer_id: 'cus_123' },
    return_url: 'https://example.com/billing/success',
    subscription_data: {
        on_demand: {
            mandate_only: true // set false to collect an initial charge
            // product_price: 1000, // optional: charge $10.00 now if mandate_only is false
            // product_currency: 'USD',
            // product_description: 'Custom initial charge',
            // adaptive_currency_fees_inclusive: false,
        }
    }
  });

  console.log(subscription.checkout_url);
}

main().catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(
    bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'),
    environment="test_mode",  # defaults to "live_mode"
)

checkout = client.checkout_sessions.create(
    product_cart=[
        {"product_id": "pdt_123", "quantity": 1}
    ],
    billing_address={
        "city": "SF",
        "country": "US",
        "state": "CA",
        "street": "1 Market St",
        "zipcode": "94105",
    },
    customer={
        "customer_id": "cus_123",
    },
    return_url="https://example.com/billing/success",
    subscription_data={
      "on_demand":{
      "mandate_only": True,  # set False to collect an initial charge
      # "product_price": 1000,  # optional: charge $10.00 now if mandate_only is false
      # "product_currency": "USD",
      # "product_description": "Custom initial charge",
      # "adaptive_currency_fees_inclusive": False,
      }
    },
)

print(checkout.checkout_url)

package main

import (
    "fmt"
    "os"

    dodo "github.com/dodopayments/dodopayments-go"
)

func main() {
    client := dodo.NewClient(dodo.Config{
        BearerToken: os.Getenv("DODO_PAYMENTS_API_KEY"),
        Environment: dodo.TestMode, // defaults to LiveMode
    })

    checkout, err := client.CheckoutSessions.Create(dodo.CheckoutSessionCreateParams{
        ProductCart: []dodo.ProductCartItem{
            {
                ProductID: "pdt_123",
                Quantity:  1,
            },
        },
        BillingAddress: &dodo.BillingAddress{
            City:    "SF",
            Country: "US",
            State:   "CA",
            Street:  "1 Market St",
            Zipcode: "94105",
        },
        Customer: &dodo.CustomerRef{
            CustomerID: "cus_123",
        },
        ReturnURL: "https://example.com/billing/success",
        SubscriptionData: &dodo.SubscriptionData{
            OnDemand: &dodo.OnDemandSubscription{
                MandateOnly: true, // set false to collect an initial charge
                // ProductPrice: 1000,  // optional: charge $10.00 now if mandate_only is false
                // ProductCurrency: "USD",
                // ProductDescription: "Custom initial charge",
                // AdaptiveCurrencyFeesInclusive: false,
            },
        },
    })
    if err != nil {
        panic(err)
    }

    fmt.Println(checkout.CheckoutURL)
}

curl -X POST "$DODO_API/checkouts" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_cart": [
      {
        "product_id": "pdt_123",
        "quantity": 1
      }
    ],
    "customer": {
      "customer_id": "cus_123"
    },
    "billing_address": {
      "street": "1 Market St",
      "city": "SF",
      "state": "CA",
      "country": "US",
      "zipcode": "94105"
    },
    "subscription_data": {
      "on_demand": {
        "mandate_only": true
      }
    },
    "return_url": "https://example.com/billing/success"
  }'

{
  "session_id": "cks_123",
  "checkout_url": "https://test.checkout.dodopayments.com/session/cks123"
}

​

Facturer un abonnement à la demande

import DodoPayments from 'dodopayments';

const client = new DodoPayments({ bearerToken: process.env.DODO_PAYMENTS_API_KEY });

async function chargeNow(subscriptionId) {
  const res = await client.subscriptions.charge(subscriptionId, { product_price: 2500 });
  console.log(res.payment_id);
}

chargeNow('sub_123').catch(console.error);

import os
from dodopayments import DodoPayments

client = DodoPayments(bearer_token=os.environ.get('DODO_PAYMENTS_API_KEY'))

response = client.subscriptions.charge(
    subscription_id="sub_123",
    product_price=2500,
)

print(response.payment_id)

package main

import (
  "context"
  "fmt"
  "github.com/dodopayments/dodopayments-go"
  "github.com/dodopayments/dodopayments-go/option"
)

func main() {
  client := dodopayments.NewClient(option.WithBearerToken("YOUR_API_KEY"))
  res, err := client.Subscriptions.Charge(context.TODO(), "sub_123", dodopayments.SubscriptionChargeParams{
    ProductPrice: dodopayments.F(int64(2500)),
  })
  if err != nil { panic(err) }
  fmt.Println(res.PaymentID)
}

curl -X POST "$DODO_API/subscriptions/sub_123/charge" \
  -H "Authorization: Bearer $DODO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product_price": 2500,
    "product_description": "Extra usage for March"
  }'

{ "payment_id": "pay_abc123" }

​

Réessayer les paiements

​

Principes pour des politiques de réessai sûres

• Mécanisme de temporisation : utilisez une temporisation exponentielle entre les relances.
• Limites de relance : plafonnez le nombre total de relances (3 à 4 tentatives maximum).
• Filtrage intelligent : relancez uniquement en cas d’échecs relançables (ex. : erreurs réseau/émétteur, fonds insuffisants) ; ne relancez jamais après un refus catégorique.
• Prévention des tests de cartes : ne relancez pas les échecs comme DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Varier les métadonnées (facultatif) : si vous gérez votre propre système de relance, différenciez les relances via les métadonnées (ex. : retry_attempt).

​

Calendrier de réessai suggéré (abonnements)

• 1ère tentative : Immédiate lors de la création de la charge
• 2ème tentative : Après 3 jours
• 3ème tentative : Après 7 jours supplémentaires (10 jours au total)
• 4ème tentative (finale) : Après 7 jours supplémentaires (17 jours au total)

​

Évitez les réessais en rafale ; alignez-vous sur l’heure d’autorisation

• Ancrez les relances sur l’horodatage d’autorisation initial pour éviter un comportement de « rafale » sur votre portefeuille.
• Exemple : si le client commence un essai ou un mandat à 13h10 aujourd’hui, programmez les relances suivantes à 13h10 les jours suivants selon votre temporisation (ex. : +3 jours → 13h10, +7 jours → 13h10).
• Alternativement, si vous stockez l’heure du dernier paiement réussi T, programmez la tentative suivante à T + X days pour préserver l’alignement sur l’heure de la journée.

​

Codes de refus que vous ne devriez pas réessayer

• STOLEN_CARD
• DO_NOT_HONOR
• FRAUDULENT
• PICKUP_CARD
• AUTHENTICATION_FAILURE
• LOST_CARD

​

Directives de mise en œuvre (sans code)

• Utilisez un planificateur/une file d’attente qui conserve des horodatages précis ; calculez la prochaine tentative à l’heure exacte du jour (ex. : T + 3 days à la même HH:MM).
• Conservez et consultez l’heure du dernier paiement réussi T pour calculer la tentative suivante ; ne regroupez pas plusieurs abonnements au même instant.
• Évaluez toujours la raison du dernier refus ; arrêtez les relances pour les refus catégoriques figurant dans la liste ci-dessus.
• Limitez les relances simultanées par client et par compte pour éviter les pics accidentels.
• Communiquez de manière proactive : envoyez un e-mail/SMS au client pour mettre à jour son moyen de paiement avant la prochaine tentative programmée.
• Utilisez les métadonnées uniquement pour l’observabilité (ex. : retry_attempt) ; n’essayez jamais de « contourner » les systèmes de fraude/risque en faisant tourner des champs sans importance.

​

Suivre les résultats avec des webhooks

• subscription.active : Mandat autorisé et abonnement activé
• subscription.failed : Échec de la création (par exemple, échec du mandat)
• subscription.on_hold : Abonnement mis en attente (par exemple, état impayé)
• payment.succeeded : Charge réussie
• payment.failed : Échec de la charge

​

Tests et prochaines étapes

​

Dépannage

• 422 Requête invalide : assurez-vous que on_demand.mandate_only est fourni lors de la création et que product_price est fourni pour les prélèvements.
• Erreurs de devise : si vous remplacez product_currency, confirmez qu’elle est prise en charge pour votre compte et votre client.
• Aucun webhook reçu : vérifiez la configuration de votre URL de webhook et de votre secret de signature.