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

Report a payment attempt 

Payment Records
Payment Records
Report a payment attempt

Report a new payment attempt on the specified Payment Record. A new payment attempt can only be specified if all other payment attempts are canceled or failed.

Parameters

  • idstringRequired

    The ID of the Payment Record.

  • initiated_attimestampRequired

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

  • descriptionstring

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

  • failedobject

    Information about the payment attempt failure.

    • failed.failed_attimestampRequired

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

  • guaranteedobject

    Information about the payment attempt guarantee.

    • guaranteed.guaranteed_attimestampRequired

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

  • 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. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

  • outcomeenum

    The outcome of the reported payment.

    Possible enum values
    failed

    The payment failed.

    guaranteed

    The payment was guaranteed.

  • payment_method_detailsobject

    Information about the Payment Method debited for this payment.

    • payment_method_details.billing_detailsobject

      The billing details associated with the method of payment.

      • payment_method_details.billing_details.addressobject

        The billing address associated with the method of payment.

        • payment_method_details.billing_details.address.citystring

          City, district, suburb, town, or village.

        • payment_method_details.billing_details.address.countrystring

          Two-letter country code (ISO 3166-1 alpha-2).

        • payment_method_details.billing_details.address.line1string

          Address line 1, such as the street, PO Box, or company name.

        • payment_method_details.billing_details.address.line2string

          Address line 2, such as the apartment, suite, unit, or building.

        • payment_method_details.billing_details.address.postal_codestring

          ZIP or postal code.

        • payment_method_details.billing_details.address.statestring

          State, county, province, or region.

      • payment_method_details.billing_details.emailstring

        The billing email associated with the method of payment.

      • payment_method_details.billing_details.namestring

        The billing name associated with the method of payment.

      • payment_method_details.billing_details.phonestring

        The billing phone number associated with the method of payment.

    • payment_method_details.customobject

      Information about the custom (user-defined) payment method used to make this payment.

      • payment_method_details.custom.display_namestring

        Display name for the custom (user-defined) payment method type used to make this payment.

      • payment_method_details.custom.typestring

        The custom payment method type associated with this payment.

    • payment_method_details.payment_methodstringRequired unless type is provided

      ID of the Stripe Payment Method used to make this payment.

    • payment_method_details.typeenumRequired unless payment_method is provided

      The type of the payment method details. An additional hash is included on the payment_method_details with a name matching this value. It contains additional information specific to the type.

      Possible enum values
      custom

      A custom payment method that is not included in Stripe’s standard payment method types. This allows you to report payments processed through external payment processors or custom integrations.

  • shipping_detailsobject

    Shipping information for this payment.

    • shipping_details.addressobject

      The physical shipping address.

      • shipping_details.address.citystring

        City, district, suburb, town, or village.

      • shipping_details.address.countrystring

        Two-letter country code (ISO 3166-1 alpha-2).

      • shipping_details.address.line1string

        Address line 1, such as the street, PO Box, or company name.

      • shipping_details.address.line2string

        Address line 2, such as the apartment, suite, unit, or building.

      • shipping_details.address.postal_codestring

        ZIP or postal code.

      • shipping_details.address.statestring

        State, county, province, or region.

    • shipping_details.namestring

      The shipping recipient’s name.

    • shipping_details.phonestring

      The shipping recipient’s phone number.

Returns

The updated Payment Record object with a new latest_payment_attempt_record, or an error (for example, if the Payment Record already has funds guaranteed).

POST /v1/payment_records/:id/report_payment_attempt
curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi/report_payment_attempt \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d initiated_at=1730253425
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_345kjsi8WE",
  "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
}