Links de Pagamento

Visão Geral

Os Links de Pagamento permitem criar um checkout pré-configurado com itens, formas de pagamento e regras de expiração. Compartilhe o link gerado com seus clientes — eles acessam, confirmam os dados e pagam diretamente, sem que você precise criar uma cobrança manualmente. Cada link gera uma URL de checkout única com token de segurança. O link pode ser reutilizado (com ou sem limite de usos) e expira automaticamente quando a data ou o número máximo de pagamentos é atingido.

Métodos de Pagamento Suportados

Método	Descrição
`CreditCard`	Cartão de crédito (parcelado ou à vista)
`PIX`	Pagamento instantâneo via PIX
`Boleto`	Boleto bancário

Se payment_types for omitido na criação, todos os métodos ativos na conta serão exibidos no checkout.

Header obrigatório

Todas as rotas de links de pagamento exigem o header account com o código da conta:

account: acc_abc123xyz

Formato de resposta padrão

{
  "mensagem": "Mensagem descritiva",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 200,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": { ... }
}

Campo	Tipo	Descrição
`mensagem`	string	Mensagem descritiva da operação
`erro`	boolean	`false` em caso de sucesso, `true` em caso de erro
`mensagenserro`	array	Lista de mensagens de erro (vazia em caso de sucesso)
`codigoretorno`	integer	Código HTTP de retorno
`id`	string	ID do recurso criado/afetado ou GUID vazio
`data`	mixed	Dados retornados (objeto, array ou vazio)

Status de um Link de Pagamento

Status	Descrição
`InProgress`	Link ativo e disponível para pagamento
`Canceled`	Link cancelado manualmente
`Concluded`	Link encerrado após atingir o limite de usos (`max_uses`)

Um link também é considerado inativo quando expires_at é uma data passada, mesmo que o status ainda seja InProgress.

Campos do cliente

O objeto client é opcional. Se omitido, os dados do pagador serão coletados diretamente no checkout no momento do pagamento. Se qualquer campo de client for enviado, todos os campos marcados como obrigatórios abaixo devem estar presentes.

Campo	Tipo	Req.¹	Descrição
`client.name`	string	Sim	Nome completo (máx. 255)
`client.email`	string	Sim	E-mail
`client.phone.ddi`	string	Sim	Código do país (DDI)
`client.phone.ddd`	string	Sim	Código de área (DDD)
`client.phone.number`	string	Sim	Número do telefone
`client.document.type`	string	Sim	`CPF`, `CNPJ`, `passport`, `undefined`
`client.document.number`	string	Sim	Número do documento (CPF/CNPJ validado com dígito)
`client.gender`	string	Não	`Male`, `Female`, `Other`, `Undefined`
`client.birthdate`	date	Não	Data de nascimento (`YYYY-MM-DD`)
`client.address.*`	object	Não²	Endereço (² todos os campos obrigatórios entre si)

¹ Obrigatório quando o objeto client é enviado. Campos de endereço — obrigatórios quando address.street é enviado:

Campo	Tipo	Descrição
`address.zipcode`	string	CEP (máx. 20)
`address.street`	string	Logradouro (máx. 255)
`address.number`	string	Número (máx. 20)
`address.neighborhood`	string	Bairro (máx. 255)
`address.city`	string	Cidade (máx. 255)
`address.state`	string	UF — 2 letras
`address.complement`	string	Complemento (opcional)
`address.country`	string	País (opcional, máx. 255)

Campos dos itens

Campo	Tipo	Req.	Descrição
`items[].id`	string	Sim	Identificador do produto (SKU, UUID ou código)
`items[].description`	string	Sim	Descrição exibida no checkout (máx. 255)
`items[].amount`	decimal	Sim	Valor unitário em reais (ex: `97.99`). Mín: `0.01`
`items[].quantity`	integer	Sim	Quantidade. Mín: `1`

O total dos itens somado ao frete deve ser de no mínimo R$ 5,00.

Configurações do link (`config`)

Todas as chaves de config são opcionais.

