The Payment Records API

Maintain a unified history of your payments, both on and off Stripe.

Use the Payment Records API to maintain a ledger of all your payments. If you’re processing payments through Stripe (on-Stripe payments) or integrating with third party processors (off-Stripe payments), use this API to keep a unified history of your payments.

The Payment Records API allows you to:

Make payments with a third-party processor, and report results back to Stripe to take advantage of the full functionality of products such as Subscriptions and Radar.
Create complex payment flows (such as multi-capture) where you can track each capture.
Track third-party and partner-initiated payments, including Stripe-instructed card transactions.

Relationship with PaymentIntents

The Payment Intents API manages a variety of payment flows. However, many advanced use cases require a more precise representation of payment history.

If your application accepts payments both on Stripe using PaymentIntents and off Stripe through another processor, you can use PaymentRecords as a complete system of record. If you’ve enabled Orchestration:

On-Stripe payments : Stripe automatically creates a PaymentRecord for each PaymentIntent.
Off-Stripe payments : You can manually create PaymentRecords by reporting payment data using the Payment Records API.

PaymentRecords enable interoperability across Stripe products. Products such as Subscriptions (with smart retries) and Invoices paid out of band use PaymentRecords as the core primitive for tracking payment outcomes.

To retrieve the PaymentRecord associated with a PaymentIntent that has Orchestration enabled:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Create and manage PaymentRecords

A PaymentRecord is the record of a payment, and includes all attempts and outcomes associated with it. It’s the primary reference point for understanding the lifecycle and status of a payment.

Each PaymentRecord can have multiple PaymentAttemptRecords, that each detail a specific attempt to process the payment. This structure allows you to track success, retries, and failures.

Each PaymentAttemptRecord can have multiple PaymentAttemptRecordEntries, that each detail a single event within that attempt, such as initiation, authentication, authorization, or capture. Together, they form an append-only event log you can use to reconstruct the full lifecycle of a payment attempt.

Report a new payment

To report an off-Stripe payment, create a PaymentRecord with details about the transaction, including the amount, payment method, processor, and relevant timestamps. Stripe automatically creates an associated PaymentAttemptRecord using the data provided, referenced as the latest_payment_attempt_record in the response.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Report a failed payment attempt

Reporting failed payment attempts makes sure Stripe has a complete view of your payment flows, enabling other products to function (for example, smart retries). If a payment attempt fails, report the failure by referencing the existing PaymentRecord ID and passing in the time of failure.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Retry failed payments

Sometimes users retry failed payments more than once. You can report a new payment attempt using the same PaymentRecord. Retries can use the same or different payment method and processor.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Report a refund

If a payment was successfully processed but later refunded (either fully or partially), you can report the refund to maintain accurate payment records. This ensures that Stripe has a complete view of the payment lifecycle, including any refunds processed through your payment processor.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

If you don’t specify an amount, the entire guaranteed amount is refunded. You can report multiple partial refunds on the same PaymentRecord until the full amount is refunded.

Understand the state of your payments

You can use the PaymentRecord for your dashboards and reporting systems. By having one record, you don’t need to reconcile the modeling differences between your other processors and Stripe.

Retrieve the PaymentRecord

You can retrieve the PaymentRecord using the ID. For orchestrated payments, this is returned in the PaymentIntent response. For historical payments made, you can also retrieve PaymentRecord using the ID of the PaymentIntent.

The latest PaymentAttemptRecord is available on the PaymentRecord and you can retrieve it using the Payment Attempt Records API. For historical payments that use the Charges API, use the Charge ID to retrieve the PaymentAttemptRecord.

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Example response

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

Retrieve the PaymentAttemptRecord

In cases where you have multiple payments attempts (for example, a payment failed on a different processor and was retried and succeeded on Stripe), the PaymentRecord includes the latest attempt under latest_payment_attempt_record. You can view all attempts by querying the PaymentAttemptRecord:

Command Line

Select a language

cURL

Stripe CLI

Ruby

Python

PHP

Java

Node.js

.NET

No results

Example response

{
 "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,
 }]
}
...

Retrieve the PaymentAttemptRecordEntry

Private preview

PaymentAttemptRecordEntries are currently limited to preview users. Contact your Stripe account representative or Sales if you’re interested in trying it out.

Distinguish canceled and failed Checkout attempts

For a Checkout Session that uses a custom payment method through Stripe’s PayPal adapter, use the PaymentAttemptRecordEntry objects associated with the Checkout Session’s payment_record to distinguish an abandoned checkout from a failed payment:

If the customer abandons the Checkout Session before entering the PayPal flow or leaves the session open until it expires, Stripe creates a canceled PaymentAttemptRecordEntry . If the session is still open, Stripe waits for it to expire before treating the attempt as abandoned.
If the customer enters the PayPal flow but returns to Checkout without approving the payment, Stripe creates a failed PaymentAttemptRecordEntry with failure _ details. code set to payment _ method _ customer _ decline .
If the customer attempts the payment but PayPal declines it, Stripe creates a failed PaymentAttemptRecordEntry with failure _ details. code set to payment _ method _ provider _ decline . Stripe uses this code for all PayPal declines, regardless of the specific reason.

Stripe sends a webhook event containing the PaymentAttemptRecordEntry object each time one is created (for example, payment_attempt_record_entry.initiated). Subscribe to these events to react to payment lifecycle changes in real time.

To view all of the PaymentAttemptRecordEntries within a particular payment attempt at once (for example, initiated, authorized, and guaranteed), list the PaymentAttemptRecordEntries using the ID of the PaymentAttemptRecord.

Command Line

cURL

Example response

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

You can also view your payments in the Dashboard.