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
}

Report payment attempt guaranteed

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

Parameters

guaranteed_attimestampRequired
When the reported payment was guaranteed. 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 guaranteed, or an error (for example, if the latest Payment Attempt Record is already guaranteed).

POST /v1/payment_records/:id/report_payment_attempt_guaranteed

curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi/report_payment_attempt_guaranteed \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d guaranteed_at=1730253453

Response

{
  "id": "pr_5RV730PrHyAEi",
  "object": "payment_record",
  "amount_canceled": {
    "currency": "usd",
    "value": 0
  },
  "amount_failed": {
    "currency": "usd",
    "value": 0
  },
  "amount_guaranteed": {
    "currency": "usd",
    "value": 1000
  },
  "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 informational

Report informational updates on the specified Payment Record.

Parameters

idstringRequired
The ID of the Payment Record.

customer_detailsobject
Customer information for this payment.

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

shipping_detailsobject
Shipping information for this payment.

Returns

The updated Payment Record object.

POST /v1/payment_records/:id/report_payment_attempt_informational

curl https://api.stripe.com/v1/payment_records/pr_5RV730PrHyAEi/report_payment_attempt_informational \
  -u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
  -d description="Updated payment description with additional context" \
  -d "metadata[order_id]"=order_12345 \
  -d "metadata[updated_by]"=customer_service \
  -d "metadata[update_reason]"=customer_inquiry \
  -d "customer_details[name]"="Jenny Rosen" \
  --data-urlencode "customer_details[email]"="jenny.rosen@example.com" \
  --data-urlencode "customer_details[phone]"="+15551234567" \
  -d "shipping_details[name]"="Jenny Rosen" \
  -d "shipping_details[address][line1]"="123 Main Street" \
  -d "shipping_details[address][line2]"="Apt 4B" \
  -d "shipping_details[address][city]"="San Francisco" \
  -d "shipping_details[address][state]"=CA \
  -d "shipping_details[address][postal_code]"=94111 \
  -d "shipping_details[address][country]"=US

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": {
    "name": "Jenny Rosen",
    "email": "jenny.rosen@example.com",
    "phone": "+15551234567"
  },
  "customer_presence": "on_session",
  "description": "Updated payment description with additional context",
  "latest_payment_attempt_record": "par_1ArV730PrHyQuG",
  "livemode": true,
  "metadata": {
    "order_id": "order_12345",
    "updated_by": "customer_service",
    "update_reason": "customer_inquiry"
  },
  "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": {
    "name": "Jenny Rosen",
    "address": {
      "line1": "123 Main Street",
      "line2": "Apt 4B",
      "city": "San Francisco",
      "state": "CA",
      "postal_code": "94111",
      "country": "US"
    }
  }
}

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.

guaranteedobject
Information about the payment attempt guarantee.

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.

shipping_detailsobject
Shipping information for this payment.

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
}

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.

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.

customer_detailsobject
Customer information for this payment.

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.

guaranteedobject
Information about the payment attempt guarantee.

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.

shipping_detailsobject
Shipping information for this payment.

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
}

Need help? Contact Support.
Check out our changelog.
Questions? Contact Sales.
LLM? Read llms.txt.
Powered by Markdoc

Report payment attempt failed

Parameters

failed_attimestampRequired

idstringRequired

Returns

Report payment attempt guaranteed

Parameters

guaranteed_attimestampRequired

idstringRequired

Returns

Report payment attempt informational

Parameters

idstringRequired

customer_detailsobject

descriptionstring

metadataobject

shipping_detailsobject

Returns

Report a payment attempt

Parameters

idstringRequired

initiated_attimestampRequired

descriptionstring

failedobject

guaranteedobject

metadataobject

outcomeenum

payment_method_detailsobject

shipping_detailsobject

Returns

Report a payment

Parameters

amount_requestedobjectRequired

initiated_attimestampRequired

payment_method_detailsobjectRequired

customer_detailsobject

customer_presenceenum

descriptionstring

failedobject

guaranteedobject

metadataobject

outcomeenum

processor_detailsobjectRequired

shipping_detailsobject

Returns