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

Report a payment 

Payment Records
Payment Records
Report a payment

Report a new Payment Record. You may report a Payment Record as it is initialized and later report updates through the other report_* methods, or report Payment Records in a terminal state directly, through this method.

Parameters

  • amount_requestedobjectRequired

    The amount you initially requested for this payment.

    • amount_requested.currencyenumRequired

      Three-letter ISO currency code, in lowercase. Must be a supported currency.

    • amount_requested.valueintegerRequired

      A positive integer representing the amount in the smallest currency unit for example, 100 cents for 1 USD or 100 for 100 JPY, a zero-decimal currency.

  • initiated_attimestampRequired

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

  • payment_method_detailsobjectRequired

    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 (e.g., street, PO Box, or company name).

        • payment_method_details.billing_details.address.line2string

          Address line 2 (e.g., 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.

  • customer_detailsobject

    Customer information for this payment.

    • customer_details.customerstring

      The customer who made the payment.

    • customer_details.emailstring

      The customer’s phone number.

    • customer_details.namestring

      The customer’s name.

    • customer_details.phonestring

      The customer’s phone number.

  • customer_presenceenum

    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.

  • 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_referencestringRequired

    An opaque string for manual reconciliation of this payment, for example a check number or a payment processor ID.

  • 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 (e.g., street, PO Box, or company name).

      • shipping_details.address.line2string

        Address line 2 (e.g., 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 newly created Payment Record.

POST /v1/payment_records/report_payment
curl https://api.stripe.com/v1/payment_records/report_payment \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -H "Stripe-Version: 2025-03-31.basil" \
  -d "amount_requested[currency]"=usd \
  -d "amount_requested[value]"=1000 \
  -d customer_presence=on_session \
  -d description="computer software" \
  -d initiated_at=1730253453 \
  -d payment_reference=npp2358872734k \
  -d "payment_method_details[custom][display_name]"=newpay \
  -d "payment_method_details[custom][type]"=cpmt_125kjj3hn3sdf \
  -d "payment_method_details[payment_method]"=pm_5j23kjksibjlks \
  -d "payment_method_details[type]"=custom
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,
  "payment_method_details": {
    "billing_details": null,
    "custom": {
      "display_name": "newpay",
      "type": "cpmt_125kjj3hn3sdf"
    },
    "payment_method": "pm_5j23kjksibjlks",
    "type": "custom"
  },
  "payment_reference": "npp2358872734k",
  "shipping_details": null
}