Skip to main content
Links de pagamento permitem criar URLs publicas para receber Pix sem precisar chamar a API de cobrancas diretamente. O fluxo envolve criar um rascunho, publica-lo e, em seguida, permitir que o pagador finalize o checkout.
Requer escopo links:write para criar/editar e links:read para consultar.

Criar rascunho

Envie POST /v1/payment-links com Idempotency-Key obrigatorio. A criacao gera um rascunho (draft); nao publica uma URL de pagamento nem emite uma cobranca.
string
required
Nome do link (1 a 80 caracteres).
string
required
UUID da carteira da conta.
integer
required
Valor em centavos de BRL (minimo 1).
string
Descricao do link (ate 300 caracteres).
curl
Use PATCH /v1/payment-links/{id} para alterar o status ou editar dados.
string
active para publicar; disabled para impedir novas intencoes.
string
Novo nome (1 a 80 caracteres).
string
Nova descricao (ate 300 caracteres).
integer
Novo valor em centavos.
curl
Publicar (status=active) exige conta ativa e habilitada, valor dentro do limite e acima da tarifa. disabled impede novas intencoes, mas nao cancela pagamentos em andamento. Alteracoes sao auditadas.

URL publica

Apos publicar, o link fica disponivel em:
O slug e retornado nos dados do link e segue o padrao ^[a-f0-9]{32}$.

Fluxo de checkout publico

O checkout publico e feito sem chave de API. O pagador acessa o link, o frontend consulta os dados publicos e cria a intencao de pagamento.
1

Consultar dados publicos do link

O frontend chama GET /public/payment-links/{slug} para obter titulo, descricao, valor e version.
curl
A resposta inclui version (hash de 64 caracteres hex), necessario no proximo passo.
2

Criar ou recuperar Pix do checkout

Envie POST /public/payment-links/{slug}/checkout com:
  • Header If-Match contendo a version consultada.
  • Header Idempotency-Key para identificar a compra.
  • Corpo vazio {}.
curl
Se o link foi alterado desde a consulta, a API retorna erro LINK_CHANGED (HTTP 428). Atualize os dados e repita.
3

Guardar checkoutToken

A resposta do checkout devolve checkoutToken (43 caracteres). Guarde-o de forma segura e nao o inclua na URL.
4

Acompanhar situacao da compra

Use GET /public/payment-links/{slug}/checkouts/{id} com header X-Checkout-Token para consultar o status do Pix.
curl
A consulta funciona mesmo se o link for desativado posteriormente.
A repeticao idempotente pode recuperar a intencao original apos edicao ou desativacao do link.

Erros comuns