Core Resources
Payment Methods
Products
Checkout
Payment Links
Billing
Capital
Connect
Reserves
Fraud
Issuing
Terminal
Treasury
Payment Records
Entitlements
Sigma
Reporting
Financial Connections
Tax
Identity
Crypto
Climate
Forwarding
Webhooks

Payment Records 

A Payment Record is a resource that allows you to represent payments that occur on- or off-Stripe. For example, you can create a Payment Record to model a payment made on a different payment processor, in order to mark an Invoice as paid and a Subscription as active. Payment Records consist of one or more Payment Attempt Records, which represent individual attempts made on a payment network.

Endpoints

The Payment Record object 

Attributes

  • idstring

    Unique identifier for the object.

  • amountobject

    The amount you intend to collect for this payment.

  • amount_authorizedobject

    The portion of the requested amount that has been authorized to be guaranteed by the payment provider.

  • amount_canceledobject

    The portion of the requested amount that has been canceled by the user, or that you no longer intend to collect.

  • amount_failedobject

    The portion of the requested amount that failed to be collected.

  • amount_guaranteedobject

    The portion of the requested amount that has been guaranteed by the payment provider.

  • amount_refundedobject

    The amount that has been refunded to the customer on this payment.

  • amount_requestedobject

    The amount you initially requested for this payment.

  • customer_detailsnullable object

    Customer information for this payment.

  • customer_presencenullable enum

    Indicates whether the customer was present in your checkout flow during this payment.

    Possible enum values
    off_session

    The customer was not present during the transaction.

    on_session

    The customer was present during the transaction.

  • descriptionnullable string

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

  • payment_method_detailsnullable object

    Information about the Payment Method debited for this payment.

  • processor_detailsobject

    Processor information for this payment.

  • shipping_detailsnullable object

    Shipping information for this payment.

More attributes

  • objectstring

  • applicationnullable string

  • createdtimestamp

  • latest_payment_attempt_recordnullable string

  • livemodeboolean

The Payment Record object
{
  "id": "pr_5RV730PrHyAEi",
  "object": "payment_record",
  "amount_canceled": {
    "currency": "usd",
    "value": 0
  },
  "amount_failed": {
    "currency": "usd",
    "value": 0
  },
  "amount_guaranteed": {
    "currency": "usd",
    "value": 0
  },
  "amount_refunded": {
    "currency": "usd",
    "value": 0
  },
  "amount_requested": {
    "currency": "usd",
    "value": 1000
  },
  "created": 1730211363,
  "customer_details": null,
  "customer_presence": "on_session",
  "description": "computer software",
  "latest_payment_attempt_record": "par_1ArV730PrHyQuG",
  "livemode": true,
  "metadata": {},
  "payment_method_details": {
    "billing_details": null,
    "custom": {
      "display_name": "newpay",
      "type": "cpmt_125kjj3hn3sdf"
    },
    "payment_method": "pm_5j23kjksibjlks",
    "type": "custom"
  },
  "processor_details": {
    "type": "custom",
    "custom": {
      "payment_reference": "npp2358872734k"
    }
  },
  "shipping_details": null
}

Retrieve a Payment Record 

Retrieves a Payment Record with the given ID

Parameters

  • idstringRequired

    The ID of the Payment Record.

Returns

Returns a Payment Record object if a valid ID was provided. Otherwise, this call raises an error.

GET /v1/payment_records/:id
cURL
curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
  "id": "pr_5RV730PrHyAEi",
  "object": "payment_record",
  "amount_canceled": {
    "currency": "usd",
    "value": 0
  },
  "amount_failed": {
    "currency": "usd",
    "value": 0
  },
  "amount_guaranteed": {
    "currency": "usd",
    "value": 0
  },
  "amount_refunded": {
    "currency": "usd",
    "value": 0
  },
  "amount_requested": {
    "currency": "usd",
    "value": 1000
  },
  "created": 1730211363,
  "customer_details": null,
  "customer_presence": "on_session",
  "description": "computer software",
  "latest_payment_attempt_record": "par_1ArV730PrHyQuG",
  "livemode": true,
  "metadata": {},
  "payment_method_details": {
    "billing_details": null,
    "custom": {
      "display_name": "newpay",
      "type": "cpmt_125kjj3hn3sdf"
    },
    "payment_method": "pm_5j23kjksibjlks",
    "type": "custom"
  },
  "processor_details": {
    "type": "custom",
    "custom": {
      "payment_reference": "npp2358872734k"
    }
  },
  "shipping_details": null
}

