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.
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.

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.

Example of request

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.

{
  "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"
}