Payment Links Schema
Hosted payment pages for collecting payments without custom forms
The Payment Links schema defines the structure and properties of payment link objects in the Payload API. This comprehensive reference table shows all available properties, their types, constraints, and requirements.
Payment Link Object Properties
Complete reference for all properties available in the Payment Link schema
amountnumber (double)
The payment amount to collect through this link. If this payment link is associated with an invoice, the amount is automatically set to the invoice balance due and cannot be specified separately. The amount can be made editable by the customer using the field_options.amount_field setting.
attachmentsPaymentLinkAttachmentarray
Collection of all file attachments associated with this payment link. Files are automatically expanded by default to show attachment details including filename, type, size, and download URL. Use attachments to provide supporting documents to customers alongside payment requests.
attrsobject
A flexible JSON object for storing custom metadata and attributes related to this payment link. Use this to attach any additional information you need for your business logic, such as order IDs, customer references, campaign codes, or internal tracking data. The object can contain any valid JSON structure up to 500 characters. If this payment link is associated with an invoice and attrs is not specified, the invoice attrs are used by default.
billerobject
Information about the merchant or service provider who will receive payment through this link. Contains the biller account identifier and payment destination details. The biller receives funds when the payer completes payment.
accountAccountobject
The expanded biller account object. When included, this provides full account details for the merchant or service provider who will receive payment through this link.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the processing account that will receive funds from this payment link. This is the merchant or service provider being paid. Required when no invoice_id is provided. If associated with an invoice, this is automatically set to match the invoice biller and cannot be changed. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$Required if:
invoice_id=nullcheckout_optionsobject
Configuration options that control the payment checkout experience and available payment methods. Use this to customize which payment options are enabled (cards, bank accounts, digital wallets), whether to collect billing addresses, show payment method previews, enable autopay enrollment, and other checkout behavior. These settings are constrained by the biller account's processing capabilities - you cannot enable payment methods that the account is not provisioned to accept.
auto_billing_toggleboolean
Display a toggle that allows customers to opt into automatic recurring payments. When true, shows a checkbox or toggle on the payment form where customers can choose to save their payment method as the default for future automatic billing. Useful for subscription or recurring payment scenarios.
bank_account_paymentsboolean
Enable or disable bank account payments for this payment link. When true, customers can pay using their bank account and routing number. When false, bank account payment options are hidden. This setting is constrained by the biller account processing capabilities - bank accounts can only be enabled if the account is provisioned for bank account processing. Defaults to the account's bank account processing enabled setting.
billing_addressboolean
Require the customer to provide a billing address during checkout. When true, address fields (street, city, state, postal code) are displayed and required before payment can be submitted. Useful for validation, fraud prevention, and compliance. When false, address collection is skipped. Zip or postal code may still be required based on AVS settings.
card_paymentsboolean
Enable or disable credit/debit card payments for this payment link. When true, customers can pay using card details. When false, card payment options are hidden. This setting is constrained by the biller account processing capabilities - cards can only be enabled if the account is provisioned for card processing. Defaults to the account's card processing enabled setting.
default_payment_optionenum[string]
The payment method type that should be selected by default when the checkout page loads. Set to "card" to pre-select card payment option, or "bank_account" to pre-select bank account payment. This provides a suggested payment method but customers can still switch to other enabled options. If not set, the first enabled payment method is shown.
Values:
card, bank_accountenable_mobile_walletsboolean
Enable digital wallet payment options including Google Pay and Apple Pay. When true, customers can use their saved payment methods from Google or Apple wallets for faster checkout. Requires compatible devices and browsers. Improves conversion rates for mobile users.
enable_plaidboolean
Enable Plaid integration for instant bank account verification and linking. When true, customers can securely connect their bank accounts through Plaid instead of manually entering routing and account numbers. Can help with user experience and reduces errors for bank account payments for certain use-cases.
keep_active_toggleboolean
Display a toggle that allows customers to save their payment method for future use. When true, shows a checkbox where customers can opt to keep their payment method active in the system after the current payment. When false or unchecked, payment methods are treated as single-use. Helps reduce friction for returning customers.
payment_method_previewboolean
Display a preview or summary of the entered payment method before final submission. When true, shows customers their entered payment details (masked) for review before confirming the payment. This helps prevent errors and builds customer confidence.
show_disclosureboolean
Include the standard payment processing disclosure text on the checkout page. When true, displays legal and informational text about the payment processing, terms of service, and related disclosures. Required in some jurisdictions or use cases for compliance.
created_atstring (date-time)Read-only
Timestamp when the resource was created. Automatically set by the system and immutable.
descriptionstring
A human-readable description of what this payment is for. This text is displayed to the customer on the payment page and helps them understand what they are paying for. Use clear, descriptive text like "Invoice #1234 Payment" or "Monthly Subscription Fee". If this payment link is associated with an invoice, the invoice description is used by default if not specified.
Max length: 128
field_optionsobject
Configuration for field collection and display behavior on the payment form. Controls what information is collected from customers, whether amounts can be edited, and which custom fields to show. Use these options to customize the payment experience for your specific use case.
amount_fieldenum[string]
Controls whether the payment amount can be modified by the customer when accessing the payment link. Set to "editable" to allow the customer to change the amount (useful for donations or variable payments), or "static" to lock the amount to the value specified in the payment link.
Values:
editable, staticcustom_fieldsarray
Additional custom form fields to collect from the customer during checkout. Use this to gather extra information beyond standard payment details, such as order notes, service preferences, or custom business data. Each field can be configured with validation, placeholders, and required/optional status.
payer_fieldsenum[string]
Controls whether customer information fields (name, email, phone) are displayed on the payment form. Set to "required" to make customer information mandatory, "optional" to allow but not require it, or "disabled" to hide customer fields entirely.
Values:
required, optional, disabledidstringRead-only
Unique identifier for the resource. Automatically generated upon creation and cannot be modified. (ID prefix: pay)
Pattern:
^pay_[A-Za-z0-9]+$invoice_id ID of Invoicestring
The unique identifier of the invoice that this payment link is for. When an invoice_id is provided, the payment link amount, payer, and biller are automatically synchronized with the invoice and cannot be changed independently. The link will collect payment for the outstanding invoice balance. If not provided, this is a standalone payment link not tied to any invoice. (ID prefix: inv)
Pattern:
^inv_[A-Za-z0-9]+$modified_atstring (date-time)Read-only
Timestamp when the resource was last modified. Automatically updated whenever any field changes.
objectenum[string]Read-only
String representing the object type for this resource.
Values:
payment_linkpayerobject
Information about the customer who will use this payment link. Contains the payer account identifier and related customer information. The payer is the party who will submit payment through the link.
accountAccountobject
The expanded payer account object. When included, this provides full account details for the customer who will use this payment link.
Visibility: explicit
account_id ID of Accountstring
The unique identifier of the customer account that will use this payment link. This is the account that will make the payment when the link is accessed. If this payment link is associated with an invoice, this must match the invoice payer. (ID prefix: acct)
Pattern:
^acct_[A-Za-z0-9]+$qr_urlstringRead-only
A URL to a QR code image representing the payment link. When accessed, this URL returns a scannable QR code that encodes the payment link URL. Customers can scan this QR code with their mobile device camera to quickly access the payment page. Useful for in-person payments, printed invoices, or displaying payment options on screens. Read-only field that is automatically generated alongside the payment link.
statusenum[string]
The current status of the payment link. Possible values: "active" (link is ready to use but not yet sent), "sent" (email notification has been delivered to the customer), "received" (customer received the email), "opened" (customer clicked the link), "bounced" (email delivery failed), "completed" (payment was successfully processed), "inactive" (link has been manually deactivated), "expired" (link has passed its expiration date). Status automatically updates based on link activity and usage. Read-only field that tracks the payment link lifecycle.
Values:
active, sent, received, opened, bounced, completed, inactive, expiredRead-only permissions:
"Undocumented"transaction_id ID of Transactionstring
The unique identifier of the transaction created when this payment link was successfully used to process a payment. This field is null until the customer completes payment through the link. Once payment is processed, this links to the transaction record containing payment method details, amount, and processing status. Read-only field that is automatically set when payment succeeds. (ID prefix: txn)
Pattern:
^txn_[A-Za-z0-9]+$Read-only permissions:
"Undocumented"typeenum[string]
The intended usage pattern for this payment link. Set to "one_time" for links that should be used once and expire after 60 days, or "reusable" for links that can be used multiple times and remain valid for a much longer period.
Values:
one_time, reusableurlstringRead-only
The secure URL that customers can visit to make a payment. This is a shortened, user-friendly link that redirects to the hosted payment page. Share this URL with customers via email, SMS, or embed it in your application. The link includes authentication credentials and provides access to the payment form. Read-only field that is automatically generated when the payment link is created.