Configure o payment link

Este guia cobre duas configurações realizadas antes ou durante a criação de um payment link: upload de imagens para os produtos e configuração de parcelamento por país e bandeira de cartão.

Como funciona

Este guia cobre duas configurações independentes realizadas antes ou durante a criação de um payment link: upload de imagens para os produtos e configuração de parcelamento por país e bandeira de cartão. Principais características:

• Imagens de produto — faça o upload de uma imagem primeiro para obter um image_id, depois referencie esse image_id no array products ao criar ou atualizar o link. Você pode, opcionalmente, consultar o conteúdo binário de uma imagem pelo seu identificador. Os formatos aceitos são PNG e JPEG, com até 250 MB.
• Business configurations — o estabelecimento pode, opcionalmente, habilitar ou desabilitar operações de pagamento específicas (crédito, débito, Boleto, Pix e outras), o que determina os métodos exibidos no checkout.
• Parcelamento (somente crédito) — o parcelamento é configurado por bandeira de cartão de crédito, dentro de payment.credit.brands[].supported_installments; null ou ausente significa pagamento único. Métodos baseados em cartão (credit, debit) usam um array brands[] para configuração por bandeira, enquanto os demais métodos usam apenas o toggle { "enabled": true }.
• Como os campos de parcelamento se relacionam — installments lista as quantidades válidas, installments_with_interest marca quais delas possuem juros, e installments_with_increase atribui uma taxa percentual a grupos de parcelas.
• Schemas específicos por região — o schema determina as regras de parcelamento e varia por país (por exemplo, plan_lojista / plan_emissor no Brasil, plan_emisor / cuota_comercio no Chile e plan_prosa no México).

A configuração de imagens de produto segue uma sequência curta:

Antes de começar

• Obtenha um token de acesso. Veja Authentication.

Imagens de produto

Para exibir uma imagem em um produto do payment link, faça o upload da imagem primeiro. Use o image_id retornado no campo image_id do objeto products ao criar ou atualizar o link.

Passo 1 - Fazer upload da imagem

Regras de preenchimento dos campos:

• Content-Type: multipart/form-data
• Formatos aceitos: image/png, image/jpeg
• Tamanho máximo: 250 MB

Campos obrigatórios

Exemplo de requisição

curl https://api-sbx.pre.globalgetnet.com/dpy/payment-link/v1/payment-links/products/images \
  --request POST \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: multipart/form-data' \
  --form 'file='

Exemplo de resposta

{
    "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002",
    "original_name": "product-photo.png",
    "mime_type": "image/png",
    "upload_at": "2026-06-10T14:30:00.000Z"
}

Passo 2 — Referenciar a imagem em um produto

Use o image_id retornado ao montar o array products na criação ou atualização do link:

"products": [
   {
      "product_type": "physical_goods",
      "title": "Camiseta Oficial Getnet",
      "amount": 9990,
      "quantity": 1,
      "image_id": "6697e354-ab4a-11eb-bcbc-0242ac130002"
   }
]

Passo 3 (opcional) — Consultar a imagem

Use este endpoint para recuperar o conteúdo binário de uma imagem pelo seu identificador.

Exemplo de requisição

curl https://api-sbx.pre.globalgetnet.com/dpy/payment-link/v1/payment-links/products/images/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'

A resposta 200 OK retorna o conteúdo binário com o Content-Type correspondente (image/png ou image/jpeg).

Exemplo de resposta

{
  "type": "string",
  "contentMediaType": "application/octet-stream"
}

Business configurations

O estabelecimento pode configurar seu payment link, de forma opcional, habilitando ou desabilitando operações de pagamento específicas. Essas configurações determinam quais métodos de pagamento — como cartão de crédito, cartão de débito, Boleto ou Pix (pagamento instantâneo) — são exibidos durante o checkout.

Parcelamento

