Links de pagamento

Uma página de pagamento pronta: crie o link, mande para o cliente e cada pagamento (Pix, cartão ou cripto) vira uma cobrança.

Um link (LNK-) abre uma página pública onde cada pagador escolhe a forma (Pix, cartão de crédito ou cripto, as que o link aceita) e gera a própria cobrança BKY-: no Pix, QR Code e Copia e Cola, válidos por 30 minutos; no cartão, a página segura de pagamento; na cripto, o valor na moeda e o endereço. Serve para vender sem programar uma tela: valor fixo ou livre, formas de pagamento, nome e cor da página, dados que você quer pedir e limite de pagamentos. Até 200 links por conta. O endereço público aparece no painel e tem a forma /pagar/LNK-....

​

Criar um link

POST /v1/payment-links · escopo payments:write (com cartão ou cripto em methods, também card:write ou crypto:write)

title · string · required

Até 80 caracteres. Título da página.

description · string | null

Até 280 caracteres.

amount · integer | null

Valor fixo em centavos. null = valor livre: o pagador escolhe entre suggestedAmounts e, se allowCustomAmount for true, digita outro entre minAmount e maxAmount.

suggestedAmounts · integer[] | null

Até 6 valores sugeridos (botões), só no valor livre.

allowCustomAmount · boolean

Aceita outro valor digitado (entre minAmount e maxAmount). Desligado, só os sugeridos.

minAmount · integer

Mínimo do valor livre (centavos).

maxAmount · integer | null

Máximo do valor livre (centavos).

methods · string[] · default: "[\"pix\"]"

Formas que quem paga pode escolher: pix, card, crypto (pelo menos uma; vazio: METHODS_REQUIRED). Sem o campo, só Pix. Uma forma indisponível no momento some da página até voltar.

customerFields · string[]

Dados a pedir antes de pagar: name, email, phone, document. Cada um escolhido é obrigatório e quem paga vira cliente seu. Vazio = não pede nada.

displayName · string | null

Nome mostrado na página (até 60). O nome da sua conta continua aparecendo como recebedor.

accentColor · string | null

Cor de destaque, #RRGGBB.

pageTheme · string

auto, light ou dark.

buttonLabel · string | null

Texto do botão, de uma lista fechada: Pagar com Pix, Comprar, Doar, Contribuir, Assinar, Garantir minha vaga, Apoiar.

thankYouMessage · string | null

Mensagem depois do pagamento (até 280).

successUrl · string | null

Para onde levar depois de pagar. Só https://.

maxPayments · integer | null

Depois dessa quantidade de pagamentos, o link fica sold_out.

expiresAt · string | null

Data e hora (ISO 8601) em que o link vence.

active · boolean

false pausa o link.

curl -X POST https://bukio-backend-production.up.railway.app/v1/payment-links \
  -H "Authorization: Bearer bk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Ingresso Workshop",
    "amount": 9900,
    "methods": ["pix", "card", "crypto"],
    "customerFields": ["name", "email"],
    "buttonLabel": "Garantir minha vaga",
    "maxPayments": 50,
    "expiresAt": "2026-11-30T23:59:59.000Z"
  }'

​

Resposta

{
  "id": "LNK-4H8W2PQ7ZM3K",
  "title": "Ingresso Workshop",
  "description": null,
  "amount": 9900,
  "minAmount": null,
  "maxAmount": null,
  "suggestedAmounts": [],
  "allowCustomAmount": false,
  "methods": ["pix", "card", "crypto"],
  "collectCustomer": true,
  "customerFields": ["name", "email"],
  "displayName": null,
  "accentColor": null,
  "pageTheme": "auto",
  "buttonLabel": "Garantir minha vaga",
  "thankYouMessage": null,
  "successUrl": null,
  "maxPayments": 50,
  "expiresAt": "2026-11-30T23:59:59.000Z",
  "active": true,
  "status": "active",
  "statusTitle": "Ativo",
  "payments": 0,
  "received": 0,
  "lastPaidAt": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}

payments e received contam as cobranças pagas pelo link (quantidade e soma em centavos). status: active, paused (active: false), expired ou sold_out.

​

Listar, ver, editar e excluir

Método	Rota	Escopo	O que faz
GET	/v1/payment-links	transactions:read	todos os links, em items (sem cursor; até 200)
GET	/v1/payment-links/{id}	transactions:read	um link
PATCH	/v1/payment-links/{id}	payments:write	muda qualquer campo (todos opcionais). active: false pausa
DELETE	/v1/payment-links/{id}	payments:write	exclui: o link para de funcionar; as cobranças já geradas ficam
GET	/v1/payment-links/{id}/payments	transactions:read	as cobranças BKY- geradas pelo link

​

Como saber quem pagou

Cada pagamento pelo link é uma cobrança BKY- normal: os webhooks payment.created, payment.paid e payment.expired chegam com data.paymentLinkId igual ao LNK- do link. Se o link pede dados, a cobrança vem com customer preenchido.