L’API Payment Records

Utilisez l’API Payment Records pour tenir un registre de tous vos paiements. Si vous traitez des paiements avec Stripe (paiements sur Stripe) ou si vous intégrez des prestataires de services de paiement tiers (paiements hors Stripe), utilisez cette API pour conserver un historique complet de vos paiements.

L’API Payment Records vous permet de :

• Effectuer des paiements avec un autre prestataire de services de paiement et de communiquer les résultats à Stripe pour profiter de toutes les fonctionnalités offertes par des produits tels que Subscriptions et Radar.
• Créer des flux de paiement complexes (tels que la multicapture) dans lesquels vous pouvez suivre chaque capture.
• Suivre les paiements effectués par des tiers ou des partenaires, y compris les transactions par carte ordonnées par Stripe.

Relation avec PaymentIntents

L’API Payment Intents gère différents flux de paiement. Cependant, de nombreux cas d’usage avancés nécessitent une représentation plus précise de l’historique des paiements.

Si votre application accepte des paiements à la fois sur Stripe avec PaymentIntents et en dehors de Stripe via un autre prestataire de services de paiement, vous pouvez utiliser PaymentRecords comme un système d’enregistrement complet. Si vous avez activé Orchestration :

• Paiements sur Stripe : Stripe crée automatiquement un PaymentRecord pour chaque PaymentIntent.
• Paiements hors Stripe : Vous pouvez créer manuellement des PaymentRecords en déclarant les données de paiement à l’aide de l’API Payment Records.

PaymentRecords permet l’interopérabilité entre les produits Stripe. Des produits tels que les Subscriptions (avec relances intelligentes) et les factures payées en dehors de Stripe utilisent PaymentRecords comme principal élément de base pour le suivi des résultats des paiements.

Pour récupérer le PaymentRecord associé à un PaymentIntent pour lequel Orchestration est activée :

curl https://api.stripe.com/v1/payment_records/
{{PAYMENT_INTENT_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Créer et gérer des PaymentRecords

Un PaymentRecord est l’enregistrement d’un paiement et inclut toutes les tentatives et tous les résultats qui lui sont associés. Il s’agit du principal point de référence pour comprendre le cycle de vie et l’état d’un paiement.

Chaque PaymentRecord peut être associé à plusieurs PaymentAttemptRecords, qui présentent chacun une tentative spécifique de traitement du paiement. Cette structure vous permet de suivre les réussites, les relances et les échecs.

Signaler un nouveau paiement

Pour signaler un paiement hors Stripe, créez un objet PaymentRecord qui contient les informations relatives à la transaction, notamment le montant, le moyen de paiement, le prestataire de services de paiement et les horodatages pertinents. Stripe crée automatiquement un PaymentAttemptRecord associé à l’aide des données fournies, référencé en tant que latest_payment_attempt_record dans la réponse.

curl https://api.stripe.com/v1/payment_records/report_payment \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "amount_requested[currency]"=usd \
  -d "amount_requested[value]"=1000 \
  -d initiated_at=1730253453 \
  -d outcome=guaranteed \
  -d "guaranteed[guaranteed_at]"=1746572320 \
  -d "payment_method_details[payment_method]"=
"{{PAYMENT_METHOD_ID}}" \
  -d "processor_details[type]"=custom

Signaler l’échec d’une tentative de paiement

La notification de l’échec d’une tentative de paiement permet à Stripe d’avoir une vue complète de vos flux de paiement, ce qui permet à d’autres produits de fonctionner (par exemple, les relances intelligentes). Si une tentative de paiement échoue, signalez l’échec en référençant l’ID du PaymentRecord existant et en transmettant l’heure de l’échec.

curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt_failed \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d failed_at=1730253453

Relancer un paiement suite à un échec

Il arrive parfois que les utilisateurs tentent plus d’une fois d’effectuer un paiement suite à un échec. Vous pouvez signaler une nouvelle tentative de paiement en utilisant le même PaymentRecord. Les relances peuvent s’effectuer avec le même moyen de paiement et le même prestataire de services de paiement, ou avec d’autres.

curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d initiated_at=1730253825 \
  -d "payment_method_details[payment_method]"=
"{{PAYMENT_METHOD_ID}}"

Comprendre l’état de vos paiements

Vous pouvez utiliser le PaymentRecord pour vos dashboards et vos systèmes de reporting. En disposant d’un seul enregistrement, vous n’avez pas besoin de rapprocher les différences de modélisation entre vos autres prestataires de services de paiement et Stripe.

Récupérer le PaymentRecord

Vous pouvez récupérer le PaymentRecord à l’aide de l’ID. Pour les paiements avec Orchestration, celui-ci est renvoyé dans la réponse du PaymentIntent. Pour les paiements antérieurs, vous pouvez également récupérer le PaymentRecord à l’aide de l’ID du PaymentIntent.

Le dernier PaymentAttemptRecord est disponible sur le PaymentRecord et vous pouvez le récupérer à l’aide de l’API Payment Attempt Records. Pour les paiements antérieurs qui utilisent l’API Charges, utilisez l’ID Charge pour récupérer le PaymentAttemptRecord.

curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

{
  "processor_details": {
    "type": "processor_a",
  },
  "latest_payment_attempt_record": "{{PAYMENT_ATTEMPT_RECORD_ID}}",
  "amount_guaranteed": {
    "value": 10000,
    "currency": "usd",
  },
  "payment_method_details": {
    "payment_method": "{{PAYMENT_METHOD_ID}}",
    "type": "card",
  },
}
...

Récupérer le PaymentAttemptRecord

En cas de tentatives de paiement multiples (par exemple, un paiement a échoué avec un autre prestataire de services de paiement et a été relancé et a abouti avec Stripe), le PaymentRecord inclut la dernière tentative sous latest_payment_attempt_record. Vous pouvez afficher toutes les tentatives en interrogeant PaymentAttemptRecord :

curl -G https://api.stripe.com/v1/payment_attempt_records \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_record={{PAYMENT_RECORD_ID}}

{
  "object": "list",
  "data": [{
    "id": "par_124",
    "amount_requested": 10000,
    "amount_guaranteed": 10000,
    "amount_failed": 0,
  },
  {
    "id": "par_123",
    "amount_requested": 10000,
    "amount_guaranteed": 0,
    "amount_failed": 10000,
  }]
}
...

Vous pouvez également consulter vos paiements dans le Dashboard.