Como criar um payment link

Um payment link é uma URL compartilhável vinculada a um catálogo de produtos e a uma configuração de pagamento. Este guia mostra como criar um link usando o endpoint POST /payment-links.

Como funciona

Principais características:

Chamada única de criação: você define a identificação do link, o catálogo de produtos e os métodos de pagamento aceitos em uma única requisição; a resposta retorna o link_id e um short_id.
URL compartilhável: o short_id retornado é o identificador público usado na URL do link compartilhável.
Catálogo de produtos: um link custom (o tipo padrão) contém produtos predefinidos com valores fixos, portanto o array products é obrigatório.
Métodos de pagamento configuráveis: você habilita os métodos por link (crédito, débito, Boleto, Pix), sendo obrigatório pelo menos um entre credit, debit, bankslip ou instant_payment.
Limites opcionais: você pode definir uma expiration (máx. 1 ano) e um limite max_orders para o número de vendas antes da expiração do link.
Entrega opcional: quando request_delivery_address é true, o comprador é solicitado a informar um endereço de entrega, e shipping_amount passa a ser obrigatório.

Antes de começar

Obtenha um token de acesso. Veja Authentication.
Tenha em mãos o x-seller-id do estabelecimento.
Se o link usar imagens de produto, faça o upload das imagens primeiro e guarde o image_id. Veja Configure o payment link.

Monte a requisição

Endpoint
`POST /payment-links`

Campos obrigatórios

Campo	Tipo	Descrição	Exemplo
`label`	string	Tag de identificação (6–36 caracteres)	`black-friday-2026`
`payment`	object	Configuração de pagamento	---
`currency`	string	Moeda do país	`BRL`, `CLP` ou `MXN`
`products.product_type`	string	Veja os valores válidos no modelo de dados de produtos	`physical_goods`
`products.title`	string	Título do produto (máx: 128)	`Camiseta Oficial Getnet`
`products.amount`	integer	Valor da compra (veja a nota sobre valores acima)	`15000`

Campos condicionais

Campo	Tipo	Descrição	Exemplo
`shipping_amount`	integer	Obrigatório quando `request_delivery_address=true`. Valor em formato inteiro (veja a nota na seção Regras de preenchimento de campos)	`500`
`products`	array	Catálogo de produtos. Obrigatório para `custom`	---
`payment.credit.brands.brand`	Bandeira do cartão. Obrigatório quando `payment.credit.enabled=true`.	`VISA`

Campos opcionais

Campo	Tipo	Descrição	Exemplo
`expiration`	string	Data de expiração. Máximo 1 ano	`2026-12-31T23:59:59`
`max_orders`	integer	Número máximo de vendas antes da expiração (mín: 1)	`100`
`type`	string	Tipo de link	`custom`
`request_delivery_address`	boolean	Solicitar endereço de entrega	`true`ou `false`
`products.description`	string	Descrição do produto (máx: 1024)	`Camiseta 100% algodão, tamanho M`
`products.order_prefix`	string	Prefixo do ID do pedido (máx: 10)	`BF2026`
`products.quantity`	integer	Quantidade (padrão: 1)	`2`
`products.image_id`	string	Referência da imagem enviada via `POST /payment-links/products/images`	`6697e354-ab4a-11eb-bcbc-0242ac130002`
`payment.credit`	object	Configuração de crédito	---
`payment.debit`	object	Configuração de débito com	---
`payment.bankslip`	object	Boleto (somente Brasil)	---
`payment.instant_payment`	object	Pix (somente Brasil)	---

Valores dos campos

Campo	Valor
`product_type`	`cash_carry`, `digital_content`, `digital_goods`, `digital_physical`, `gift_card`, `physical_goods`, `renew_subs`, `shareware` ou `service`
`brand`	`VISA`, `MASTERCARD`, `AMEX`, `ELO`, `HIPERCARD` ou `CARNET`

Regras de preenchimento de campos:

Valores: informe o valor em formato inteiro, em que os últimos 2 dígitos representam os centavos. Para países em que os centavos não se aplicam, preencha o valor com 2 zeros à direita (ex.: $150 → envie 15000).
Pelo menos um dos campos credit, debit, bankslip ou instant_payment deve estar presente.

Para a estrutura detalhada de crédito, débito, bandeiras de cartão e parcelas, veja Configure o payment link.

Exemplo de requisição

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

Exemplo de resposta

O short_id retornado é o identificador público usado na URL do link compartilhável.

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