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 avisapayment_link.createdepayment_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ção | Rota | Efeito |
|---|---|---|
| Pausar | POST /v1/payment-links/:id/pause | Para de gerar cobranças. As já geradas podem ser pagas até o prazo delas. |
| Reativar | POST /v1/payment-links/:id/activate | Volta a gerar cobranças. |
| Arquivar | POST /v1/payment-links/:id/archive | Para sempre: o endereço passa a mostrar link encerrado e o link não muda mais. |
| Alterar | PATCH /v1/payment-links/:id | Só 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
| Rota | Escopo | O que faz |
|---|---|---|
POST /v1/payment-links | charges: write | Criar link de pagamento |
GET /v1/payment-links | charges: read | Lista com cursor, filtro status (ACTIVE, PAUSED, ARCHIVED). |
GET /v1/payment-links/:id | charges: read | Um link, com usos e recebido de agora. |
PATCH /v1/payment-links/:id | charges: write | Nome, limite de usos e validade. |
POST /v1/payment-links/:id/pause · activate · archive | charges: write | Muda a situação. |
GET /v1/charges?paymentLinkId=plk_… | charges: read | As cobranças geradas pelo link. |