# How to create a payment link A payment link is a shareable URL tied to a product catalog and a payment configuration. This guide shows how to create a link using the `POST /payment-links` endpoint. ## How it works Key characteristics: - **Single creation call**: you define the link's identification, product catalog, and accepted payment methods in one request; the response returns the `link_id` and a `short_id`. - **Shareable URL**: the `short_id` returned is the public identifier used in the shareable link URL. - **Product catalog**: a `custom` link (the default type) carries predefined products with fixed amounts, so the `products` array is required. - **Configurable payment methods**: you enable methods per link (credit, debit, Boleto, Pix), with at least one of `credit`, `debit`, `bankslip`, or `instant_payment` required. - **Optional limits**: you can set an `expiration` (max 1 year) and a `max_orders` cap on the number of sales before the link expires. - **Optional delivery**: when `request_delivery_address` is `true`, the buyer is asked for a delivery address and `shipping_amount` becomes required. ## Before you start - Obtain an access token. See [Authentication](/en/payment-link-api/first-step-plk/authentication-token-plk). - Have the `x-seller-id` of the merchant on hand. - If the link uses product images, upload the images first and save the `image_id`. See [Configure the payment link](/en/payment-link-api/first-step-plk/configure-link-plk). ## Build the request Endpoint| ---| `POST /payment-links` **Required fields** | Field | Type | Description | Example | | --- | --- | --- | --- | | `label` | string | Identification tag (6–36 characters) | `black-friday-2026`| | `payment` | object | Payment configuration | --- | | `currency` | string | Country currency | `BRL`, `CLP` or `MXN` | | `products.product_type` | string | See valid values in the product data model | `physical_goods` | | `products.title` | string | Product title (max: 128) | `Camiseta Oficial Getnet`| | `products.amount` | integer | Purchase amount (see note on amounts above) | `15000`| **Conditional fields** | Field | Type | Description | Example | | --- | --- | --- | --- | | `shipping_amount` | integer | Required when `request_delivery_address=true`. Value in integer format (see note on **Field filling rules** section) | `500`| | `products` | array | Product catalog. Required for `custom` | --- | | `payment.credit.brands.brand`| Card brand. Required when `payment.credit.enabled=true`. | `VISA` | **Optional fields** | Field | Type | Description | Example | | --- | --- | --- | --- | | `expiration` | string | Expiration date. Maximum 1 year | `2026-12-31T23:59:59` | | `max_orders` | integer | Maximum number of sales before expiration (min: 1) | `100`| | `type` | string | Link type | `custom` | | `request_delivery_address` | boolean | Request delivery address | `true` or `false`| | `products.description` | string | Product description (max: 1024) | `Camiseta 100% algodão, tamanho M`| | `products.order_prefix` | string | Order ID prefix (max: 10) | `BF2026`| | `products.quantity` | integer | Quantity (default: 1) | `2`| | `products.image_id` | string | Reference to the image uploaded via `POST /payment-links/products/images` | `6697e354-ab4a-11eb-bcbc-0242ac130002`| | `payment.credit` | object | Credit configuration | --- | | `payment.debit` | object | Debit configuration with | --- | | `payment.bankslip` | object | Boleto (Brazil only) | --- | | `payment.instant_payment` | object | Pix (Brazil only) | --- | **Field Values** | Field | Value | ---|---| `product_type`| `cash_carry`, `digital_content`, `digital_goods`, `digital_physical`, `gift_card`, `physical_goods`, `renew_subs`, `shareware` or `service`| `brand` | `VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD` or `CARNET`| #### Field filling rules: * **Amounts:** provide the value in integer format, where the last 2 digits represent cents. For countries where cents do not apply, fill in the value with 2 trailing zeros (e.g., \$150 → send `15000`). * At least one of `credit`, `debit`, `bankslip`, or `instant_payment` must be present. For the detailed structure of credit, debit, card brands, and installments, see [Configure the payment link](/en/payment-link-api/first-step-plk/configure-link-plk). #### Example of request ```json curl -X POST "${API_URL}/payment-links" \ -H "Authorization: Bearer ${ACCESS_TOKEN}" \ -H "x-seller-id: ${SELLER_ID}" \ -H "country: BR" \ -H "tenant: santander" \ -H "Content-Type: application/json" \ -d '{ "label": "black-friday-2026", "expiration": "2026-12-31T23:59:59", "max_orders": 100, "type": "custom", "request_delivery_address": false, "products": [ { "product_type": "physical_goods", "title": "Camiseta Oficial Getnet", "description": "Camiseta 100% algodão", "order_prefix": "BF2026", "amount": 9990, "quantity": 1, "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002" } ], "payment": { "credit": { "enabled": true, "brands": [ { "enabled": true, "brand": "VISA", "currencies": ["BRL"], "threeds": true, "supported_installments": [ { "schema": "plan_lojista", "schema_name": "Plan Lojista", "installments": [2,3,4,5,6,7,8,9,10,11,12], "installments_with_interest": [6,9,12] } ] }, { "enabled": true, "brand": "MASTERCARD", "currencies": ["BRL"], "threeds": true, "supported_installments": [ { "schema": "plan_lojista", "schema_name": "Plan Lojista", "installments": [2,3,6], "installments_with_interest": [] } ] } ] }, "debit": { "enabled": true, "brands": [ { "enabled": true, "brand": "VISA", "currencies": ["BRL"], "threeds": true }, { "enabled": true, "brand": "MASTERCARD", "currencies": ["BRL"], "threeds": true } ] }, "bankslip": { "enabled": true }, "instant_payment": { "enabled": true } }, "currency": "BRL" }' ``` #### Example of response The `short_id` returned is the public identifier used in the shareable link URL. ```json { "link_id": "76c3caa9-4c5b-243b-8fc5-a73381fcdf9b", "short_id": "ZDdlNmM1YTg", "seller_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "label": "black-friday-2026", "expiration": "2026-12-31T23:59:59.000Z", "max_orders": 100, "type": "custom", "successful_sales": 0, "request_delivery_address": false, "shipping_amount": 0, "products": [ { "product_type": "physical_goods", "title": "Camiseta Oficial Getnet", "description": "Camiseta 100% algodão", "order_prefix": "BF2026", "amount": 9990, "quantity": 1, "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002" } ], "payment": { "credit": { "enabled": true, "brands": [ { "enabled": true, "brand": "VISA", "currencies": ["BRL"], "threeds": true, "supported_installments": [ { "schema": "plan_lojista", "schema_name": "Plan Lojista", "installments": [2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12], "installments_with_interest": [6, 9, 12] } ] }, { "enabled": true, "brand": "MASTERCARD", "currencies": ["BRL"], "threeds": true, "supported_installments": [ { "schema": "plan_lojista", "schema_name": "Plan Lojista", "installments": [2, 3, 6], "installments_with_interest": [] } ] } ] }, "debit": { "enabled": true, "brands": [ { "enabled": true, "brand": "VISA", "currencies": ["BRL"], "threeds": true }, { "enabled": true, "brand": "MASTERCARD", "currencies": ["BRL"], "threeds": true } ] }, "bankslip": { "enabled": true }, "instant_payment": { "enabled": true } }, "status": "ACTIVE", "created_at": "2026-06-04T12:00:00.000Z", "updated_at": "2026-06-04T12:00:00.000Z", "currency": "BRL" } ``` ## Next steps - [How to manage the lifecycle of a link](/en/payment-link-api/payment-guides-plk/howto-manage-life-cicle-plk) - [How to retrieve and list payment orders](/en/payment-link-api/payment-guides-plk/howto-retrieve-list-payment-orders-plk)