O parcelamento é configurado dentro de cada bandeira de crédito, em payment.credit.brands[].supported_installments. Cada entrada é um objeto InstallmentPlan que representa um schema de parcelamento oferecido pelo adquirente ou emissor.

Métodos baseados em cartão (credit, debit) possuem um array brands[] para configuração por bandeira. Os demais métodos usam apenas o toggle { "enabled": true }. O parcelamento aplica-se somente ao crédito; null ou ausente significa pagamento único.

Para entender as regras de parcelamento de cada país, acesse Regras e disponibilidade de parcelamento

Campos obrigatórios

Campos opcionais

Exemplo de requisição

curl https://api-sbx.pre.globalgetnet.com/dpy/payment-link/v1/payment-links/business-configurations \
  --request POST \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...' \
  --header 'Content-Type: application/json' \
  --data '{
  "expiration": "2026-12-31T23:59:59",
  "max_orders": 100,
  "request_delivery_address": false,
  "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]
            }
          ]
        }
      ]
    },
    "debit": {
      "enabled": true,
      "brands": [
        {
          "enabled": true,
          "brand": "VISA",
          "currencies": [
            "BRL"
          ],
          "threeds": true
        }
      ]
    },
    "bankslip": {
      "enabled": true
    },
    "instant_payment": {
      "enabled": true
    },
    "google_pay": {
      "enabled": false
    },
    "apple_pay": {
      "enabled": false
  },
  "currency": "BRL"
}'

Como os campos se relacionam

• installments lista as quantidades de parcelas válidas. Por exemplo, [2, 3, 6, 12] permite ao comprador pagar em 2, 3, 6 ou 12 parcelas.

• installments_with_interest indica quais dessas parcelas possuem juros. Se installments = [2,3,6,12] e installments_with_interest = [6,12], então 2 e 3 parcelas são sem juros, enquanto 6 e 12 parcelas possuem juros.

• installments_with_increase fornece precificação baseada em taxa: cada entrada agrupa parcelas e atribui uma taxa percentual.

Objeto InstallmentsWithIncrease

Exemplo:

"installments_with_increase": [
  { "installments": [3, 6], "rate": 1.5 },
  { "installments": [9, 12], "rate": 2.99 }
]

Nesse caso, parcelas de 3 e 6 possuem aumento de 1,5%, e parcelas de 9 e 12 possuem aumento de 2,99%.

Schemas regionais

Exemplos por país

Brasil — plan_lojista + plan_emissor

{
    "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]
       },
       {
          "schema": "plan_emissor",
          "schema_name": "Plan Emissor",
          "installments": [2,3,4,5,6],
          "installments_with_interest": []
       }
    ]
}

Chile - plan_emisor + cuota_comercio

{
    "enabled": true,
    "brand": "VISA",
    "currencies": ["CLP"],
    "threeds": true,
    "supported_installments": [
      {
        "schema": "plan_emisor",
        "schema_name": "Plan Emisor",
        "installments": [2, 3, 4, 5, 6],
        "installments_with_interest": [4, 5, 6]
      },
      {
        "schema": "cuota_comercio",
        "schema_name": "Cuota Comercio",
        "installments": [2, 3, 6, 9, 12],
        "installments_with_interest": [6, 9, 12]
      }
    ]
  }

México — plan_prosa

{
    "enabled": true,
    "brand": "VISA",
    "currencies": ["MXN"],
    "threeds": true,
    "supported_installments": [
      { "schema": "plan_prosa", "schema_name": "Plan Prosa", "installments": [3,6,9,12], "installments_with_interest": [3,6,9,12] }
    ]
}

Exemplo com installments_with_increase

{
    "enabled": true,
    "brand": "MASTERCARD",
    "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],
          "installments_with_increase": [
             { "installments": [2,3,4,5,6], "rate": 1.5 },
             { "installments": [7,8,9,10,11,12], "rate": 2.99 }
          ],
          "single_increase_rate": false
       }
    ]
}

Próximos passos

• Como criar um payment link