Report a payment

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 currency’s minor unit. For example, 100 can represent 1 USD or 100 JPY.

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

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.

processor_detailsobjectRequired
Processor information for this payment.
- processor_details.typeenumRequired
  The type of the processor details. An additional hash is included on processor_details with a name matching this value. It contains additional information specific to the processor.
  Possible enum values
  custom
  A custom payment processor that is not included in Stripe’s standard processor types. This allows you to report payments processed through external payment processors or custom integrations.
- processor_details.customobject
  Information about the custom processor used to make this payment.
  processor_details.custom.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, 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 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:" \
  -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_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,
  "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 a payment

Parameters

amount_requestedobjectRequired

amount_requested.currencyenumRequired

amount_requested.valueintegerRequired

initiated_attimestampRequired

payment_method_detailsobjectRequired

payment_method_details.billing_detailsobject

payment_method_details.billing_details.addressobject

payment_method_details.billing_details.address.citystring

payment_method_details.billing_details.address.countrystring

payment_method_details.billing_details.address.line1string

payment_method_details.billing_details.address.line2string

payment_method_details.billing_details.address.postal_codestring

payment_method_details.billing_details.address.statestring

payment_method_details.billing_details.emailstring

payment_method_details.billing_details.namestring

payment_method_details.billing_details.phonestring

payment_method_details.customobject

payment_method_details.custom.display_namestring

payment_method_details.custom.typestring

payment_method_details.payment_methodstringRequired unless type is provided

payment_method_details.typeenumRequired unless payment_method is provided

customer_detailsobject

customer_details.customerstring

customer_details.emailstring

customer_details.namestring

customer_details.phonestring

customer_presenceenum

descriptionstring

failedobject

failed.failed_attimestampRequired

guaranteedobject

guaranteed.guaranteed_attimestampRequired

metadataobject

outcomeenum

processor_detailsobjectRequired

processor_details.typeenumRequired

processor_details.customobject

processor_details.custom.payment_referencestringRequired

shipping_detailsobject

shipping_details.addressobject

shipping_details.address.citystring

shipping_details.address.countrystring

shipping_details.address.line1string

shipping_details.address.line2string

shipping_details.address.postal_codestring

shipping_details.address.statestring

shipping_details.namestring

shipping_details.phonestring

Returns