Payment modes
Choose between a single payment and multiple partial payments against one link.
Choosing a mode
| Single payment | Partial payments | |
|---|---|---|
| Set with | allowPartialFulfillment: false (default) | allowPartialFulfillment: true |
| Amount shown to the payer | The full amount, fixed | The outstanding balance, payer chooses how much to pay now |
| Payments beneath the execution | One successful payment | Several, until the total is collected |
Status becomes closed when | The first payment succeeds | paidAmount reaches amount |
| Reopens after a refund | No | Possibly. See Refunds below |
| Reconciliation complexity | Linear and deterministic | Depends on cumulative paidAmount |
Both modes use the same endpoints, the same webhook model, and the same hosted page (See what the payer sees here). Behavior is determined by the flag.
Choose single payment when a fixed invoice must be paid in full, no installments are needed, and you want the simplest possible reconciliation.
Choose partial payments when you need deposits or installments, when payment timing is flexible, when several people may contribute towards one total, or when a large balance is settled over time.
Both modes use the one-link-one-execution model described in How it works.
Single payment
The payer sees the full amount and cannot change it. On the first successful payment the status becomes closed and no further payment is accepted.
If a payment fails, the payer can retry while the link is still enabled. Retries create additional payments beneath the same execution, and only one of them can succeed.
Partial payments
The payer sees the outstanding balance and enters the amount they want to pay now, up to that balance. Each successful payment increases paidAmount and triggers a webhook. The link stays enabled until paidAmount reaches amount.
All of those payments sit beneath the one execution for that link, which gives you a single place to see the full payment history for one request.
Overpayment is not possible. The hosted page validates the entered amount against the outstanding balance.
Calculating the outstanding balance
The API does not return a remaining balance. It returns
amountandpaidAmount. Compute the balance yourself asamount.valueminuspaidAmount.value.Both are decimal strings, not numbers. Parse them with a decimal type rather than a float, or rounding will drift across repeated partial payments.
Read paidAmount from Payrails rather than accumulating it yourself from the webhooks you have seen. It is authoritative and already accounts for refunds, failures, and retries.
Refunds
Refunds arrive as webhook events and change paidAmount.
| Mode | Effect of a refund |
|---|---|
| Single payment | Affects payment accounting. The link does not automatically reopen |
| Partial payments | Reduces paidAmount, so the outstanding balance rises. A link that had closed may become payable again, depending on configuration and status, for example if it has not expired and has not been deleted |
A refund references the payment it reverses. The payment history beneath the execution stays intact as an audit trail.
If payment is still owed after a refund on a single payment link, create a new link.
Chargebacks and disputes
A payment may later be challenged or reversed. Disputes and chargebacks arrive as webhook events referencing the original payment.
Treat a chargeback as a reversal of a successful payment and update your balances and records accordingly.
Expiry
expiresAt is required on every link. Set it as an ISO 8601 timestamp with timezone.
After that time the status becomes expired, the payer sees an expiry message, and no new payment can start. Expiry never cancels or reverses payments that already completed, and an expired link cannot be reactivated — create a new one.
Pick expiry windows deliberately. Too short and your payer finds an expired link; too long and stale payment requests accumulate. In partial payments mode the window has to cover the whole installment schedule, not just the first payment.
Next steps
Updated 12 minutes ago