Criar link

Cria um link (LNK-) com página de pagamento pronta. Cada pagamento vira uma cobrança BKY-.

POST /v1/payment-links

cURL

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"
  }'

200

{
  "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,
  "subaccount": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}

Escopo payments:write; o link que aceita cartão ou cripto (methods) pede também card:write ou crypto:write. Até 200 links por conta e 60 criações ou edições por hora. O endereço público aparece no painel, na forma /pagar/LNK-....

title · string · required

Até 80 caracteres.

description · string | null

Até 280 caracteres.

amount · integer | null

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

suggestedAmounts · integer[] | null

Até 6 valores sugeridos, só no valor livre.

allowCustomAmount · boolean

Aceita outro valor digitado.

minAmount · integer

Mínimo do valor livre.

maxAmount · integer | null

Máximo do valor livre (até 100.000.000).

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

Formas que quem paga pode escolher na página: pix, card, crypto (pelo menos uma; vazio: METHODS_REQUIRED). Sem o campo, só Pix. Uma forma que fique indisponível 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.

displayName · string | null

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

accentColor · string | null

Cor de destaque, #RRGGBB.

pageTheme · string

auto, light ou dark.

buttonLabel · string | null

Pagar com Pix, Comprar, Doar, Contribuir, Assinar, Garantir minha vaga ou 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 cria o link pausado.

subaccountId · string | null

sacc_... ou externalId de uma subconta: cada pagamento pelo link é creditado a ela, como na cobrança com subaccountId. Desativada na criação: 422 SUBACCOUNT_INACTIVE; desativada ou excluída depois, os pagamentos ficam com você.

​

Resposta

id · string

LNK- + 12.

title · string

Título.

description · string | null

Descrição.

amount · integer | null

Valor fixo, ou null no valor livre.

minAmount · integer | null

Mínimo do valor livre.

maxAmount · integer | null

Máximo do valor livre.

suggestedAmounts · integer[]

Valores sugeridos.

allowCustomAmount · boolean

Aceita valor digitado.

methods · string[]

Formas aceitas no link: pix, card, crypto.

collectCustomer · boolean

true se algum dado é pedido.

customerFields · string[]

Dados pedidos.

displayName · string | null

Nome na página.

accentColor · string | null

Cor de destaque.

pageTheme · string

auto, light ou dark.

buttonLabel · string | null

Texto do botão.

thankYouMessage · string | null

Mensagem depois do pagamento.

successUrl · string | null

Destino depois do pagamento.

maxPayments · integer | null

Limite de pagamentos.

expiresAt · string | null

Vencimento.

active · boolean

Ligado ou pausado.

status · string

active, paused, expired ou sold_out.

statusTitle · string

Ativo, Pausado, Vencido ou Esgotado.

payments · integer

Quantidade de cobranças pagas pelo link.

received · integer

Soma recebida pelo link (centavos).

lastPaidAt · string | null

Último pagamento.

subaccount · object | null

A subconta do link: { id, name }. null sem subconta.

createdAt · string

Criação.

cURL

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"
  }'

200

{
  "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,
  "subaccount": null,
  "createdAt": "2026-10-08T15:00:00.000Z"
}