Campo	Tipo	Descrição
`payment_types`	array	Métodos exibidos no checkout: `"CreditCard"`, `"PIX"`, `"Boleto"`
`installments`	array	Opções de parcelamento (ver seção abaixo)
`expires_at`	datetime	Data/hora de expiração (`YYYY-MM-DD HH:MM:SS`). `null` = sem expiração
`max_uses`	integer	Máximo de pagamentos aceitos. `null` = ilimitado. Mín: `1`
`freight`	decimal	Frete em reais adicionado ao total. Mín: `0`. Padrão: `0`
`link_name`	string	Nome interno do link (não exibido no checkout). Máx. 255
`order_title`	string	Título exibido no checkout (substitui “Resumo do pedido”). Máx. 255
`soft_descriptor`	string	Texto exibido na fatura do cartão. Máx. 22
`image`	string	URL pública ou base64 da imagem exibida no topo do checkout (ver abaixo)
`image_url`	string	URL de imagem já armazenada. Máx. 1000. Preterido quando `image` é enviado
`pix_expiration`	integer	Expiração do QR Code PIX em horas. Mín: `1`
`pix_discount_value`	decimal	Valor do desconto para pagamentos PIX
`pix_discount_type`	string	Tipo do desconto PIX: `"percentage"` ou `"fixed"`
`obfuscate_client`	boolean	Mascarar dados do pagador no checkout
`obfuscate_items`	boolean	Ocultar nomes e valores dos itens no checkout

Parcelamento (`config.installments`)

As opções de parcelamento são definidas por milestones — cada milestone define a taxa de juros para todas as parcelas desde o milestone anterior até o count informado.

Campo	Tipo	Descrição
`count`	integer	Número de parcelas (1–12)
`interest_rate`	decimal	Fator multiplicador sobre o valor base. `1.0` = sem juros. Mín: `1`

Fórmula: total_cobrado = valor_base × interest_rate

Exemplos de configuração de parcelamento

[
  { "count": 1, "interest_rate": 1 }
]

Exibe somente 1x sem juros.

[
  { "count": 1, "interest_rate": 1 },
  { "count": 12, "interest_rate": 1 }
]

Exibe de 1x a 12x, todos sem juros.

[
  { "count": 2,  "interest_rate": 1    },
  { "count": 6,  "interest_rate": 1.10 },
  { "count": 12, "interest_rate": 1.20 }
]

1x–2x sem juros, 3x–6x com 10%, 7x–12x com 20%.

Se installments for omitido, o checkout exibe apenas 1x sem juros.

Imagem do link (`config.image`)

O campo image aceita dois formatos:

