Stripe: Create a payment link

← Payment links operations · Get started

Operation stripe.postpaymentlinks

Provider route: POST /v1/payment_links. 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["paymentLinks"]["postPaymentLinks"]>[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.paymentLinks.postPaymentLinks(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_links.post_payment_links(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.after_completion	object	Optional	Behavior after the purchase is complete.
body.after_completion.hosted_confirmation	object	Optional
body.after_completion.hosted_confirmation.custom_message	string	Optional	Maximum length: 500
body.after_completion.redirect	object	Optional
body.after_completion.redirect.url	string	Required within parent
body.after_completion.type	string	Required within parent	One of: hosted_confirmation, redirect
body.allow_promotion_codes	boolean	Optional	Enables user redeemable promotion codes.
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. Can only be applied when there are no line items with recurring prices.
body.application_fee_percent	number	Optional	A non-negative decimal between 0 and 100, with at most two decimal places. This represents the percentage of the subscription invoice total that will be transferred to the application owner’s Stripe account. There must be at least 1 line item with a recurring price to use this field.
body.automatic_tax	object	Optional	Configuration for automatic tax collection.
body.automatic_tax.enabled	boolean	Required within parent
body.automatic_tax.liability	object	Optional
body.automatic_tax.liability.account	string	Optional
body.automatic_tax.liability.type	string	Required within parent	One of: account, self
body.billing_address_collection	string	Optional	Configuration for collecting the customer’s billing address. Defaults to `auto`. One of: auto, required
body.consent_collection	object	Optional	Configure fields to gather active consent from customers.
body.consent_collection.payment_method_reuse_agreement	object	Optional
body.consent_collection.payment_method_reuse_agreement.position	string	Required within parent	One of: auto, hidden
body.consent_collection.promotions	string	Optional	One of: auto, none
body.consent_collection.terms_of_service	string	Optional	One of: none, required
body.currency	string	Optional	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) and supported by each line item’s price. Format: currency
body.custom_fields	array	Optional	Collect additional information from your customer using custom fields. Up to 3 fields are supported. You can’t set this parameter if `ui_mode` is `elements`.
body.custom_fields[]	Model	Each item	Expand Create a payment link — request body — body custom fields item
body.custom_text	Model	Optional	Expand Create a payment link — request body — body custom text
body.customer_creation	string	Optional	Configures whether [checkout sessions](https://docs.stripe.com/api/checkout/sessions) created by this payment link create a [Customer](https://docs.stripe.com/api/customers). One of: always, if_required
body.expand	array	Optional	Specifies which fields in the response should be expanded.
body.expand[]	string	Each item	Maximum length: 5000
body.inactive_message	string	Optional	The custom message to be displayed to a customer when a payment link is no longer active. Maximum length: 500
body.invoice_creation	Model	Optional	Expand Create a payment link — request body — body invoice creation
body.line_items	array	Required within parent	The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.
body.line_items[]	object	Each item
body.line_items[].adjustable_quantity	object	Optional
body.line_items[].adjustable_quantity.enabled	boolean	Required within parent
body.line_items[].adjustable_quantity.maximum	integer	Optional
body.line_items[].adjustable_quantity.minimum	integer	Optional
body.line_items[].price	string	Optional	Maximum length: 5000
body.line_items[].price_data	Model	Optional	Expand Create a payment link — request body — body line items item price data
body.line_items[].quantity	integer	Required within parent
body.managed_payments	object	Optional	Settings for Managed Payments for this Payment Link and resulting [CheckoutSessions](/api/checkout/sessions/object), [PaymentIntents](/api/payment_intents/object), [Invoices](/api/invoices/object), and [Subscriptions](/api/subscriptions/object).
body.managed_payments.enabled	boolean	Optional
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`. Metadata associated with this Payment Link will automatically be copied to [checkout sessions](https://docs.stripe.com/api/checkout/sessions) created by this payment link. Additional keys: see wildcard field
body.metadata.*	string	Additional keys
body.name_collection	object	Optional	Controls settings applied for collecting the customer’s name.
body.name_collection.business	object	Optional
body.name_collection.business.enabled	boolean	Required within parent
body.name_collection.business.optional	boolean	Optional
body.name_collection.individual	object	Optional
body.name_collection.individual.enabled	boolean	Required within parent
body.name_collection.individual.optional	boolean	Optional
body.on_behalf_of	string	Optional	The account on behalf of which to charge.
body.optional_items	array	Optional	A list of optional items the customer can add to their order at checkout. Use this parameter to pass one-time or recurring [Prices](https://docs.stripe.com/api/prices). There is a maximum of 10 optional items allowed on a payment link, and the existing limits on the number of line items allowed on a payment link apply to the combined number of line items and optional items. There is a maximum of 20 combined line items and optional items.
body.optional_items[]	object	Each item
body.optional_items[].adjustable_quantity	object	Optional
body.optional_items[].adjustable_quantity.enabled	boolean	Required within parent
body.optional_items[].adjustable_quantity.maximum	integer	Optional
body.optional_items[].adjustable_quantity.minimum	integer	Optional
body.optional_items[].price	string	Required within parent	Maximum length: 5000
body.optional_items[].quantity	integer	Required within parent
body.payment_intent_data	object	Optional	A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in `payment` mode.
body.payment_intent_data.capture_method	string	Optional	One of: automatic, automatic_async, manual
body.payment_intent_data.description	string	Optional	Maximum length: 1000
body.payment_intent_data.metadata	object	Optional	Additional keys: see wildcard field
body.payment_intent_data.metadata.*	string	Additional keys
body.payment_intent_data.setup_future_usage	string	Optional	One of: off_session, on_session
body.payment_intent_data.statement_descriptor	string	Optional	Maximum length: 22
body.payment_intent_data.statement_descriptor_suffix	string	Optional	Maximum length: 22
body.payment_intent_data.transfer_group	string	Optional	Maximum length: 5000
body.payment_method_collection	string	Optional	Specify whether Checkout should collect a payment method. When set to `if_required`, Checkout will not collect a payment method when the total due for the session is 0.This may occur if the Checkout Session includes a free trial or a discount. Can only be set in `subscription` mode. Defaults to `always`. If you’d like information on how to collect a payment method outside of Checkout, read the guide on [configuring subscriptions with a free trial](https://docs.stripe.com/payments/checkout/free-trials). One of: always, if_required
body.payment_method_options	object	Optional	Payment-method-specific configuration.
body.payment_method_options.card	object	Optional
body.payment_method_options.card.restrictions	object	Optional
body.payment_method_options.card.restrictions.brands_blocked	array	Optional
body.payment_method_options.card.restrictions.brands_blocked[]	string	Each item	One of: american_express, discover_global_network, mastercard, visa
body.payment_method_types	array	Optional	The list of payment method types that customers can use. If no value is passed, Stripe will dynamically show relevant payment methods from your [payment method settings](https://dashboard.stripe.com/settings/payment_methods) (20+ payment methods [supported](https://docs.stripe.com/payments/payment-methods/integration-options#payment-method-product-support)).
body.payment_method_types[]	string	Each item	One of: affirm, afterpay_clearpay, alipay, alma, au_becs_debit, bacs_debit, bancontact, billie, bizum, blik, boleto, card, cashapp, eps, fpx, giropay, grabpay, ideal, klarna, konbini, link, mb_way, mobilepay, multibanco, oxxo, p24, pay_by_bank, paynow, paypal, paypay, payto, pix, promptpay, satispay, sepa_debit, sequra, sofort, sunbit, swish, twint, upi, us_bank_account, wechat_pay, zip
body.phone_number_collection	object	Optional	Controls phone number collection settings during checkout. We recommend that you review your privacy policy and check with your legal contacts.
body.phone_number_collection.enabled	boolean	Required within parent
body.restrictions	object	Optional	Settings that restrict the usage of a payment link.
body.restrictions.completed_sessions	object	Required within parent
body.restrictions.completed_sessions.limit	integer	Required within parent
body.shipping_address_collection	object	Optional	Configuration for collecting the customer’s shipping address.
body.shipping_address_collection.allowed_countries	array	Required within parent
body.shipping_address_collection.allowed_countries[]	string	Each item	One of: AC, AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CV, CW, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MK, ML, MM, MN, MO, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SZ, TA, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, US, UY, UZ, VA, VC, VE, VG, VN, VU, WF, WS, XK, YE, YT, ZA, ZM, ZW, ZZ
body.shipping_options	array	Optional	The shipping rate options to apply to [checkout sessions](https://docs.stripe.com/api/checkout/sessions) created by this payment link.
body.shipping_options[]	object	Each item
body.shipping_options[].shipping_rate	string	Optional	Maximum length: 5000
body.submit_type	string	Optional	Describes the type of transaction being performed in order to customize relevant text on the page, such as the submit button. Changing this value will also affect the hostname in the [url](https://docs.stripe.com/api/payment_links/payment_links/object#url) property (example: `donate.stripe.com`). One of: auto, book, donate, pay, subscribe
body.subscription_data	object	Optional	When creating a subscription, the specified configuration data will be used. There must be at least one line item with a recurring price to use `subscription_data`.
body.subscription_data.description	string	Optional	Maximum length: 500
body.subscription_data.invoice_settings	object	Optional
body.subscription_data.invoice_settings.issuer	object	Optional
body.subscription_data.invoice_settings.issuer.account	string	Optional
body.subscription_data.invoice_settings.issuer.type	string	Required within parent	One of: account, self
body.subscription_data.metadata	object	Optional	Additional keys: see wildcard field
body.subscription_data.metadata.*	string	Additional keys
body.subscription_data.trial_period_days	integer	Optional
body.subscription_data.trial_settings	object	Optional
body.subscription_data.trial_settings.end_behavior	object	Required within parent
body.subscription_data.trial_settings.end_behavior.missing_payment_method	string	Required within parent	One of: cancel, create_invoice, pause
body.tax_id_collection	object	Optional	Controls tax ID collection during checkout.
body.tax_id_collection.enabled	boolean	Required within parent
body.tax_id_collection.required	string	Optional	One of: if_supported, never
body.transfer_data	object	Optional	The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.
body.transfer_data.amount	integer	Optional
body.transfer_data.destination	string	Required within parent

Referenced models: Create a payment link — request body — body custom fields item, Create a payment link — request body — body custom text, Create a payment link — request body — body invoice creation, Create a payment link — request body — body line items item price data

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 Create a payment link — response body

Referenced models: Create a payment link — response body

Schemas

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

Create a payment link — request body — body custom fields item

Field	Type	Presence	Description and constraints
$	object	Root
dropdown	object	Optional
dropdown.default_value	string	Optional	Maximum length: 100
dropdown.options	array	Required within parent
dropdown.options[]	object	Each item
dropdown.options[].label	string	Required within parent	Maximum length: 100
dropdown.options[].value	string	Required within parent	Maximum length: 100
key	string	Required within parent	Maximum length: 200
label	object	Required within parent
label.custom	string	Required within parent	Maximum length: 100
label.type	string	Required within parent	One of: custom
numeric	object	Optional
numeric.default_value	string	Optional	Maximum length: 255
numeric.maximum_length	integer	Optional
numeric.minimum_length	integer	Optional
optional	boolean	Optional
text	object	Optional
text.default_value	string	Optional	Maximum length: 255
text.maximum_length	integer	Optional
text.minimum_length	integer	Optional
type	string	Required within parent	One of: dropdown, numeric, text

Create a payment link — request body — body custom text

Field	Type	Presence	Description and constraints
$	object	Root	Display additional text for your customers using custom text. You can't set this parameter if `ui_mode` is `elements`.
after_submit	JSON	Optional
after_submit (anyOf 1)	object	Alternative
after_submit (anyOf 1).message	string	Required within parent	Maximum length: 1200
after_submit (anyOf 2)	string	Alternative	One of:
shipping_address	JSON	Optional
shipping_address (anyOf 1)	object	Alternative
shipping_address (anyOf 1).message	string	Required within parent	Maximum length: 1200
shipping_address (anyOf 2)	string	Alternative	One of:
submit	JSON	Optional
submit (anyOf 1)	object	Alternative
submit (anyOf 1).message	string	Required within parent	Maximum length: 1200
submit (anyOf 2)	string	Alternative	One of:
terms_of_service_acceptance	JSON	Optional
terms_of_service_acceptance (anyOf 1)	object	Alternative
terms_of_service_acceptance (anyOf 1).message	string	Required within parent	Maximum length: 1200
terms_of_service_acceptance (anyOf 2)	string	Alternative	One of:

Create a payment link — request body — body invoice creation

Field	Type	Presence	Description and constraints
$	object	Root	Generate a post-purchase Invoice for one-time payments.
enabled	boolean	Required within parent
invoice_data	Model	Optional	Expand Create a payment link — request body — body invoice creation invoice data

Referenced models: Create a payment link — request body — body invoice creation invoice data

Create a payment link — request body — body line items item price data

Field	Type	Presence	Description and constraints
$	object	Root
currency	string	Required within parent	Format: currency
product	string	Optional	Maximum length: 5000
product_data	Model	Optional	Expand Update an invoice's line item — request body — body price data product data
recurring	object	Optional
recurring.interval	string	Required within parent	One of: day, month, week, year
recurring.interval_count	integer	Optional
tax_behavior	string	Optional	One of: exclusive, inclusive, unspecified
unit_amount	integer	Optional
unit_amount_decimal	string	Optional	Format: decimal

Referenced models: Update an invoice's line item — request body — body price data product data

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

Accept a quote — response body — application / value / deleted: True, object: application

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

Create a payment link — response body — after completion

Field	Type	Presence	Description and constraints
$	object	Root
hosted_confirmation	Model	Optional	Expand Create a payment link — response body — after completion hosted confirmation
redirect	Model	Optional	Expand Create a payment link — response body — after completion redirect
type	string	Required within parent	The specified behavior after the purchase is complete. Known values: hosted_confirmation, redirect

Referenced models: Create a payment link — response body — after completion hosted confirmation, Create a payment link — response body — after completion redirect

Create a payment link — response body — automatic tax

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	If `true`, tax will be calculated automatically using the customer's location.
liability	JSON	Optional
liability (anyOf 1)	JSON	Alternative	The account that's liable for tax. If set, the business address and tax registrations required to perform the tax calculation are loaded from this account. The tax transaction is returned in the report of the connected account.
liability (anyOf 1) (anyOf 1)	Model	Alternative	Expand Pay an invoice — response body — issuer
liability (anyOf 2)	null	Alternative

Referenced models: Pay an invoice — response body — issuer

Create a payment link — response body — consent collection value payment method reuse agreement, promotions, terms of service

Field	Type	Presence	Description and constraints
$	object	Root
payment_method_reuse_agreement	JSON	Optional
payment_method_reuse_agreement (anyOf 1)	JSON	Alternative	Settings related to the payment method reuse text shown in the Checkout UI.
payment_method_reuse_agreement (anyOf 1) (anyOf 1)	Model	Alternative	Expand Create a payment link — response body — consent_collection / value / payment_method_reuse_agreement, promotions, terms_of_service / payment_method_reuse_agreement / value / position: auto, hidden
payment_method_reuse_agreement (anyOf 2)	null	Alternative
promotions	JSON	Optional
promotions (anyOf 1)	string	Alternative	If set to `auto`, enables the collection of customer consent for promotional communications. Known values: auto, none
promotions (anyOf 2)	null	Alternative
terms_of_service	JSON	Optional
terms_of_service (anyOf 1)	string	Alternative	If set to `required`, it requires cutomers to accept the terms of service before being able to pay. If set to `none`, customers won't be shown a checkbox to accept the terms of service. Known values: none, required
terms_of_service (anyOf 2)	null	Alternative

Referenced models: Create a payment link — response body — consent_collection / value / payment_method_reuse_agreement, promotions, terms_of_service / payment_method_reuse_agreement / value / position: auto, hidden

Create a payment link — response body — phone number collection

Field	Type	Presence	Description and constraints
$	object	Root
enabled	boolean	Required within parent	If `true`, a phone number will be collected during checkout.

Policy, approvals and errors

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