How it works

The lifecycle

graph LR
    A["Create link<br>(API or Portal)"] --> B["Share URL<br>with customer"]
    B --> C["Customer pays on<br>hosted page"]
    C --> D["Webhook sent<br>to your backend"]
    D --> E["Link closes"]

Create. Your backend calls the Payrails API, or you create the link in the Portal. Payrails returns a hosted payment page URL.
Share. You send the URL to your customer through any channel.
Pay. The customer opens the link and pays on the Payrails-hosted page.
Notify. Payrails sends a webhook to your backend with the outcome following the configured workflow.
Close. The link closes when it is fully paid, expires, or you delete it.

ℹ️
Webhooks are the source of truth for payment state. Do not rely on the confirmation screen the customer sees, on a redirect, or on an API response alone. See Track and reconcile.

One link, one execution, many payments

graph LR
    A["Drop-in link<br>(the payment request)"] --> B["Execution<br>(one per link)"]
    B --> C["Payment 1"]
    B --> D["Payment 2"]
    B --> E["Payment n"]

Object	What it represents
Drop-in link	The payment request: total amount, currency, expiry, description, and the rules for collection. It is not a payment
Execution	The workflow execution behind the link. There is exactly one per link, created when the link is first used. Its ID appears on the link as `executionId`
Payment	An individual payment made against that execution. One in single payment mode, several in partial payments mode

This is the standard Payrails execution-and-payment model, so reporting and cross-referencing behave the same as for any other execution.

paidAmount on the link accumulates across the payments beneath the execution.

Who is responsible for what

Payrails handles	You handle
Hosting the payment page	Creating and configuring links
PCI compliance and page security	Sharing links with your customers
Payment processing, authorization, and capture	Hosting and securing a webhook endpoint
3-D Secure enforcement	Processing webhook events idempotently
Accumulating `paidAmount` across payments	Updating your own systems, such as CRM, ERP, or order management
Execution and payment lifecycle management	All customer communications: receipts, confirmations, reminders, refund notices

Link statuses

Status	Meaning	What causes it
`enabled`	The link can accept payment. A payment may have been attempted but not completed successfully	The initial state after creation
`closed`	Fully paid. No further payment is accepted	Single mode: one successful payment. Partial mode: `paidAmount` reaches `amount`
`expired`	Past `expiresAt`. No new payment can start, and it cannot be reactivated	The expiry timestamp passed
`deleted`	Deleted by you. No new payment can start, and it cannot be restored	You called the delete endpoint

Completed payments remain valid in all of these states, and the link record stays readable.

Failed payments do not change the status. The link stays enabled and the payer can retry.

State transitions are calculated by Payrails. Webhooks tell you the outcome of each payment, but they do not drive the status themselves.

Next steps

Create a payment link
Payment modes — how single and partial payments differ