# L’API Payment Records Conservez un historique unifié de vos paiements, à la fois sur et en dehors de Stripe. Utilisez l’API [Payment Records](https://docs.stripe.com/api/payment-record.md) 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](https://docs.stripe.com/api/payment_intents.md) 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](https://docs.stripe.com/payments/orchestration.md) : - **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](https://docs.stripe.com/subscriptions.md) (avec relances intelligentes) et les [factures payées en dehors de Stripe](https://support.stripe.com/questions/marking-an-invoice-paid-out-of-band) 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 curl https://api.stripe.com/v1/payment_records/{{PAYMENTINTENT_ID}} \ -u "<>:" ``` ## 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](https://docs.stripe.com/api/payment-attempt-record.md), 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. Chaque PaymentAttemptRecord peut comporter plusieurs PaymentAttemptRecordEntries, chacune détaillant un événement unique au sein de cette tentative, tel que l’initiation, l’authentification, l’autorisation ou la capture. Ensemble, elles forment un journal d’événements en ajout seul que vous pouvez utiliser pour reconstituer l’intégralité du cycle de vie d’une tentative de paiement. Exemple de PaymentRecord avec PaymentAttemptRecords et PaymentAttemptRecordEntries (See full diagram at https://docs.stripe.com/payments/payment-records) ### Signaler un nouveau paiement Pour [signaler](https://docs.stripe.com/api/payment-record/report-payment/report.md) 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 curl https://api.stripe.com/v1/payment_records/report_payment \ -u "<>:" \ -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]={{PAYMENTMETHOD_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](https://docs.stripe.com/billing/revenue-recovery/smart-retries.md)). Si une tentative de paiement échoue, [signalez l’échec](https://docs.stripe.com/api/payment-record/report-payment-attempt-failed/report.md) en référençant l’ID du PaymentRecord existant et en transmettant l’heure de l’échec. ```curl curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt_failed \ -u "<>:" \ -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](https://docs.stripe.com/api/payment-record/report-payment-attempt/report.md) 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 curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt \ -u "<>:" \ -d initiated_at=1730253825 \ -d "payment_method_details[payment_method]={{PAYMENTMETHOD_ID}}" ``` ### Signaler un remboursement Si un paiement a été traité avec succès, mais qu’il a été remboursé par la suite (en totalité ou en partie), vous pouvez [signaler le remboursement](https://docs.stripe.com/api/payment-record/report-refund/report.md) pour maintenir des registres de paiement précis. Cela permet à Stripe de disposer d’une vue complète du cycle de vie des paiements, y compris les remboursements traités par votre prestataire de services de paiement. ```curl curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_refund \ -u "<>:" \ -d "processor_details[type]=custom" \ -d "processor_details[custom][refund_reference]=ref_123456" \ -d outcome=refunded \ -d "refunded[refunded_at]=1730253825" \ -d "amount[value]=1000" \ -d "amount[currency]=usd" ``` Si vous ne spécifiez pas de `montant`, la totalité du montant garanti est remboursée. Vous pouvez signaler plusieurs remboursements partiels sur le même PaymentRecord jusqu’à ce que le montant total soit remboursé. ## 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](https://docs.stripe.com/payments/payment-records.md#retrieve-payment-attempt-record). Pour les paiements antérieurs qui utilisent l’API Charges, utilisez l’ID Charge pour récupérer le PaymentAttemptRecord. ```curl curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}} \ -u "<>:" ``` ```json { "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 curl -G https://api.stripe.com/v1/payment_attempt_records \ -u "<>:" \ -d payment_record={{PAYMENT_RECORD_ID}} ``` ```json { "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, }] } ... ``` ### Récupérer le PaymentAttemptRecordEntry > Les PaymentAttemptRecordEntries sont actuellement limités aux utilisateurs en version bêta. Contactez votre chargé de compte Stripe ou l’équipe commerciale si vous souhaitez les tester. Stripe envoie un événement webhook contenant l’objet `PaymentAttemptRecordEntry` chaque fois qu’une entrée est créée (par exemple, payment_attempt_record_entry.initiated). Abonnez-vous à ces événements pour réagir en temps réel aux changements du cycle de vie des paiements. Pour afficher l’ensemble des PaymentAttemptRecordEntries d’une tentative de paiement donnée (par exemple, initiated, authorized et guaranteed), listez les PaymentAttemptRecordEntries à l’aide de l’ID du PaymentAttemptRecord : ```curl curl -G https://api.stripe.com/v1/payment_attempt_record_entries \ -u "<>:" \ -d payment_attempt_record={{PAYMENT_ATTEMPT_RECORD_ID}} ``` ```json { "object": "list", "data": [{ "id": "pare_4", "type": "guaranteed", "guaranteed": { "amount": { "value": 1099, "currency": "usd" } } }, { "id": "pare_3", "type": "authorized", "authorized": { "amount": { "value": 1099, "currency": "usd" } } }, { "id": "pare_2", "type": "authenticated", "authenticated": { "amount": { "value": 1099, "currency": "usd" } } }, { "id": "pare_1", "type": "initiated", "initiated": { "amount": { "value": 1099, "currency": "usd" }, "payment_method_details": { "type": "card" }, "processor_details": { "type": "processor_a" } } }] } ... ``` Vous pouvez également consulter vos paiements dans le [Dashboard](https://dashboard.stripe.com/payments).