URL pública (https://...): o servidor faz o download, armazena internamente e grava a URL resultante.
Base64 (com ou sem prefixo data:image/...;base64,): o servidor decodifica e armazena.

Formatos aceitos: jpg, png, webp, gif.

Se a imagem não puder ser processada (URL inacessível, formato não suportado, base64 inválido), o link é criado normalmente sem imagem. A resposta incluirá o campo image_warning com a descrição do motivo.

Alternativamente, você pode enviar a imagem antes pelo endpoint de upload e usar a URL resultante em image_url:

POST /links-de-pagamento/upload-imagem
Content-Type: multipart/form-data
Campo: image (arquivo)

Resposta: { "url": "https://...", "path": "payment-links/images/..." }

Desconto PIX (`config.pix_discount_value` / `config.pix_discount_type`)

Concede desconto exclusivo para pagamentos via PIX.

`pix_discount_type`	Comportamento
`"percentage"`	Percentual sobre o valor total (ex: `10` = 10% de desconto)
`"fixed"`	Valor fixo em reais (ex: `5.00` = R$ 5,00 de desconto)

O desconto é aplicado sobre os itens — não incide sobre o frete. O valor final após desconto deve ser de no mínimo R$ 5,00.

O campo "PIX" deve estar presente em payment_types para que o desconto seja aplicado.

Expiração do QR Code PIX (`config.pix_expiration`)

Define o tempo de vida do QR Code PIX em horas. A prioridade de resolução no momento do pagamento é:

payment.pix_expiration no body da cobrança (em segundos — override)
Tempo restante até expires_at (calculado em segundos, mínimo 300 s)
config.pix_expiration × 3600 (convertido para segundos)
Padrão da adquirente (~30 min)

Objeto de resposta do link

Campo	Tipo	Descrição
`code`	string	Código único do link (ex: `lnk_abc123`)
`order_code`	string	Código do pedido gerado na criação
`token`	string	Token de segurança do checkout (64 caracteres hex)
`url`	string	URL completa do checkout para compartilhar
`status`	string	Status atual do link
`payment_types`	array	Métodos de pagamento configurados
`installments`	array	Opções de parcelamento expandidas
`obfuscate_client`	boolean	Dados do pagador mascarados no checkout
`obfuscate_items`	boolean	Itens ocultos no checkout
`expires_at`	datetime	Data/hora de expiração ou `null`
`max_uses`	integer	Limite de pagamentos ou `null` se ilimitado
`uses_count`	integer	Quantidade de pagamentos realizados via este link

Exemplo completo

Criar link de pagamento

{
  "client": {
    "name": "Hugo Belo",
    "email": "hugo@exemplo.com.br",
    "phone": { "ddi": "55", "ddd": "62", "number": "984063942" },
    "document": { "type": "CPF", "number": "71854312120" }
  },
  "items": [
    {
      "id": "plano-premium",
      "description": "Plano Mensal Premium",
      "amount": 97.99,
      "quantity": 1
    }
  ],
  "config": {
    "payment_types": ["CreditCard", "PIX"],
    "installments": [
      { "count": 1,  "interest_rate": 1      },
      { "count": 6,  "interest_rate": 1.1047 },
      { "count": 12, "interest_rate": 1.2    }
    ],
    "expires_at": "2026-12-31 23:59:59",
    "max_uses": 100,
    "link_name": "Black Friday – Plano Premium",
    "order_title": "Plano Mensal Premium",
    "pix_discount_value": 10,
    "pix_discount_type": "percentage",
    "redirect_url": "https://meusite.com.br/obrigado"
  }
}

Resposta (HTTP 201)

{
  "mensagem": "Link de pagamento criado com sucesso",
  "erro": false,
  "mensagenserro": [],
  "codigoretorno": 201,
  "id": "00000000-0000-0000-0000-000000000000",
  "data": {
    "code": "lnk_abc123xyz",
    "order_code": "ord_abc123xyz",
    "token": "a1b2c3d4e5f6...",
    "url": "https://checkout.4seletpay.com.br/lnk_abc123xyz?token=a1b2c3d4e5f6...",
    "status": "InProgress",
    "payment_types": ["CreditCard", "PIX"],
    "installments": [
      { "count": 1,  "interest_rate": 1      },
      { "count": 2,  "interest_rate": 1      },
      { "count": 3,  "interest_rate": 1.1047 },
      { "count": 4,  "interest_rate": 1.1047 },
      { "count": 5,  "interest_rate": 1.1047 },
      { "count": 6,  "interest_rate": 1.1047 },
      { "count": 7,  "interest_rate": 1.2    },
      { "count": 8,  "interest_rate": 1.2    },
      { "count": 9,  "interest_rate": 1.2    },
      { "count": 10, "interest_rate": 1.2    },
      { "count": 11, "interest_rate": 1.2    },
      { "count": 12, "interest_rate": 1.2    }
    ],
    "obfuscate_client": false,
    "obfuscate_items": false,
    "expires_at": "2026-12-31T23:59:59.000000Z",
    "max_uses": 100,
    "uses_count": 0,
    "value": 97.99,
    "created_at": "2026-05-27T10:00:00.000000Z"
  }
}

Compartilhe o campo url diretamente com seus clientes. Ele já contém o token de segurança necessário para acessar o checkout.

Um link expirado ou que atingiu max_uses retorna erro ao ser acessado no checkout. Crie um novo link ou ajuste as configurações via painel administrativo.

Autenticação

Cobranças

Pedidos

Cartões

Assinaturas

Faturas