Links de pagamento

Páginas de pagamento reutilizáveis (ex.: um produto, uma doação) para divulgar por WhatsApp, redes sociais ou e-mail. Cada pagamento pelo link gera uma cobrança nova (com payment_link_id) e os eventos de sempre.

Criar link de pagamento

POST /v1/payment_links

Valor fixo (amount) ou escolhido pelo pagador entre min_amount e max_amount. Cada clique em "Pagar com Pix" cria uma cobrança imediata válida por charge_expires_in segundos. Requer o escopo charges:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Corpo da requisição

Campo	Tipo	Descrição
`title` obrigatório	string	Nome do produto ou do motivo do pagamento.
`description`	string
`amount`	string (valor)	Valor em reais, duas casas decimais, separador ponto.
`min_amount`	string (valor)	Valor em reais, duas casas decimais, separador ponto.
`max_amount`	string (valor)	Valor em reais, duas casas decimais, separador ponto.
`charge_expires_in`	integer	Validade (s) da cobrança gerada a cada pagamento.
`max_payments`	integer	Depois de N pagamentos o link deixa de aceitar novos.
`expires_at`	string (date-time)
`return_url`	string (uri)
`metadata`	Metadata	Até 20 pares chave/valor livres do integrador (chave ≤ 40, valor ≤ 500 caracteres). Não use para dados pessoais.

Respostas

201 Link criado.
400 Requisição inválida (formato ou campos).
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/payment_links" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "title": "Camiseta Aurora — M",
  "amount": "59.90",
  "max_payments": 100,
  "return_url": "https://loja.exemplo.com.br/obrigado"
}'

Identificador nos logs: api.payment_links.create

Listar links de pagamento

GET /v1/payment_links

Requer o escopo charges:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`limit`	consulta	integer
`starting_after`	consulta	string	Cursor — ID do último objeto da página anterior.
`ending_before`	consulta	string	Cursor — ID do primeiro objeto da página seguinte.

Respostas

200 Lista paginada de links.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/payment_links?limit=20" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.payment_links.list

Consultar link de pagamento

GET /v1/payment_links/{payment_link_id}

Inclui quantas cobranças o link gerou, quantas foram pagas e o total recebido. Requer charges:read.

Parâmetros

Nome	Onde	Tipo	Descrição
`payment_link_id` obrigatório	caminho	string

Respostas

200 Link.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X GET "https://api.exemplo.com.br/v1/payment_links/pl_01J9Z3F0A1B2C3D4E5F6G7H8J9" \
  -H "Authorization: Bearer $PIX_API_KEY"

Identificador nos logs: api.payment_links.retrieve

Desativar link de pagamento

POST /v1/payment_links/{payment_link_id}/deactivate

A página passa a informar que o link foi desativado; cobranças já geradas continuam válidas. Requer charges:write.

Exige o cabeçalho Idempotency-Key (os SDKs enviam automaticamente).

Parâmetros

Nome	Onde	Tipo	Descrição
`payment_link_id` obrigatório	caminho	string

Respostas

200 Link desativado.
401 Chave ausente, inválida, expirada ou revogada.
403 Operação não permitida: escopo insuficiente (`insufficient-scope`), IP fora da lista permitida
404 Recurso não encontrado (ou pertencente a outra unidade).
429 Limite de requisições (`rate-limited`) ou cota diária de cobranças (`quota-exceeded`) excedidos.

Exemplo

curl -X POST "https://api.exemplo.com.br/v1/payment_links/pl_01J9Z3F0A1B2C3D4E5F6G7H8J9/deactivate" \
  -H "Authorization: Bearer $PIX_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

Identificador nos logs: api.payment_links.deactivate