A payment link is a shareable URL that will take your customers to a hosted payment page. A payment link can be shared and used multiple times. When a customer opens a payment link it will open a new checkout session to render the payment page. You can use checkout session events to track payments through payment links.
openapi: 3.0.0
info:
title: Stripe Payment Links API
description: >-
A payment link is a shareable URL that will take your customers to a hosted
payment page. A payment link can be shared and used multiple times. When a
customer opens a payment link it will open a new checkout session to render
the payment page. You can use checkout session events to track payments
through payment links.
contact:
email: [email protected]
name: Stripe Dev Platform Team
url: https://stripe.com
termsOfService: https://stripe.com/us/terms/
version: '2023-10-16'
x-stripeSpecFilename: spec3
security:
- basicAuth: []
- bearerAuth: []
servers:
- url: https://api.stripe.com/
paths:
/v1/payment_links:
get:
description: <p>Returns a list of your payment links.</p>
operationId: getPaymentLinks
parameters:
- description: >-
Only return payment links that are active or inactive (e.g., pass
`false` to list all inactive payment links).
in: query
name: active
required: false
schema:
type: boolean
style: form
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentLinksRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PaymentLinksResourcePaymentLinkList'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Links
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Links
- Payments
post:
description: <p>Creates a payment link.</p>
operationId: postPaymentLinks
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
after_completion:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
consent_collection:
explode: true
style: deepObject
custom_fields:
explode: true
style: deepObject
custom_text:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
invoice_creation:
explode: true
style: deepObject
line_items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_intent_data:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
phone_number_collection:
explode: true
style: deepObject
restrictions:
explode: true
style: deepObject
shipping_address_collection:
explode: true
style: deepObject
shipping_options:
explode: true
style: deepObject
subscription_data:
explode: true
style: deepObject
tax_id_collection:
explode: true
style: deepObject
transfer_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentLinksRequest'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_link'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Links
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Links
- Payments
- Post
/v1/payment_links/{payment_link}:
get:
description: <p>Retrieve a payment link.</p>
operationId: getPaymentLinksPaymentLink
parameters:
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- in: path
name: payment_link
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentLinksPaymentLinkRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_link'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Links
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Links
- Payments
post:
description: <p>Updates a payment link.</p>
operationId: postPaymentLinksPaymentLink
parameters:
- in: path
name: payment_link
required: true
schema:
maxLength: 5000
type: string
style: simple
requestBody:
content:
application/x-www-form-urlencoded:
encoding:
after_completion:
explode: true
style: deepObject
automatic_tax:
explode: true
style: deepObject
custom_fields:
explode: true
style: deepObject
custom_text:
explode: true
style: deepObject
expand:
explode: true
style: deepObject
inactive_message:
explode: true
style: deepObject
invoice_creation:
explode: true
style: deepObject
line_items:
explode: true
style: deepObject
metadata:
explode: true
style: deepObject
payment_intent_data:
explode: true
style: deepObject
payment_method_types:
explode: true
style: deepObject
restrictions:
explode: true
style: deepObject
shipping_address_collection:
explode: true
style: deepObject
subscription_data:
explode: true
style: deepObject
schema:
additionalProperties: false
$ref: '#/components/schemas/PostPaymentLinksPaymentLinkRequest'
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/payment_link'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Post Payment Links
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Links
- Payments
- Post
/v1/payment_links/{payment_link}/line_items:
get:
description: >-
<p>When retrieving a payment link, there is an includable
<strong>line_items</strong> property containing the first handful of
those items. There is also a URL where you can retrieve the full
(paginated) list of line items.</p>
operationId: getPaymentLinksPaymentLinkLineItems
parameters:
- description: >-
A cursor for use in pagination. `ending_before` is an object ID that
defines your place in the list. For instance, if you make a list
request and receive 100 objects, starting with `obj_bar`, your
subsequent call can include `ending_before=obj_bar` in order to
fetch the previous page of the list.
in: query
name: ending_before
required: false
schema:
maxLength: 5000
type: string
style: form
- description: Specifies which fields in the response should be expanded.
explode: true
in: query
name: expand
required: false
schema:
items:
maxLength: 5000
type: string
type: array
style: deepObject
- description: >-
A limit on the number of objects to be returned. Limit can range
between 1 and 100, and the default is 10.
in: query
name: limit
required: false
schema:
type: integer
style: form
- in: path
name: payment_link
required: true
schema:
maxLength: 5000
type: string
style: simple
- description: >-
A cursor for use in pagination. `starting_after` is an object ID
that defines your place in the list. For instance, if you make a
list request and receive 100 objects, ending with `obj_foo`, your
subsequent call can include `starting_after=obj_foo` in order to
fetch the next page of the list.
in: query
name: starting_after
required: false
schema:
maxLength: 5000
type: string
style: form
requestBody:
content:
application/x-www-form-urlencoded:
encoding: {}
schema:
additionalProperties: false
$ref: '#/components/schemas/GetPaymentLinksPaymentLinkLineItemsRequest'
required: false
responses:
'200':
content:
application/json:
schema:
description: ''
x-expandableFields:
- data
$ref: '#/components/schemas/PaymentLinksResourceListLineItems'
description: Successful response.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/error'
description: Error response.
summary: Stripe Get Payment Links Line Items
x-api-evangelist-processing:
GenerateOperationSummariesFromPath: true
PascalCaseOperationSummaries: true
CaselCaseOperationIds: true
ChooseTags: true
tags:
- Get
- Items
- Line
- Links
- Payments
components:
schemas:
error:
description: An error response from the Stripe API
properties:
error:
$ref: '#/components/schemas/api_errors'
required:
- error
type: object
payment_link:
description: >-
A payment link is a shareable URL that will take your customers to a
hosted payment page. A payment link can be shared and used multiple
times.
When a customer opens a payment link it will open a new [checkout
session](https://stripe.com/docs/api/checkout/sessions) to render the
payment page. You can use [checkout session
events](https://stripe.com/docs/api/events/types#event_types-checkout.session.completed)
to track payments through payment links.
Related guide: [Payment Links
API](https://stripe.com/docs/payment-links)
properties:
active:
description: >-
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.
type: boolean
after_completion:
$ref: '#/components/schemas/payment_links_resource_after_completion'
allow_promotion_codes:
description: Whether user redeemable promotion codes are enabled.
type: boolean
application:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
description: The ID of the Connect application that created the Payment Link.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/application'
- $ref: '#/components/schemas/deleted_application'
application_fee_amount:
description: >-
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.
nullable: true
type: integer
application_fee_percent:
description: >-
This represents the percentage of the subscription invoice total
that will be transferred to the application owner's Stripe account.
nullable: true
type: number
automatic_tax:
$ref: '#/components/schemas/payment_links_resource_automatic_tax'
billing_address_collection:
description: Configuration for collecting the customer's billing address.
enum:
- auto
- required
type: string
consent_collection:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_consent_collection'
description: >-
When set, provides configuration to gather active consent from
customers.
nullable: true
currency:
description: >-
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).
type: string
custom_fields:
description: >-
Collect additional information from your customer using custom
fields. Up to 2 fields are supported.
items:
$ref: '#/components/schemas/payment_links_resource_custom_fields'
type: array
custom_text:
$ref: '#/components/schemas/payment_links_resource_custom_text'
customer_creation:
description: Configuration for Customer creation during checkout.
enum:
- always
- if_required
type: string
id:
description: Unique identifier for the object.
maxLength: 5000
type: string
inactive_message:
description: >-
The custom message to be displayed to a customer when a payment link
is no longer active.
maxLength: 5000
nullable: true
type: string
invoice_creation:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_invoice_creation'
description: Configuration for creating invoice for payment mode payment links.
nullable: true
line_items:
description: The line items representing what is being sold.
properties:
data:
description: Details about each object.
items:
$ref: '#/components/schemas/item'
type: array
has_more:
description: >-
True if this list has another page of items after this one that
can be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
type: string
required:
- data
- has_more
- object
- url
title: PaymentLinksResourceListLineItems
type: object
x-expandableFields:
- data
livemode:
description: >-
Has the value `true` if the object exists in live mode or the value
`false` if the object exists in test mode.
type: boolean
metadata:
additionalProperties:
maxLength: 500
type: string
description: >-
Set of [key-value pairs](https://stripe.com/docs/api/metadata) that
you can attach to an object. This can be useful for storing
additional information about the object in a structured format.
type: object
object:
description: >-
String representing the object's type. Objects of the same type
share the same value.
enum:
- payment_link
type: string
on_behalf_of:
anyOf:
- maxLength: 5000
type: string
- $ref: '#/components/schemas/account'
description: >-
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.
nullable: true
x-expansionResources:
oneOf:
- $ref: '#/components/schemas/account'
payment_intent_data:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_payment_intent_data'
description: >-
Indicates the parameters to be passed to PaymentIntent creation
during checkout.
nullable: true
payment_method_collection:
description: Configuration for collecting a payment method during checkout.
enum:
- always
- if_required
type: string
payment_method_types:
description: >-
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).
items:
enum:
- affirm
- afterpay_clearpay
- alipay
- au_becs_debit
- bacs_debit
- bancontact
- blik
- boleto
- card
- cashapp
- eps
- fpx
- giropay
- grabpay
- ideal
- klarna
- konbini
- link
- oxxo
- p24
- paynow
- paypal
- pix
- promptpay
- sepa_debit
- sofort
- us_bank_account
- wechat_pay
type: string
x-stripeBypassValidation: true
nullable: true
type: array
phone_number_collection:
$ref: '#/components/schemas/payment_links_resource_phone_number_collection'
restrictions:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_restrictions'
description: Settings that restrict the usage of a payment link.
nullable: true
shipping_address_collection:
anyOf:
- $ref: >-
#/components/schemas/payment_links_resource_shipping_address_collection
description: Configuration for collecting the customer's shipping address.
nullable: true
shipping_options:
description: The shipping rate options applied to the session.
items:
$ref: '#/components/schemas/payment_links_resource_shipping_option'
type: array
submit_type:
description: >-
Indicates the type of transaction being performed which customizes
relevant text on the page, such as the submit button.
enum:
- auto
- book
- donate
- pay
type: string
subscription_data:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_subscription_data'
description: >-
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`.
nullable: true
tax_id_collection:
$ref: '#/components/schemas/payment_links_resource_tax_id_collection'
transfer_data:
anyOf:
- $ref: '#/components/schemas/payment_links_resource_transfer_data'
description: >-
The account (if any) the payments will be attributed to for tax
reporting, and where funds from each payment will be transferred to.
nullable: true
url:
description: The public URL that can be shared with customers.
maxLength: 5000
type: string
required:
- active
- after_completion
- allow_promotion_codes
- automatic_tax
- billing_address_collection
- currency
- custom_fields
- custom_text
- customer_creation
- id
- livemode
- metadata
- object
- payment_method_collection
- phone_number_collection
- shipping_options
- submit_type
- tax_id_collection
- url
title: PaymentLink
type: object
x-expandableFields:
- after_completion
- application
- automatic_tax
- consent_collection
- custom_fields
- custom_text
- invoice_creation
- line_items
- on_behalf_of
- payment_intent_data
- phone_number_collection
- restrictions
- shipping_address_collection
- shipping_options
- subscription_data
- tax_id_collection
- transfer_data
x-resourceId: payment_link
GetPaymentLinksRequest:
type: object
properties: {}
PaymentLinksResourcePaymentLinkList:
type: object
required:
- data
- has_more
- object
- url
properties:
data:
items:
$ref: '#/components/schemas/payment_link'
type: array
has_more:
description: >-
True if this list has another page of items after this one that can
be fetched.
type: boolean
object:
description: >-
String representing the object's type. Objects of the same type
share the same value. Always has the value `list`.
enum:
- list
type: string
url:
description: The URL where this list can be accessed.
maxLength: 5000
pattern: ^/v1/payment_links
type: string
PostPaymentLinksRequest:
type: object
required:
- line_items
properties:
after_completion:
description: Behavior after the purchase is complete.
properties:
hosted_confirmation:
properties:
custom_message:
maxLength: 500
type: string
title: after_completion_confirmation_page_params
type: object
redirect:
properties:
url:
maxLength: 2048
type: string
required:
- url
title: after_completion_redirect_params
type: object
type:
enum:
- hosted_confirmation
- redirect
type: string
required:
- type
title: after_completion_params
type: object
allow_promotion_codes:
description: Enables user redeemable promotion codes.
type: boolean
application_fee_amount:
description: >-
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.
type: integer
application_fee_percent:
description: >-
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.
type: number
automatic_tax:
description: Configuration for automatic tax collection.
properties:
enabled:
type: boolean
required:
- enabled
title: automatic_tax_params
type: object
billing_address_collection:
description: Configuration for collecting the customer's billing address.
enum:
- auto
- required
type: string
consent_collection:
description: Configure fields to gather active consent from customers.
properties:
payment_method_reuse_agreement:
properties:
position:
enum:
- auto
- hidden
type: string
required:
- position
title: payment_method_reuse_agreement_params
type: object
promotions:
enum:
- auto
- none
type: string
terms_of_service:
enum:
- none
- required
type: string
title: consent_collection_params
type: object
currency:
description: >-
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.
type: string
custom_fields:
description: >-
Collect additional information from your customer using custom
fields. Up to 2 fields are supported.
items:
properties:
dropdown:
properties:
options:
items:
properties:
label:
maxLength: 100
type: string
value:
maxLength: 100
type: string
required:
- label
- value
title: custom_field_option_param
type: object
type: array
required:
- options
title: custom_field_dropdown_param
type: object
key:
maxLength: 200
type: string
label:
properties:
custom:
maxLength: 50
type: string
type:
enum:
- custom
type: string
required:
- custom
- type
title: custom_field_label_param
type: object
numeric:
properties:
maximum_length:
type: integer
minimum_length:
type: integer
title: custom_field_numeric_param
type: object
optional:
type: boolean
text:
properties:
maximum_length:
type: integer
minimum_length:
type: integer
title: custom_field_text_param
type: object
type:
enum:
- dropdown
- numeric
- text
type: string
required:
- key
- label
- type
title: custom_field_param
type: object
type: array
custom_text:
description: Display additional text for your customers using custom text.
properties:
after_submit:
anyOf:
- properties:
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/stripe/refs/heads/main/openapi/stripe-payment-links-api-openapi.yml