Checkout URL Parameters
Prefill customer fields and attach your own reference by adding query parameters to a payment link.
Overview
You can add query parameters to a payment link URL to prefill the checkout form and attach your own identifiers. The hosted checkout reads these parameters and includes them when the payment (invoice) is created, so they flow through to your webhooks.
This is the recommended way to tie a payment back to a user or order in your system:
pass clientReferenceId, and it is returned on payment and invoice webhook events as
customer.clientReferenceId.
Usage
Append parameters to the payment link URL:
https://pay.yolfi.com/{paylink-id}?clientReferenceId=user_123&email=customer@example.comThey also work together with the language prefix:
https://pay.yolfi.com/{language}/{paylink-id}?clientReferenceId=user_123Supported Parameters
| Parameter | Description |
|---|---|
clientReferenceId | Your internal customer or order reference. Returned as customer.clientReferenceId in webhook payloads. |
email | Prefills the customer email. |
name | Prefills the customer name. |
phone | Prefills the customer phone. |
dob | Prefills the customer date of birth. |
address | Prefills the customer address. |
subscriptionId | Associates the payment with an existing subscription. |
metadata[KEY] | Adds a string metadata field to the invoice and signed webhook events. |
All parameters are optional. Values must be URL-encoded (for example, encode @ in an
email address as %40).
Metadata keys may contain letters, numbers, _, and -. For example:
https://pay.yolfi.com/{paylink-id}?metadata[order_id]=order_123&metadata[campaign]=summerMetadata supplied by the browser is attribution context, not authentication. A Paylink's
server-controlled paymentMetadata has priority over query metadata and is the appropriate
place for routing values that buyers must not be able to change.
How it reaches your webhooks
When the customer completes checkout, these values are attached to the created invoice's
customer and delivered in your webhook events (see Webhook Details).
Use clientReferenceId (or email) to match the payment to a customer in your system.
Note:
clientReferenceIdis included on invoice and payment events (for examplepayment.confirmed). Metadata remains scoped to the payment that created the event; it is not copied from the first checkout onto later subscription renewals.
Setting it server-side
If you create payments through the API instead of sharing a link, set the same
clientReferenceId field directly in the POST /api/public/payments request body.
Redirect after payment
Post-payment redirects are configured on the Payment Link; they are not checkout URL parameters. See After a Payment to configure a basic redirect or optionally pass the Checkout Session ID to your return page.