Criar link de pagamento

POST/v1/payment-links

Cria o link e devolve o endereço para divulgar em url. O link nasce ativo; cada pagador que abre ganha a própria cobrança. Escopo da chave: charges em write.

Cabeçalhos

  • AuthorizationtextoobrigatórioBearer com a sua chave: sk_test_… no teste, sk_live_… em produção.
  • Idempotency-KeytextoobrigatórioUm valor único por pedido (ex.: o número do pedido), até 255 caracteres visíveis, sem espaços. Mesmo corpo de novo: a resposta guardada, com Idempotent-Replayed: true. Outro corpo: 409. Vale por 7 dias.
  • Content-Typetextoobrigatórioapplication/json

Corpo

  • nametextoobrigatórioAté 120 caracteres, sem quebra de linha. Aparece para o pagador, forma o começo do endereço e vira a descrição de cada cobrança.
  • amountModetextoobrigatório"FIXED" (valor definido aqui) ou "OPEN" (o pagador digita o valor).
  • amounttextoopcionalSó no FIXED, e obrigatório nele: texto decimal com ponto, ex.: "150.00", maior que zero e que cubra a tarifa. No OPEN não mande: o pagador digita a partir de 1.00.
  • currencytextoobrigatório"BRL" (PIX). MXN (SPEI), COP (Colômbia, em pesos inteiros) e USDT: em breve. Só moedas habilitadas para a sua empresa.
  • methodslistaopcionalSó em COP (em breve): quais métodos o link aceita, entre "PSE", "NEQUI" e "BREB"; o pagador escolhe um no checkout e informa nome, documento, e-mail e celular (e o banco no PSE). Ausente = os três. Nas outras moedas o método é o da moeda.
  • maxUsesnúmeroopcionalQuantos pagamentos encerram o link (esgotado), de 1 a 1.000.000. null ou ausente = sem limite.
  • expiresAtdataopcionalValidade em ISO 8601 com fuso, ex.: "2026-12-31T23:59:59-03:00": no futuro e até dois anos à frente. null ou ausente = sem validade.

Campos desconhecidos são recusados. O método vem da moeda: BRL cria um link de PIX.

O endereço é o começo do nome em letras simples mais um código aleatório (ex.: plano-pro-mensal-k7m2qx) e nunca muda, nem quando o nome muda.

Respostas

  • 201CreatedO link foi criado, com status e state "ACTIVE" e usage zerado. Numa repetição com o mesmo corpo, vem com Idempotent-Replayed: true.
  • 409ConflictIDEMPOTENCY_KEY_REUSED: a mesma chave já foi usada com outro corpo.
  • 422Unprocessable EntityVALIDATION_ERROR, AMOUNT_TOO_LOW, PAYMENT_METHOD_UNAVAILABLE ou CURRENCY_NOT_ENABLED; veja abaixo.

O recurso campo a campo está em Links de pagamento.

Erros

Códigos de erro
CódigoHTTPQuando acontece
VALIDATION_ERROR422Nome vazio ou com quebra de linha, amount no OPEN ou faltando no FIXED, casas decimais demais, moeda não aceita, validade no passado ou a mais de dois anos.
AMOUNT_TOO_LOW422O valor fixo não cobre a tarifa da cobrança.
PAYMENT_METHOD_UNAVAILABLE422A moeda não está disponível neste ambiente.
CURRENCY_NOT_ENABLED422A moeda não está habilitada para a sua empresa.
IDEMPOTENCY_KEY_REQUIRED400Faltou o cabeçalho Idempotency-Key.
IDEMPOTENCY_KEY_REUSED409A Idempotency-Key já foi usada com outro corpo.
API_KEY_SCOPE403A chave não tem write em charges.