Report payment attempt canceled 

Report that the most recent payment attempt on the specified Payment Record was canceled.

Parameters

  • canceled_attimestampRequired

    When the reported payment was canceled. Measured in seconds since the Unix epoch.

  • idstringRequired

    The ID of the Payment Record.

Returns

The updated Payment Record object with its most recent payment attempt canceled, or an error (for example, if the latest payment attempt is already guaranteed).

POST /v1/payment_records/:id/report_payment_attempt_canceled
curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi/report_payment_attempt_canceled \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d canceled_at=1730253453
Response
{
  "id": "pr_5RV730PrHyAEi",
  "object": "payment_record",
  "amount_canceled": {
    "currency": "usd",
    "value": 1000
  },
  "amount_failed": {
    "currency": "usd",
    "value": 0
  },
  "amount_guaranteed": {
    "currency": "usd",
    "value": 0
  },
  "amount_refunded": {
    "currency": "usd",
    "value": 0
  },
  "amount_requested": {
    "currency": "usd",
    "value": 1000
  },
  "created": 1730211363,
  "customer_details": null,
  "customer_presence": "on_session",
  "description": "computer software",
  "latest_payment_attempt_record": "par_1ArV730PrHyQuG",
  "livemode": true,
  "metadata": {},
  "payment_method_details": {
    "billing_details": null,
    "custom": {
      "display_name": "newpay",
      "type": "cpmt_125kjj3hn3sdf"
    },
    "payment_method": "pm_5j23kjksibjlks",
    "type": "custom"
  },
  "processor_details": {
    "type": "custom",
    "custom": {
      "payment_reference": "npp2358872734k"
    }
  },
  "shipping_details": null
}

Report payment attempt failed 

Report that the most recent payment attempt on the specified Payment Record failed or errored.

Parameters

  • failed_attimestampRequired

    When the reported payment failed. Measured in seconds since the Unix epoch.

  • idstringRequired

    The ID of the Payment Record.

Returns

The updated payment record object with its most recent payment attempt failed, or an error (for example, if the latest Payment Attempt Record is already guaranteed).

POST /v1/payment_records/:id/report_payment_attempt_failed
curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi/report_payment_attempt_failed \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d failed_at=1730253453
Response
{
  "id": "pr_5RV730PrHyAEi",
  "object": "payment_record",
  "amount_canceled": {
    "currency": "usd",
    "value": 0
  },
  "amount_failed": {
    "currency": "usd",
    "value": 1000
  },
  "amount_guaranteed": {
    "currency": "usd",
    "value": 0
  },
  "amount_refunded": {
    "currency": "usd",
    "value": 0
  },
  "amount_requested": {
    "currency": "usd",
    "value": 1000
  },
  "created": 1730211363,
  "customer_details": null,
  "customer_presence": "on_session",
  "description": "computer software",
  "latest_payment_attempt_record": "par_1ArV730PrHyQuG",
  "livemode": true,
  "metadata": {},
  "payment_method_details": {
    "billing_details": null,
    "custom": {
      "display_name": "newpay",
      "type": "cpmt_125kjj3hn3sdf"
    },
    "payment_method": "pm_5j23kjksibjlks",
    "type": "custom"
  },
  "processor_details": {
    "type": "custom",
    "custom": {
      "payment_reference": "npp2358872734k"
    }
  },
  "shipping_details": null
}