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:

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

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.

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.

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

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.

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

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.

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}}"

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.

curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_refund \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -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

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.

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

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:

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

You can also view your payments in the Dashboard.