Stripe: Report a payment attempt

← Payment records operations · Get started

Operation stripe.postpaymentrecordsidreportpaymentattempt

Provider route: POST /v1/payment_records/{id}/report_payment_attempt. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { StripeIntegration } from "@alter-ai/stripe";

async function execute(input: Parameters<StripeIntegration["paymentRecords"]["postPaymentRecordsIdReportPaymentAttempt"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.paymentRecords.postPaymentRecordsIdReportPaymentAttempt(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_stripe import StripeIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.payment_records.post_payment_records_id_report_payment_attempt(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.id	string	Required within parent	Maximum length: 5000
headers	object	Optional	Additional keys: not allowed
headers.Idempotency-Key	string	Optional	Minimum length: 1 Maximum length: 255
body	object	Required within parent	Additional keys: not allowed
body.canceled	object	Optional	Information about the payment attempt cancelation.
body.canceled.canceled_at	integer	Required within parent	Format: unix-time
body.description	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.failed	object	Optional	Information about the payment attempt failure.
body.failed.failed_at	integer	Required within parent	Format: unix-time
body.guaranteed	object	Optional	Information about the payment attempt guarantee.
body.guaranteed.guaranteed_at	integer	Required within parent	Format: unix-time
body.initiated_at	integer	Required within parent	When the reported payment was initiated. Measured in seconds since the Unix epoch. Format: unix-time
body.metadata	JSON	Optional	Set of [key-value pairs](https://docs.stripe.com/api/metadata) 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`.
body.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.metadata (anyOf 1).*	string	Additional keys
body.metadata (anyOf 2)	string	Alternative	One of:
body.outcome	string	Optional	The outcome of the reported payment. One of: canceled, failed, guaranteed
body.payment_method_details	Model	Optional	Expand Report a payment — request body — body payment method details
body.shipping_details	object	Optional	Shipping information for this payment.
body.shipping_details.address	object	Optional
body.shipping_details.address.city	string	Optional	Maximum length: 5000
body.shipping_details.address.country	string	Optional	Maximum length: 5000
body.shipping_details.address.line1	string	Optional	Maximum length: 5000
body.shipping_details.address.line2	string	Optional	Maximum length: 5000
body.shipping_details.address.postal_code	string	Optional	Maximum length: 5000
body.shipping_details.address.state	string	Optional	Maximum length: 5000
body.shipping_details.name	string	Optional	Maximum length: 5000
body.shipping_details.phone	string	Optional

Referenced models: Report a payment — request body — body payment method details

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	Model	Root	Expand Report a refund — response body

Referenced models: Report a refund — response body

Schemas

706 more schemas are linked from the tables above, on the schema pages.

Report a refund — response body

Field	Type	Presence	Description and constraints
$	object	Root	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.
amount	Model	Required within parent	Expand Report a refund — response body — amount
amount_authorized	Model	Required within parent	Expand Report a refund — response body — amount
amount_canceled	Model	Required within parent	Expand Report a refund — response body — amount
amount_failed	Model	Required within parent	Expand Report a refund — response body — amount
amount_guaranteed	Model	Required within parent	Expand Report a refund — response body — amount
amount_refunded	Model	Required within parent	Expand Report a refund — response body — amount
amount_requested	Model	Required within parent	Expand Report a refund — response body — amount
application	JSON	Optional
application (anyOf 1)	string	Alternative	ID of the Connect application that created the PaymentRecord. Maximum length: 5000
application (anyOf 2)	null	Alternative
created	JSON	Required within parent
created (anyOf 1)	integer	Alternative	Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time
created (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
customer_details	JSON	Optional
customer_details (anyOf 1)	JSON	Alternative	Customer information for this payment.
customer_details (anyOf 1) (anyOf 1)	Model	Alternative	Expand Report a refund — response body — customer details Customer information for this payment Information about the customer for this payment
customer_details (anyOf 2)	null	Alternative
customer_presence	JSON	Optional
customer_presence (anyOf 1)	string	Alternative	Indicates whether the customer was present in your checkout flow during this payment. Known values: off_session, on_session
customer_presence (anyOf 2)	null	Alternative
description	JSON	Optional
description (anyOf 1)	string	Alternative	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 5000
description (anyOf 2)	null	Alternative
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
latest_payment_attempt_record	JSON	Optional
latest_payment_attempt_record (anyOf 1)	string	Alternative	ID of the latest Payment Attempt Record attached to this Payment Record. Maximum length: 5000
latest_payment_attempt_record (anyOf 2)	null	Alternative
livemode	boolean	Required within parent	If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
metadata	object	Required within parent	Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field
metadata.*	string	Additional keys	Maximum length: 500
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: payment_record
payment_method_details	JSON	Optional
payment_method_details (anyOf 1)	JSON	Alternative	Information about the Payment Method debited for this payment.
payment_method_details (anyOf 1) (anyOf 1)	Model	Alternative	Expand Report a refund — response body — payment method details value ach credit transfer, ach debit, acss debit, affirm, afterpay clearpay, alipay, alma, amazon pay, au becs debit, bacs debit, bancontact, billie, billing details, bizum, blik, boleto, card, card present, cashapp, crypto, custom, customer balance, eps, fpx, giropay, grabpay, ideal, interac present, kakao pay, klarna, konbini, kr card, link, mb way, mobilepay, momo, multibanco, naver pay, nz bank account, oxxo, p24, pay by bank, payco, payment method, paynow, paypal, paypay, payto, pix, promptpay, revolut pay, samsung pay, satispay, scalapay, sepa debit, sequra, sofort, stripe account, sunbit, swish, twint, type, upi, us bank account, wechat, wechat pay, zip
payment_method_details (anyOf 2)	null	Alternative
processor_details	Model	Required within parent	Expand Report a refund — response body — processor details
reported_by	string	Required within parent	Indicates who reported the payment. Known values: self, stripe
shipping_details	JSON	Optional
shipping_details (anyOf 1)	JSON	Alternative	Shipping information for this payment.
shipping_details (anyOf 1) (anyOf 1)	Model	Alternative	Expand Report a refund — response body — shipping details Shipping information for this payment address, name, phone
shipping_details (anyOf 2)	null	Alternative

Referenced models: Report a refund — response body — amount, Report a refund — response body — customer details Customer information for this payment Information about the customer for this payment, Report a refund — response body — payment method details value ach credit transfer, ach debit, acss debit, affirm, afterpay clearpay, alipay, alma, amazon pay, au becs debit, bacs debit, bancontact, billie, billing details, bizum, blik, boleto, card, card present, cashapp, crypto, custom, customer balance, eps, fpx, giropay, grabpay, ideal, interac present, kakao pay, klarna, konbini, kr card, link, mb way, mobilepay, momo, multibanco, naver pay, nz bank account, oxxo, p24, pay by bank, payco, payment method, paynow, paypal, paypay, payto, pix, promptpay, revolut pay, samsung pay, satispay, scalapay, sepa debit, sequra, sofort, stripe account, sunbit, swish, twint, type, upi, us bank account, wechat, wechat pay, zip, Report a refund — response body — processor details, Report a refund — response body — shipping details Shipping information for this payment address, name, phone

Report a payment — request body — body payment method details

Field	Type	Presence	Description and constraints
$	object	Root	Information about the Payment Method debited for this payment.
billing_details	object	Optional
billing_details.address	object	Optional
billing_details.address.city	string	Optional	Maximum length: 5000
billing_details.address.country	string	Optional	Maximum length: 5000
billing_details.address.line1	string	Optional	Maximum length: 5000
billing_details.address.line2	string	Optional	Maximum length: 5000
billing_details.address.postal_code	string	Optional	Maximum length: 5000
billing_details.address.state	string	Optional	Maximum length: 5000
billing_details.email	string	Optional
billing_details.name	string	Optional	Maximum length: 5000
billing_details.phone	string	Optional
custom	object	Optional
custom.display_name	string	Optional	Maximum length: 5000
custom.type	string	Optional	Maximum length: 5000
payment_method	string	Optional	Maximum length: 5000
type	string	Optional	One of: custom

Report a refund — response body — amount

Field	Type	Presence	Description and constraints
$	object	Root	A representation of an amount of money, consisting of an amount and a currency.
currency	string	Required within parent	Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies). Format: currency
value	JSON	Required within parent
value (anyOf 1)	integer	Alternative	A positive integer representing the amount in the currency's [minor unit](https://docs.stripe.com/currencies#zero-decimal). For example, `100` can represent 1 USD or 100 JPY.
value (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$

Report a refund — response body — customer details Customer information for this payment Information about the customer for this payment

Field	Type	Presence	Description and constraints
$	object	Root	Information about the customer for this payment.
customer	JSON	Optional
customer (anyOf 1)	string	Alternative	ID of the Stripe Customer associated with this payment. Maximum length: 5000
customer (anyOf 2)	null	Alternative
email	JSON	Optional
email (anyOf 1)	string	Alternative	The customer's email address. Maximum length: 5000
email (anyOf 2)	null	Alternative
name	JSON	Optional
name (anyOf 1)	string	Alternative	The customer's name. Maximum length: 5000
name (anyOf 2)	null	Alternative
phone	JSON	Optional
phone (anyOf 1)	string	Alternative	The customer's phone number. Maximum length: 5000
phone (anyOf 2)	null	Alternative

Policy, approvals and errors

SDK function policy ID: stripe.postpaymentrecordsidreportpaymentattempt. Catalog operation: PostPaymentRecordsIdReportPaymentAttempt. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Pinned headers: {"Stripe-Version": "2026-09-30.endive"}

Official provider source