Sample - Stripe API
POST/v1/payment_links

Create a payment link

Creates a payment link that provides customers with a hosted payment page for the configured items. Supply line_items and configure checkout behaviour such as after_completion, automatic_tax, payment methods, customer creation, and shipping collection as needed. The response contains the created payment link and its hosted URL.

  • RetriesRetries up to 2×, 500ms backoff, 30s timeout.
  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

32 body fields

Payment link configuration, including the items sold and the checkout behaviour presented to customers.

after_completionobjectoptional
Behavior after the purchase is complete.
allow_promotion_codesbooleanoptional
Enables user redeemable promotion codes.
application_fee_amountintegeroptional
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.
application_fee_percentnumberoptional
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.
automatic_taxobjectoptional
Configuration for automatic tax collection.
billing_address_collectionstringoptional
Configuration for collecting the customer's billing address. Defaults to `auto`.
Allowed:autorequired
consent_collectionobjectoptional
Configure fields to gather active consent from customers.
currencystringoptional
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.
custom_fieldsarray<CustomFieldParam>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 `custom`.
custom_textobjectoptional
Display additional text for your customers using custom text. You can't set this parameter if `ui_mode` is `custom`.
customer_creationstringoptional
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).
Allowed:alwaysif_required
expandarray<string>optional
Specifies which fields in the response should be expanded.
inactive_messagestringoptional
The custom message to be displayed to a customer when a payment link is no longer active.
invoice_creationobjectoptional
Generate a post-purchase Invoice for one-time payments.
line_itemsarray<LineItemsCreateParams>required
The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.
managed_paymentsobjectoptional
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).
metadataobjectoptional
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.
name_collectionobjectoptional
Controls settings applied for collecting the customer's name.
on_behalf_ofstringoptional
The account on behalf of which to charge.
optional_itemsarray<OptionalItemParams>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.
payment_intent_dataobjectoptional
A subset of parameters to be passed to PaymentIntent creation for Checkout Sessions in `payment` mode.
payment_method_collectionstringoptional
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).
Allowed:alwaysif_required
payment_method_optionsobjectoptional
Payment-method-specific configuration.
payment_method_typesarray<string>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)).
phone_number_collectionobjectoptional
Controls phone number collection settings during checkout. We recommend that you review your privacy policy and check with your legal contacts.
restrictionsobjectoptional
Settings that restrict the usage of a payment link.
shipping_address_collectionobjectoptional
Configuration for collecting the customer's shipping address.
shipping_optionsarray<ShippingOptionParams>optional
The shipping rate options to apply to [checkout sessions](https://docs.stripe.com/api/checkout/sessions) created by this payment link.
submit_typestringoptional
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`).
Allowed:autobookdonatepaysubscribe
subscription_dataobjectoptional
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`.
tax_id_collectionobjectoptional
Controls tax ID collection during checkout.
transfer_dataobjectoptional
The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.

2 status codes
200Returns the created payment link object, including its identifier, active state, checkout configuration, currency, and hosted payment link details.
activebooleanrequired
Whether the payment link's `url` is active. If `false`, customers visiting the URL will be shown a page saying that the link has been deactivated.
after_completionobjectrequired
allow_promotion_codesbooleanrequired
Whether user redeemable promotion codes are enabled.
applicationstringoptional
The ID of the Connect application that created the Payment Link.
application_fee_amountintegeroptional
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.
application_fee_percentnumberoptional
This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.
automatic_taxobjectrequired
billing_address_collectionstringrequired
Configuration for collecting the customer's billing address. Defaults to `auto`.
Allowed:autorequired
consent_collectionobjectoptional
When set, provides configuration to gather active consent from customers.
currencystringrequired
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).
custom_fieldsarray<PaymentLinksResourceCustomFields>required
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 `custom`.
custom_textobjectrequired
customer_creationstringrequired
Configuration for Customer creation during checkout.
Allowed:alwaysif_required
idstringrequired
Unique identifier for the object.
inactive_messagestringoptional
The custom message to be displayed to a customer when a payment link is no longer active.
invoice_creationobjectoptional
Configuration for creating invoice for payment mode payment links.
line_itemsobjectoptional
The line items representing what is being sold.
livemodebooleanrequired
If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`.
managed_paymentsobjectoptional
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).
metadataobjectrequired
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.
name_collectionobjectoptional
objectstringrequired
String representing the object's type. Objects of the same type share the same value.
Allowed:payment_link
on_behalf_ofstringoptional
The account on behalf of which to charge. See the [Connect documentation](https://support.stripe.com/questions/sending-invoices-on-behalf-of-connected-accounts) for details.
optional_itemsarray<PaymentLinksResourceOptionalItem>optional
The optional items presented to the customer at checkout.
payment_intent_dataobjectoptional
Indicates the parameters to be passed to PaymentIntent creation during checkout.
payment_method_collectionstringrequired
Configuration for collecting a payment method during checkout. Defaults to `always`.
Allowed:alwaysif_required
payment_method_optionsobjectoptional
Payment-method-specific configuration.
payment_method_typesarray<string>optional
The list of payment method types that customers can use. When `null`, Stripe will dynamically show relevant payment methods you've enabled in your [payment method settings](https://dashboard.stripe.com/settings/payment_methods).
phone_number_collectionobjectrequired
restrictionsobjectoptional
Settings that restrict the usage of a payment link.
shipping_address_collectionobjectoptional
Configuration for collecting the customer's shipping address.
shipping_optionsarray<PaymentLinksResourceShippingOption>required
The shipping rate options applied to the session.
submit_typestringrequired
Indicates the type of transaction being performed which customizes relevant text on the page, such as the submit button.
Allowed:autobookdonatepaysubscribe
subscription_dataobjectoptional
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`.
tax_id_collectionobjectrequired
transfer_dataobjectoptional
The account (if any) the payments will be attributed to for tax reporting, and where funds from each payment will be transferred to.
urlstringrequired
The public URL that can be shared with customers.
defaultError response.
errorobjectrequired

Error handling

line_items is required and each line item must include quantity; provide no more than 20 line items. after_completion.type must be hosted_confirmation or redirect, billing_address_collection must be auto or required, and customer_creation must be always or if_required. currency must be a supported lowercase three-letter ISO currency code, and inactive_message must not exceed 500 characters.