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.

Before you begin

  • 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.
type fieldBehavior
custom (default)Link with predefined products and fixed amounts. Requires products.

Build the request

Base fields

FieldTypeRequiredDescription
labelstringYesIdentification tag (6–36 characters)
expirationstringNoExpiration date. Maximum 1 year
max_ordersintegerNoMaximum number of sales before expiration (min: 1)
typestringNoDefault custom
request_delivery_addressbooleanNoRequest delivery address
shipping_amountintegerConditionalRequired when request_delivery_address=true. Value in integer format (see note on amounts below)
productsarrayConditionalProduct catalog. Required for custom
paymentobjectYesPayment configuration
currencystringYesCountry currency: BRL or MXN
information icon
About monetary 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).

Fields for each product (products[])

FieldTypeRequiredDescription
product_typestringYesSee valid values in the product data model
titlestringYesProduct title (max: 128)
descriptionstringNoProduct description (max: 1024)
order_prefixstringNoOrder ID prefix (max: 10)
amountintegerYesPurchase amount (see note on amounts above)
quantityintegerNoQuantity (default: 1)
image_idstring (UUID)NoReference to the image uploaded via POST /payment-links/products/images

payment object

At least one of credit, debit, bankslip, c2p_master, or instant_payment must be present.
FieldTypeRequiredDescription
payment.creditobjectNoCredit configuration with brands[]
payment.debitobjectNoDebit configuration with brands[]
payment.bankslipobjectNoBoleto (Brazil only)
payment.instant_paymentobjectNoPix (Brazil only)
payment.google_payobjectNoGoogle Pay (Brazil only)
payment.apple_payobjectNoApple Pay (Brazil only)
payment.c2p_masterobjectNoClick to Pay (Argentina only)

For the detailed structure of credit, debit, card brands, and installments, see Configure the payment link.

Request example

Example (Brazil — credit + debit + Boleto + Pix):

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 }, "google_pay": { "enabled": true }, "apple_pay": { "enabled": true }, "c2p_master": { "enabled": false } }, "currency": "BRL" }'
The short_id returned is the public identifier used in the shareable link URL.
Response example
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 }, "google_pay": { "enabled": true }, "apple_pay": { "enabled": true }, "c2p_master": { "enabled": false } }, "status": "ACTIVE", "created_at": "2026-06-04T12:00:00.000Z", "updated_at": "2026-06-04T12:00:00.000Z", "currency": "BRL" }

Next steps

On this page

How to create a payment link