Links de pagamento

Um endereço que você divulga uma vez (na bio, no WhatsApp, num QR impresso) e que gera uma cobrança nova para cada pagador. Bom para venda recorrente do mesmo produto, doação e valor combinado na hora.

Como funciona

  • Valor fixo (FIXED, você define) ou livre (OPEN, o pagador digita, a partir de 1.00 em BRL).
  • Uma moeda por link: BRL, pago por PIX. MXN (SPEI) e USDT: em breve.
  • O pagador informa o nome e o CPF/CNPJ (e, se quiser, o e-mail) e recebe a própria cobrança, com o PIX dela.
  • Cada cobrança gerada leva o nome do link como descrição, vale 30 minutos e traz paymentLinkId. Os eventos da cobrança são os de sempre (charge.created, charge.paid…); o próprio link avisa payment_link.created e payment_link.updated (nome, limite, validade, pausar, reativar, arquivar).
  • Splits: valem as regras permanentes da empresa. Split só de uma cobrança não existe em link.

Limite de usos, validade e estado

maxUses conta as cobranças pagas. As que estão em andamento reservam um uso: se o limite é 100 e há 98 pagas e 2 aguardando, o próximo pagador só gera cobrança quando uma dessas duas expirar sem pagamento. Ao atingir o limite, o link fica SOLD_OUT; passou do expiresAt, EXPIRED. Esses dois não são guardados: saem dos usos e da data, por isso aparecem em state, não em status.

Ações do link
AçãoRotaEfeito
PausarPOST /v1/payment-links/:id/pausePara de gerar cobranças. As já geradas podem ser pagas até o prazo delas.
ReativarPOST /v1/payment-links/:id/activateVolta a gerar cobranças.
ArquivarPOST /v1/payment-links/:id/archivePara sempre: o endereço passa a mostrar link encerrado e o link não muda mais.
AlterarPATCH /v1/payment-links/:idSó name, maxUses e expiresAt. Valor, moeda e endereço nunca mudam.

Repetir uma ação no estado em que o link já está não muda nada. Link arquivado responde 409 CONFLICT a qualquer alteração.

O pagador vê quando o link está pausado, expirado, esgotado ou encerrado. Quando a empresa não pode receber agora ou a plataforma pausou os links, ele vê só que o link está indisponível, sem o motivo.

O recurso payment_link

  • idtextosempreId do link, plk_…
  • objecttextosempreSempre "payment_link".
  • environmenttextosempre"test" ou "live".
  • statustextosempreA situação guardada: ACTIVE, PAUSED ou ARCHIVED.
  • statetextosempreO que vale agora: além das três, EXPIRED (passou da validade) e SOLD_OUT (atingiu o limite de usos).
  • nametextosempreAparece para o pagador e vira a descrição de cada cobrança.
  • urlURLsempreO endereço para divulgar. Nunca muda.
  • amountMode · amounttextopode ser nullFIXED com o valor, ou OPEN (o pagador digita) com amount null.
  • currency · methodstextosempreA moeda do link e o meio dela, ex.: "BRL" e ["PIX"].
  • maxUses · expiresAtváriospode ser nullLimite de pagamentos e validade; null = sem limite, sem validade.
  • usageobjetosemprepaid: cobranças pagas (contam como uso). open: cobranças em andamento (reservam um uso).
  • amountReceivedtextosempreSoma do que as cobranças pagas do link receberam.
  • archivedAt · createdAt · updatedAtdatapode ser nullDatas do link; archivedAt é null enquanto não arquivado.

Rotas

Rotas de links de pagamento
RotaEscopoO que faz
POST /v1/payment-linkscharges: writeCriar link de pagamento
GET /v1/payment-linkscharges: readLista com cursor, filtro status (ACTIVE, PAUSED, ARCHIVED).
GET /v1/payment-links/:idcharges: readUm link, com usos e recebido de agora.
PATCH /v1/payment-links/:idcharges: writeNome, limite de usos e validade.
POST /v1/payment-links/:id/pause · activate · archivecharges: writeMuda a situação.
GET /v1/charges?paymentLinkId=plk_…charges: readAs cobranças geradas pelo link.