> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wyzecash.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/criar-link) · 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](https://docs.wyzecash.com.br/endpoints/clientes.md) 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.

```bash theme={null}
curl -X POST https://api.wyzecash.com.br/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

```json theme={null}
{
  "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`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/listar-links) | `transactions:read` | todos os links, em `items` (sem cursor; até 200) |
| GET | [`/v1/payment-links/{id}`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/consultar-link) | `transactions:read` | um link |
| PATCH | [`/v1/payment-links/{id}`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/editar-link) | `payments:write` | muda qualquer campo (todos opcionais). `active: false` pausa |
| DELETE | [`/v1/payment-links/{id}`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/excluir-link) | `payments:write` | exclui: o link para de funcionar; as cobranças já geradas ficam |
| GET | [`/v1/payment-links/{id}/payments`](https://docs.wyzecash.com.br/referencia/links-de-pagamento/cobrancas-do-link) | `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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.