Paylinks API
Request fields, responses, pagination, and immutable billing terms for reusable payment links.
All private endpoints use the HTTP API authentication contract. A Paylink is a reusable hosted checkout for a fixed product price. Dynamic totals belong in Checkout Sessions.
Create a Paylink
POST /api/private/paylinks/create
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | Non-empty product or plan name, up to 255 characters. |
price | decimal string | yes | At least 0.01 in the pricing currency, up to 64 characters. Use a string to preserve decimal precision. |
type | enum | no | ONE_TIME (default) or RECURRING. |
currency | enum | no | USD (default), EUR, or CNY. |
description | string | no | Up to 1,000 characters. |
imageUrl | string | no | Public HTTP(S) image URL, up to 2,048 characters. |
collectEmail | boolean | no | Show the buyer-email field. Defaults to false; payment invoice creation still requires an effective customer email. |
collectName | boolean | no | Collect customer name. Defaults to false. |
collectDateOfBirth | boolean | no | Collect date of birth. Defaults to false. |
collectAddress | boolean | no | Collect address. Defaults to false. |
collectPhoneNumber | boolean | no | Collect phone number. Defaults to false. |
recurringInterval | enum | for recurring | Base interval from the table below. |
recurringIntervalCount | integer | no | Multiplier for the interval; defaults to 1 for recurring links. |
metadata | object | no | Checkout settings and primitive metadata, described below. |
paymentMetadata | object | no | Merchant metadata propagated to payment handling. See limits below. |
| Interval | Maximum multiplier |
|---|---|
TWO_DAYS | 183 |
WEEK | 52 |
BIWEEK | 26 |
MONTH | 12 |
BIMONTH | 6 |
QUARTER | 4 |
BIANNUAL | 2 |
YEARLY | 1 |
recurringIntervalCount must be at least 1. Recurring payments are customer-authorized renewals, not automatic wallet debits.
Metadata
Both metadata objects accept at most 20 keys. Keys contain letters, numbers, underscores, or hyphens and are 1-64 characters. Primitive values are finite numbers, booleans, or strings of at most 500 characters. paymentMetadata accepts only these primitives.
metadata additionally accepts:
afterCompletion:{ "type": "SHOW_MESSAGE", "message": "Thank you" }or{ "type": "REDIRECT", "redirectUrl": "https://example.com/thanks" }. The message can contain up to 1,000 characters; redirect URLs must be HTTP(S) and at most 2,048 characters. See after-payment behavior.paymentMethodTypes: an array containingCONNECT_WALLET,WALLET_TRANSFER, or both, without duplicates.
Response
Creation returns { "success": true, "data": <paylink> }. Save data.id; the hosted URL is https://pay.yolfi.com/{paylinkId}. The returned Paylink includes its saved product and billing fields, enabled state, and timestamps. Read it back to verify the configuration before sharing the URL.
Minimum payment amounts
The minimum price is 0.01 in the Paylink's pricing currency (USD, EUR, or CNY).
The backend rejects a lower price when the merchant creates the link. Exactly 0.01 passes this
price validation. The merchant's enabled payment networks and cryptocurrencies are unchanged;
network-specific payment and settlement requirements still apply.
List Paylinks
GET /api/private/paylinks?page=1&rows=10&filter=all
| Query | Default | Allowed values |
|---|---|---|
page | 1 | Positive integer. |
rows | 10 | Integer from 1 to 100. |
filter | all | all, one-time, recurring, or disabled. |
Returns { "success": true, "data": [...], "total": 42 }. one-time and recurring select enabled links of that type. all can include disabled links. Lists are ordered by creation time, newest first. Continue pagination until all relevant entries are inspected before deciding no matching link exists.
Read a Paylink
GET /api/private/paylinks/{id}
Returns { "success": true, "data": <paylink> } for a link in the authenticated organization. Invalid or unavailable IDs can return success: false; inspect the response body as well as the HTTP status.
Edit a Paylink
POST /api/private/paylinks/edit
Send required UUID id plus any of: name, description, imageUrl, collectEmail, collectName, collectDateOfBirth, collectAddress, collectPhoneNumber, metadata, or paymentMetadata, using the types and limits above. Omitted fields keep their existing values.
Price, currency, payment type, and recurring cadence are not editable through this endpoint. For changed billing terms, create an explicitly approved replacement link and decide how to handle the previous one. Do not attempt to modify price by placing it in metadata.
Disable a Paylink
POST /api/private/paylinks/disable
{ "id": "120e3400-e12b-04d4-a716-446417440031" }Disabling changes the link's availability. Perform it only when requested, and verify the saved state. Do not disable a working link simply because an integration retry occurred.