# Paylinks API (/en/paylinks/api-reference)



All private endpoints use the [HTTP API authentication](/en/api#authentication) contract. A Paylink is a reusable hosted checkout for a fixed product price. Dynamic totals belong in [Checkout Sessions](/en/checkout/api-reference).

Create a Paylink [#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 [#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](/en/paylinks/after-payment).
* `paymentMethodTypes`: an array containing `CONNECT_WALLET`, `WALLET_TRANSFER`, or both, without duplicates.

Response [#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 [#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 [#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 [#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 [#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 [#disable-a-paylink]

`POST /api/private/paylinks/disable`

```json
{ "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.