Stripe: Create a Payment Intent

← Payment intents operations · Get started

Operation stripe.postpaymentintents

Provider route: POST /v1/payment_intents. 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["paymentIntents"]["postPaymentIntents"]>[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.paymentIntents.postPaymentIntents(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_intents.post_payment_intents(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
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.allowed_payment_method_types	array	Optional	The list of payment method types allowed for use with this payment. Stripe automatically returns compatible payment methods from this list in the `payment_method_types` field of the response, based on the other PaymentIntent parameters, such as `currency`, `amount`, and `customer`.
body.allowed_payment_method_types[]	string	Each item	One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boku_promptpay, boleto, capchase_pay, card, card_present, cashapp, check_scan, click_to_pay, crypto, customer_balance, demo_pay, duitnow, dummy_auth_push, dummy_passthrough_card, edenred, eps, fpx, gcash, getbalance, gift_card, giropay, gopay, grabpay, id_bank_transfer, ideal, interac_present, kakao_pay, klarna, knet, konbini, kr_card, kr_market, kriya, link, mb_way, mobilepay, momo, mondu, multibanco, naver_pay, netbanking, ng_bank, ng_bank_transfer, ng_card, ng_market, ng_ussd, ng_wallet, nz_bank_account, octopus, oxxo, p24, paper_check, pay_by_bank, payco, paynow, paypal, paypay, payto, pix, promptpay, qris, rechnung, revolut_pay, samsung_pay, satispay, scalapay, sepa_debit, sequra, shop_pay, shopeepay, sofort, south_korea_market, stripe_balance, sunbit, swish, tamara, test_pay, touch_n_go, truemoney, twint, upi, us_bank_account, us_cash_voucher, vipps, wechat_pay, wero, zip
body.amount	integer	Required within parent	Amount intended to be collected by this PaymentIntent. A positive integer representing how much to charge in the [smallest currency unit](https://docs.stripe.com/currencies#zero-decimal) (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). The minimum amount is $0.50 US or [equivalent in charge currency](https://docs.stripe.com/currencies#minimum-and-maximum-charge-amounts). The amount value supports up to eight digits (e.g., a value of 99999999 for a USD charge of $999,999.99).
body.amount_details	Model	Optional	Expand Create a Payment Intent — request body — body amount details
body.application_fee_amount	integer	Optional	The amount of the application fee (if any) that will be requested to be applied to the payment and transferred to the application owner’s Stripe account. The amount of the application fee collected will be capped at the total amount captured. For more information, see the PaymentIntents [use case for connected accounts](https://docs.stripe.com/payments/connected-accounts).
body.automatic_payment_methods	object	Optional	When you enable this parameter, this PaymentIntent accepts payment methods that you enable in the Dashboard and that are compatible with this PaymentIntent’s other parameters.
body.automatic_payment_methods.allow_redirects	string	Optional	One of: always, never
body.automatic_payment_methods.enabled	boolean	Required within parent
body.capture_method	string	Optional	Controls when the funds will be captured from the customer’s account. One of: automatic, automatic_async, manual
body.confirm	boolean	Optional	Set to `true` to attempt to [confirm this PaymentIntent](https://docs.stripe.com/api/payment_intents/confirm) immediately. This parameter defaults to `false`. When creating and confirming a PaymentIntent at the same time, you can also provide the parameters available in the [Confirm API](https://docs.stripe.com/api/payment_intents/confirm).
body.confirmation_method	string	Optional	Describes whether we can confirm this PaymentIntent automatically, or if it requires customer action to confirm the payment. One of: automatic, manual
body.confirmation_token	string	Optional	ID of the ConfirmationToken used to confirm this PaymentIntent. If the provided ConfirmationToken contains properties that are also being provided in this request, such as `payment_method`, then the values in this request will take precedence. Maximum length: 5000
body.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
body.customer	string	Optional	ID of the Customer this PaymentIntent belongs to, if one exists. Payment methods attached to other Customers cannot be used with this PaymentIntent. If [setup_future_usage](https://docs.stripe.com/api#payment_intent_object-setup_future_usage) is set and this PaymentIntent’s payment method is not `card_present`, then the payment method attaches to the Customer after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is `card_present` and isn’t a digital wallet, then a [generated_card](https://docs.stripe.com/api/charges/object#charge_object-payment_method_details-card_present-generated_card) payment method representing the card is created and attached to the Customer instead. Maximum length: 5000
body.customer_account	string	Optional	ID of the Account representing the customer that this PaymentIntent belongs to, if one exists. Payment methods attached to other Accounts cannot be used with this PaymentIntent. If [setup_future_usage](https://docs.stripe.com/api#payment_intent_object-setup_future_usage) is set and this PaymentIntent’s payment method is not `card_present`, then the payment method attaches to the Account after the PaymentIntent has been confirmed and any required actions from the user are complete. If the payment method is `card_present` and isn’t a digital wallet, then a [generated_card](https://docs.stripe.com/api/charges/object#charge_object-payment_method_details-card_present-generated_card) payment method representing the card is created and attached to the Account instead. Maximum length: 5000
body.description	string	Optional	An arbitrary string attached to the object. Often useful for displaying to users. Maximum length: 1000
body.error_on_requires_action	boolean	Optional	Set to `true` to fail the payment attempt if the PaymentIntent transitions into `requires_action`. Use this parameter for simpler integrations that don’t handle customer actions, such as [saving cards without authentication](https://docs.stripe.com/payments/save-card-without-authentication). This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm).
body.excluded_payment_method_types	array	Optional	The list of payment method types to exclude from use with this payment.
body.excluded_payment_method_types[]	string	Each item	One of: acss_debit, affirm, afterpay_clearpay, alipay, alma, amazon_pay, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boleto, card, cashapp, crypto, customer_balance, eps, fpx, giropay, grabpay, ideal, kakao_pay, klarna, konbini, kr_card, mb_way, mobilepay, multibanco, naver_pay, nz_bank_account, oxxo, p24, pay_by_bank, payco, paynow, paypal, paypay, payto, pix, promptpay, revolut_pay, samsung_pay, satispay, scalapay, sepa_debit, sequra, sofort, sunbit, swish, twint, upi, us_bank_account, wechat_pay, zip
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.hooks	object	Optional	Automations to be run during the PaymentIntent lifecycle
body.hooks.inputs	object	Optional
body.hooks.inputs.tax	object	Optional
body.hooks.inputs.tax.calculation	JSON	Required within parent
body.hooks.inputs.tax.calculation (anyOf 1)	string	Alternative	Maximum length: 5000
body.hooks.inputs.tax.calculation (anyOf 2)	string	Alternative	One of:
body.mandate	string	Optional	ID of the mandate that’s used for this payment. This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm). Maximum length: 5000
body.mandate_data	JSON	Optional	This hash contains details about the Mandate to create. This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm).
body.mandate_data (anyOf 1)	Model	Alternative	Expand Create a Setup Intent — request body — body mandate data customer acceptance
body.mandate_data (anyOf 2)	string	Alternative	One of:
body.metadata	object	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`. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.off_session	JSON	Optional	Set to `true` to indicate that the customer isn’t in your checkout flow during this payment attempt and can’t authenticate. Use this parameter in scenarios where you collect payment method details and [charge them later](https://docs.stripe.com/payments/save-during-payment). This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm).
body.off_session (anyOf 1)	boolean	Alternative
body.off_session (anyOf 2)	string	Alternative	One of: one_off, recurring Maximum length: 5000
body.on_behalf_of	string	Optional	The Stripe account ID that these funds are intended for. Learn more about the [use case for connected accounts](https://docs.stripe.com/payments/connected-accounts).
body.payment_details	object	Optional	Provides industry-specific information about the charge.
body.payment_details.customer_reference	JSON	Optional
body.payment_details.customer_reference (anyOf 1)	string	Alternative	Maximum length: 5000
body.payment_details.customer_reference (anyOf 2)	string	Alternative	One of:
body.payment_details.order_reference	JSON	Optional
body.payment_details.order_reference (anyOf 1)	string	Alternative	Maximum length: 5000
body.payment_details.order_reference (anyOf 2)	string	Alternative	One of:
body.payment_method	string	Optional	ID of the payment method (a PaymentMethod, Card, or [compatible Source](https://docs.stripe.com/payments/payment-methods/transitioning#compatibility) object) to attach to this PaymentIntent. If you omit this parameter with `confirm=true`, `customer.default_source` attaches as this PaymentIntent’s payment instrument to improve migration for users of the Charges API. We recommend that you explicitly provide the `payment_method` moving forward. If the payment method is attached to a Customer, you must also provide the ID of that Customer as the [customer](https://docs.stripe.com/api#create_payment_intent-customer) parameter of this PaymentIntent. Maximum length: 5000
body.payment_method_configuration	string	Optional	The ID of the [payment method configuration](https://docs.stripe.com/api/payment_method_configurations) to use with this PaymentIntent. Maximum length: 100
body.payment_method_data	Model	Optional	Expand Create a Payment Intent — request body — body payment method data
body.payment_method_options	Model	Optional	Expand Create a Payment Intent — request body — body payment method options
body.radar_options	object	Optional	Options to configure Radar. Learn more about [Radar Sessions](https://docs.stripe.com/radar/radar-session).
body.radar_options.referrer	JSON	Optional
body.radar_options.referrer (anyOf 1)	string	Alternative	Maximum length: 5000
body.radar_options.referrer (anyOf 2)	string	Alternative	One of:
body.radar_options.session	string	Optional	Maximum length: 5000
body.receipt_email	string	Optional	Email address to send the receipt to. If you specify `receipt_email` for a payment in live mode, you send a receipt regardless of your [email settings](https://dashboard.stripe.com/account/emails).
body.return_url	string	Optional	The URL to redirect your customer back to after they authenticate or cancel their payment on the payment method’s app or site. If you’d prefer to redirect to a mobile application, you can alternatively supply an application URI scheme. This parameter can only be used with [`confirm=true`](https://docs.stripe.com/api/payment_intents/create#create_payment_intent-confirm).
body.setup_future_usage	string	Optional	Indicates that you intend to make future payments with this PaymentIntent’s payment method. If you provide a Customer with the PaymentIntent, you can use this parameter to [attach the payment method](/payments/save-during-payment) to the Customer after the PaymentIntent is confirmed and the customer completes any required actions. If you don’t provide a Customer, you can still [attach](/api/payment_methods/attach) the payment method to a Customer after the transaction completes. If the payment method is `card_present` and isn’t a digital wallet, Stripe creates and attaches a [generated_card](/api/charges/object#charge_object-payment_method_details-card_present-generated_card) payment method representing the card to the Customer instead. When processing card payments, Stripe uses `setup_future_usage` to help you comply with regional legislation and network rules, such as [SCA](/strong-customer-authentication). One of: off_session, on_session
body.shipping	object	Optional	Shipping information for this PaymentIntent.
body.shipping.address	object	Required within parent
body.shipping.address.city	string	Optional	Maximum length: 5000
body.shipping.address.country	string	Optional	Maximum length: 5000
body.shipping.address.line1	string	Optional	Maximum length: 5000
body.shipping.address.line2	string	Optional	Maximum length: 5000
body.shipping.address.postal_code	string	Optional	Maximum length: 5000
body.shipping.address.state	string	Optional	Maximum length: 5000
body.shipping.carrier	string	Optional	Maximum length: 5000
body.shipping.name	string	Required within parent	Maximum length: 5000
body.shipping.phone	string	Optional	Maximum length: 5000
body.shipping.tracking_number	string	Optional	Maximum length: 5000
body.statement_descriptor	string	Optional	Text that appears on the customer’s statement as the statement descriptor for a non-card charge. This value overrides the account’s default statement descriptor. For information about requirements, including the 22-character limit, see [the Statement Descriptor docs](https://docs.stripe.com/get-started/account/statement-descriptors). Setting this value for a card charge returns an error. For card charges, set the [statement_descriptor_suffix](https://docs.stripe.com/get-started/account/statement-descriptors#dynamic) instead. Maximum length: 22
body.statement_descriptor_suffix	string	Optional	Provides information about a card charge. Concatenated to the account’s [statement descriptor prefix](https://docs.stripe.com/get-started/account/statement-descriptors#static) to form the complete statement descriptor that appears on the customer’s statement. Maximum length: 22
body.transfer_data	object	Optional	The parameters that you can use to automatically create a Transfer. Learn more about the [use case for connected accounts](https://docs.stripe.com/payments/connected-accounts).
body.transfer_data.amount	integer	Optional
body.transfer_data.description	string	Optional	Maximum length: 5000
body.transfer_data.destination	string	Required within parent
body.transfer_data.metadata	JSON	Optional
body.transfer_data.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.transfer_data.metadata (anyOf 1).*	string	Additional keys
body.transfer_data.metadata (anyOf 2)	string	Alternative	One of:
body.transfer_data.payment_data	object	Optional
body.transfer_data.payment_data.description	string	Optional	Maximum length: 5000
body.transfer_data.payment_data.metadata	JSON	Optional
body.transfer_data.payment_data.metadata (anyOf 1)	object	Alternative	Additional keys: see wildcard field
body.transfer_data.payment_data.metadata (anyOf 1).*	string	Additional keys
body.transfer_data.payment_data.metadata (anyOf 2)	string	Alternative	One of:
body.transfer_group	string	Optional	A string that identifies the resulting payment as part of a group. Learn more about the [use case for connected accounts](https://docs.stripe.com/connect/separate-charges-and-transfers).
body.use_stripe_sdk	boolean	Optional	Set to `true` when confirming server-side and using Stripe.js, iOS, or Android client-side SDKs to handle the next actions.

Referenced models: Create a Payment Intent — request body — body amount details, Create a Setup Intent — request body — body mandate data customer acceptance, Create a Payment Intent — request body — body payment method data, Create a Payment Intent — request body — body payment method options

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 Cancel a Payment Intent — response body

Referenced models: Cancel a Payment Intent — response body

Schemas

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

Create a Payment Intent — request body — body amount details

Field	Type	Presence	Description and constraints
$	object	Root	Provides industry-specific information about the amount.
discount_amount	JSON	Optional
discount_amount (anyOf 1)	integer	Alternative
discount_amount (anyOf 2)	string	Alternative	One of:
enforce_arithmetic_validation	boolean	Optional
line_items	JSON	Optional
line_items (anyOf 1)	array	Alternative
line_items (anyOf 1)[]	Model	Each item	Expand Create a Payment Intent — request body — body amount details line items array item
line_items (anyOf 2)	string	Alternative	One of:
shipping	JSON	Optional
shipping (anyOf 1)	object	Alternative
shipping (anyOf 1).amount	JSON	Optional
shipping (anyOf 1).amount (anyOf 1)	integer	Alternative
shipping (anyOf 1).amount (anyOf 2)	string	Alternative	One of:
shipping (anyOf 1).from_postal_code	JSON	Optional
shipping (anyOf 1).from_postal_code (anyOf 1)	string	Alternative	Maximum length: 10
shipping (anyOf 1).from_postal_code (anyOf 2)	string	Alternative	One of:
shipping (anyOf 1).to_postal_code	JSON	Optional
shipping (anyOf 1).to_postal_code (anyOf 1)	string	Alternative	Maximum length: 10
shipping (anyOf 1).to_postal_code (anyOf 2)	string	Alternative	One of:
shipping (anyOf 2)	string	Alternative	One of:
tax	JSON	Optional
tax (anyOf 1)	object	Alternative
tax (anyOf 1).total_tax_amount	integer	Required within parent
tax (anyOf 2)	string	Alternative	One of:

Referenced models: Create a Payment Intent — request body — body amount details line items array item

Create a Setup Intent — request body — body mandate data customer acceptance

Field	Type	Presence	Description and constraints
$	object	Root
customer_acceptance	object	Required within parent
customer_acceptance.accepted_at	integer	Optional	Format: unix-time
customer_acceptance.offline	object	Optional
customer_acceptance.online	object	Optional
customer_acceptance.online.ip_address	string	Required within parent
customer_acceptance.online.user_agent	string	Required within parent	Maximum length: 5000
customer_acceptance.type	string	Required within parent	One of: offline, online Maximum length: 5000

Cancel a SetupIntent — response body — last_setup_error / value / type: api error, card error, idempotency error, invalid request error

Field	Type	Presence	Description and constraints
$	object	Root
advice_code	string	Optional	For card errors resulting from a card issuer decline, a short string indicating [how to proceed with an error](https://docs.stripe.com/declines/card#retrying-issuer-declines) if they provide one. Maximum length: 5000
charge	string	Optional	For card errors, the ID of the failed charge. Maximum length: 5000
code	string	Optional	For some errors that could be handled programmatically, a short string indicating the [error code](https://docs.stripe.com/error-codes) reported. Maximum length: 5000
decline_code	string	Optional	For card errors resulting from a card issuer decline, a short string indicating the [card issuer's reason for the decline](https://docs.stripe.com/declines#issuer-declines) if they provide one. Maximum length: 5000
doc_url	string	Optional	A URL to more information about the [error code](https://docs.stripe.com/error-codes) reported. Maximum length: 5000
message	string	Optional	A human-readable message providing more details about the error. For card errors, these messages can be shown to your users. Maximum length: 40000
network_advice_code	string	Optional	For card errors resulting from a card issuer decline, a 2 digit code which indicates the advice given to merchant by the card network on how to proceed with an error. Maximum length: 5000
network_decline_code	string	Optional	For payments declined by the network, an alphanumeric code which indicates the reason the payment failed. Maximum length: 5000
param	string	Optional	If the error is parameter-specific, the parameter related to the error. For example, you can use this to display a message near the correct form field. Maximum length: 5000
payment_intent	Model	Optional	Expand Cancel a Payment Intent — response body
payment_method	Model	Optional	Expand Create a Payment Method — response body
payment_method_type	string	Optional	If the error is specific to the type of payment method, the payment method type that had a problem. This field is only populated for invoice-related errors. Maximum length: 5000
request_log_url	string	Optional	A URL to the request log entry in your dashboard. Maximum length: 5000
setup_intent	Model	Optional	Expand Cancel a Setup Intent — response body
source	JSON	Optional	The [source object](https://docs.stripe.com/api/sources/object) for errors returned on a request involving a source.
source (anyOf 1)	Model	Alternative	Expand Retrieve a bank account — response body
source (anyOf 2)	Model	Alternative	Expand Retrieve a card — customers get Customers Customer Cards Id — response body
source (anyOf 3)	Model	Alternative	Expand Create a source — response body
type	string	Required within parent	The type of error returned. One of `api_error`, `card_error`, `idempotency_error`, or `invalid_request_error` Known values: api_error, card_error, idempotency_error, invalid_request_error

Referenced models: Retrieve a bank account — response body, Retrieve a card — customers get Customers Customer Cards Id — response body, Cancel a Payment Intent — response body, Create a Payment Method — response body, Cancel a Setup Intent — response body, Create a source — response body

PostApplicationFeesIdRefund — response body — application / object: application

Field	Type	Presence	Description and constraints
$	object	Root
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
name	JSON	Optional
name (anyOf 1)	string	Alternative	The name of the application. Maximum length: 5000
name (anyOf 2)	null	Alternative
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: application

Delete a customer — response body

Field	Type	Presence	Description and constraints
$	object	Root
deleted	boolean	Required within parent	Always true for a deleted object Known values: True
id	string	Required within parent	Unique identifier for the object. Maximum length: 5000
object	string	Required within parent	String representing the object's type. Objects of the same type share the same value. Known values: customer

Cancel a Payment Intent — response body — amount details tip

Field	Type	Presence	Description and constraints
$	object	Root
tip	Model	Optional	Expand Cancel a Payment Intent — response body — amount details tip tip

Referenced models: Cancel a Payment Intent — response body — amount details tip tip

Cancel a PaymentIntent — response body — automatic_payment_methods / value / allow_redirects: always, never

Field	Type	Presence	Description and constraints
$	object	Root
allow_redirects	string	Optional	Controls whether this PaymentIntent will accept redirect-based payment methods. Redirect-based payment methods may require your customer to be redirected to a payment method's app or site for authentication or additional steps. To [confirm](https://docs.stripe.com/api/payment_intents/confirm) this PaymentIntent, you may be required to provide a `return_url` to redirect customers back to your site after they authenticate or complete the payment. Known values: always, never
enabled	boolean	Required within parent	Automatically calculates compatible payment methods

Cancel a Payment Intent — response body — hooks

Field	Type	Presence	Description and constraints
$	object	Root
inputs	Model	Optional	Expand Cancel a Payment Intent — response body — hooks inputs

Referenced models: Cancel a Payment Intent — response body — hooks inputs

Create a Payment Method — response body — zip

Field	Type	Presence	Description and constraints
$	object	Root

Policy, approvals and errors

SDK function policy ID: stripe.postpaymentintents. Catalog operation: PostPaymentIntents. 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