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 une méthode de paiement et éventuellement collecter une charge initiale.
2. Plus tard, vous créez des charges contre cet abonnement avec des montants personnalisés en utilisant le point de terminaison de charge dédié.
3. Vous écoutez les webhooks (par exemple, 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 retour en arrière : Utilisez un retour en arrière exponentiel entre les réessais.
• Limites de réessai : Limitez le nombre total de réessais (3 à 4 tentatives maximum).
• Filtrage intelligent : Réessayez uniquement en cas d’échecs réessayables (par exemple, erreurs réseau/émetteur, fonds insuffisants) ; ne réessayez jamais les refus fermes.
• Prévention des tests de carte : Ne réessayez pas les échecs tels que DO_NOT_HONOR, STOLEN_CARD, LOST_CARD, PICKUP_CARD, FRAUDULENT, AUTHENTICATION_FAILURE.
• Varier les métadonnées (optionnel) : Si vous maintenez votre propre système de réessai, différenciez les réessais via des métadonnées (par exemple, 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 réessais à l’horodatage d’autorisation original pour éviter un comportement de “rafale” dans votre portefeuille.
• Exemple : Si le client commence un essai ou un mandat à 13h10 aujourd’hui, planifiez les réessais de suivi à 13h10 les jours suivants selon votre retour en arrière (par exemple, +3 jours → 13h10, +7 jours → 13h10).
• Alternativement, si vous stockez l’heure du dernier paiement réussi T, planifiez la prochaine tentative à T + X days pour préserver l’alignement de 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 persiste des horodatages précis ; calculez la prochaine tentative à l’heure exacte de décalage (par exemple, T + 3 days à la même HH:MM).
• Maintenez et référencez l’horodatage du dernier paiement réussi T pour calculer la prochaine tentative ; ne regroupez pas plusieurs abonnements au même instant.
• Évaluez toujours la dernière raison de refus ; arrêtez les réessais pour les refus fermes dans la liste à ignorer ci-dessus.
• Limitez les réessais simultanés par client et par compte pour éviter des pics accidentels.
• Communiquez de manière proactive : envoyez un e-mail/SMS au client pour mettre à jour sa méthode de paiement avant la prochaine tentative prévue.
• Utilisez les métadonnées uniquement pour l’observabilité (par exemple, retry_attempt) ; n’essayez jamais de “contourner” les systèmes de fraude/de risque en faisant tourner des champs sans conséquence.

​

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 charges.
• Erreurs de devise : Si vous surchargez product_currency, confirmez qu’elle est prise en charge pour votre compte et votre client.
• Aucun webhook reçu : Vérifiez votre URL de webhook et la configuration du secret de signature.