Create a payment link

Changed on

Creates a payment link.

post/v1/payment_links

Request

  • Base URL: https://api.stripe.com
  • URL: https://api.stripe.com/v1/payment_links
  • Auth: one of:
    • HTTP basic
    • HTTP bearer

Request body application/x-www-form-urlencoded

allow_promotion_codesboolean

Enables user redeemable promotion codes.

application_fee_amountinteger

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_percentnumber

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.

billing_address_collection'auto' | 'required'

Configuration for collecting the customer's billing address. Defaults to auto.

currencystring currency

Three-letter ISO currency code, in lowercase. Must be a supported currency and supported by each line item's price.

customer_creation'always' | 'if_required'

Configures whether checkout sessions created by this payment link create a Customer.

expandstring[]

Specifies which fields in the response should be expanded.

inactive_messagestring

The custom message to be displayed to a customer when a payment link is no longer active.

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. Metadata associated with this Payment Link will automatically be copied to checkout sessions created by this payment link.

on_behalf_ofstring

The account on behalf of which to charge.

payment_method_collection'always' | 'if_required'

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.

payment_method_typesstring[]

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 (20+ payment methods supported).

submit_type'auto' | 'book' | 'donate' | 'pay' | 'subscribe'

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 property (example: donate.stripe.com).

Response

Successful response.

activeboolean required

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.

allow_promotion_codesboolean required

Whether user redeemable promotion codes are enabled.

application_fee_amountinteger nullable

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

This represents the percentage of the subscription invoice total that will be transferred to the application owner's Stripe account.

billing_address_collection'auto' | 'required' required

Configuration for collecting the customer's billing address. Defaults to auto.

currencystring currency required

Three-letter ISO currency code, in lowercase. Must be a supported currency.

customer_creation'always' | 'if_required' required

Configuration for Customer creation during checkout.

idstring required

Unique identifier for the object.

inactive_messagestring nullable

The custom message to be displayed to a customer when a payment link is no longer active.

livemodeboolean required

If the object exists in live mode, the value is true. If the object exists in test mode, the value is false.

metadataobject required

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.

object'payment_link' required

String representing the object's type. Objects of the same type share the same value.

payment_method_collection'always' | 'if_required' required

Configuration for collecting a payment method during checkout. Defaults to always.

payment_method_typesstring[] nullable

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.

submit_type'auto' | 'book' | 'donate' | 'pay' | 'subscribe' required

Indicates the type of transaction being performed which customizes relevant text on the page, such as the submit button.

urlstring required

The public URL that can be shared with customers.

Changes

  • 585b581504aeRevision changes
    • warning

      added the new final_payment_failure enum value to the ////////////// response property for the response status

    • warning

      added the new final_payment_failure enum value to the //////////////// response property for the response status

    • warning

      added the new first_payment_failure enum value to the ////////////// response property for the response status

    • warning

      added the new first_payment_failure enum value to the //////////////// response property for the response status

  • 7537419124b6Revision changes
    • info

      added the optional property /////////// to the response with the status

    • info

      added the optional property ///////////// to the response with the status

Some revisions have not been checked yet.