Payment Link
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.
Related guide: Payment Links API
The Payment Link object
Attributes
- idstring
Unique identifier for the object.
- activeboolean
Whether the payment link’s
url
is active. Iffalse
, customers visiting the URL will be shown a page saying that the link has been deactivated. - line_
itemsobjectExpandable The line items representing what is being sold.
- 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.
- urlstring
The public URL that can be shared with customers.
More attributes
- objectstring
- after_
completionobject - allow_
promotion_ codesboolean - applicationnullable stringExpandableConnect only
- application_
fee_ amountnullable integerConnect only - application_
fee_ percentnullable floatConnect only - automatic_
taxobject - billing_
address_ collectionenum - consent_
collectionnullable object - currencyenum
- custom_
fieldsarray of objects - custom_
textobject - customer_
creationenum - inactive_
messagenullable string - invoice_
creationnullable object - livemodeboolean
- on_
behalf_ ofnullable stringExpandableConnect only - payment_
intent_ datanullable object - payment_
method_ collectionenum - payment_
method_ typesnullable array of enums - phone_
number_ collectionobject - restrictionsnullable object
- shipping_
address_ collectionnullable object - shipping_
optionsarray of objects - submit_
typeenum - subscription_
datanullable object - tax_
id_ collectionobject - transfer_
datanullable objectConnect only
{
"id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
"object": "payment_link",
"active": true,
"after_completion": {
"hosted_confirmation": {
"custom_message": null
},
"type": "hosted_confirmation"
},
"allow_promotion_codes": false,
"application_fee_amount": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": null
},
"billing_address_collection": "auto",
"consent_collection": null,
"currency": "usd",
"custom_fields": [],
"custom_text": {
"shipping_address": null,
"submit": null
},
"customer_creation": "if_required",
"invoice_creation": {
"enabled": false,
"invoice_data": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"issuer": null,
"metadata": {},
"rendering_options": null
}
},
"livemode": false,
"metadata": {},
"on_behalf_of": null,
"payment_intent_data": null,
"payment_method_collection": "always",
"payment_method_types": null,
"phone_number_collection": {
"enabled": false
},
"shipping_address_collection": null,
"shipping_options": [],
"submit_type": "auto",
"subscription_data": {
"description": null,
"invoice_settings": {
"issuer": {
"type": "self"
}
},
"trial_period_days": null
},
"tax_id_collection": {
"enabled": false
},
"transfer_data": null,
"url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}
Create a payment link
Creates a payment link.
Parameters
- line_
itemsarray of objectsRequired The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.
- 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.
More parameters
- after_
completionobject - allow_
promotion_ codesboolean - application_
fee_ amountintegerConnect only - application_
fee_ percentfloatConnect only - automatic_
taxobject - billing_
address_ collectionenum - consent_
collectionobject - currencyenum
- custom_
fieldsarray of objects - custom_
textobject - customer_
creationenum - inactive_
messagestring - invoice_
creationobject - on_
behalf_ ofstringConnect only - payment_
intent_ dataobject - payment_
method_ collectionenum - payment_
method_ typesarray of enums - phone_
number_ collectionobject - restrictionsobject
- shipping_
address_ collectionobject - shipping_
optionsarray of objects - submit_
typeenum - subscription_
dataobject - tax_
id_ collectionobject - transfer_
dataobjectConnect only
Returns
Returns the payment link.
{
"id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
"object": "payment_link",
"active": true,
"after_completion": {
"hosted_confirmation": {
"custom_message": null
},
"type": "hosted_confirmation"
},
"allow_promotion_codes": false,
"application_fee_amount": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": null
},
"billing_address_collection": "auto",
"consent_collection": null,
"currency": "usd",
"custom_fields": [],
"custom_text": {
"shipping_address": null,
"submit": null
},
"customer_creation": "if_required",
"invoice_creation": {
"enabled": false,
"invoice_data": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"issuer": null,
"metadata": {},
"rendering_options": null
}
},
"livemode": false,
"metadata": {},
"on_behalf_of": null,
"payment_intent_data": null,
"payment_method_collection": "always",
"payment_method_types": null,
"phone_number_collection": {
"enabled": false
},
"shipping_address_collection": null,
"shipping_options": [],
"submit_type": "auto",
"subscription_data": {
"description": null,
"invoice_settings": {
"issuer": {
"type": "self"
}
},
"trial_period_days": null
},
"tax_id_collection": {
"enabled": false
},
"transfer_data": null,
"url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}
Update a payment link
Updates a payment link.
Parameters
- activeboolean
Whether the payment link’s
url
is active. Iffalse
, customers visiting the URL will be shown a page saying that the link has been deactivated. - line_
itemsarray of objects The line items representing what is being sold. Each line item represents an item being sold. Up to 20 line items are supported.
- 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.
More parameters
- after_
completionobject - allow_
promotion_ codesboolean - automatic_
taxobject - billing_
address_ collectionenum - custom_
fieldsarray of objects - custom_
textobject - customer_
creationenum - inactive_
messagestring - invoice_
creationobject - payment_
intent_ dataobject - payment_
method_ collectionenum - payment_
method_ typesarray of enums - restrictionsobject
- shipping_
address_ collectionobject - subscription_
dataobject
Returns
Updated payment link.
{
"id": "plink_1MoC3ULkdIwHu7ixZjtGpVl2",
"object": "payment_link",
"active": true,
"after_completion": {
"hosted_confirmation": {
"custom_message": null
},
"type": "hosted_confirmation"
},
"allow_promotion_codes": false,
"application_fee_amount": null,
"application_fee_percent": null,
"automatic_tax": {
"enabled": false,
"liability": null
},
"billing_address_collection": "auto",
"consent_collection": null,
"currency": "usd",
"custom_fields": [],
"custom_text": {
"shipping_address": null,
"submit": null
},
"customer_creation": "if_required",
"invoice_creation": {
"enabled": false,
"invoice_data": {
"account_tax_ids": null,
"custom_fields": null,
"description": null,
"footer": null,
"issuer": null,
"metadata": {},
"rendering_options": null
}
},
"livemode": false,
"metadata": {
"order_id": "6735"
},
"on_behalf_of": null,
"payment_intent_data": null,
"payment_method_collection": "always",
"payment_method_types": null,
"phone_number_collection": {
"enabled": false
},
"shipping_address_collection": null,
"shipping_options": [],
"submit_type": "auto",
"subscription_data": {
"description": null,
"invoice_settings": {
"issuer": {
"type": "self"
}
},
"trial_period_days": null
},
"tax_id_collection": {
"enabled": false
},
"transfer_data": null,
"url": "https://buy.stripe.com/test_cN25nr0iZ7bUa7meUY"
}
Retrieve a payment link's line items
When retrieving a payment link, there is an includable line_items property containing the first handful of those items. There is also a URL where you can retrieve the full (paginated) list of line items.
Parameters
No parameters.
More parameters
- ending_
beforestring - limitinteger
- starting_
afterstring
Returns
A dictionary with a data
property that contains an array of up to limit
payment link line items, starting after Line Item starting_after
. Each entry in the array is a separate Line Item object. If no more line items are available, the resulting array will be empty.
{
"object": "list",
"data": [
{
"id": "li_NpsHNiHSaDeU0X",
"object": "item",
"amount_discount": 0,
"amount_subtotal": 1099,
"amount_tax": 0,
"amount_total": 1099,
"currency": "usd",
"description": "T-shirt",
"price": {
"id": "price_1N4AEsLkdIwHu7ix7Ssho8Cl",
"object": "price",
"active": true,
"billing_scheme": "per_unit",
"created": 1683237782,
"currency": "usd",
"custom_unit_amount": null,
"livemode": false,
"lookup_key": null,
"metadata": {},
"nickname": null,
"product": "prod_NppuJWzzNnD5Ut",
"recurring": null,
"tax_behavior": "unspecified",
"tiers_mode": null,
"transform_quantity": null,
"type": "one_time",
"unit_amount": 1099,
"unit_amount_decimal": "1099"
},
"quantity": 1
}
],
"has_more": false,
"url": "/v1/payment_links/plink_1N4CWjLkdIwHu7ix2Y2F1kqb/line_items"
}