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

> ## Agent Instructions
> Consulte o contrato Bunni antes de sugerir chamadas. Valores monetários são inteiros em centavos. Não invente endpoints ou respostas de sucesso para recursos ainda indisponíveis. Nunca solicite chaves reais no chat nem exponha credenciais no cliente.

# Links e checkout

> Crie rascunhos de links de pagamento, publique, desative e processe checkout publico com controle de versao e token secreto.

Links de pagamento permitem criar URLs publicas para receber Pix sem precisar chamar a API de cobrancas diretamente. O fluxo envolve criar um rascunho, publica-lo e, em seguida, permitir que o pagador finalize o checkout.

> [!NOTE]
>
> Requer escopo `links:write` para criar/editar e `links:read` para consultar.

## Criar rascunho

Envie `POST /v1/payment-links` com `Idempotency-Key` obrigatorio. A criacao gera um rascunho (`draft`); nao publica uma URL de pagamento nem emite uma cobranca.

**name** `string` *required*

Nome do link (1 a 80 caracteres).

**walletId** `string` *required*

UUID da carteira da conta.

**amountCents** `integer` *required*

Valor em centavos de BRL (minimo 1).

**description** `string`

Descricao do link (ate 300 caracteres).

```bash curl theme={"theme":"github-dark-default"}
curl -X POST https://api.bunnipay.com.br/v1/payment-links \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE" \
  -H "Idempotency-Key: link-789-unico" \
  -d '{
    "name": "Assinatura Mensal",
    "walletId": "550e8400-e29b-41d4-a716-446655440000",
    "amountCents": 2990,
    "description": "Plano mensal de assinatura"
  }'
```

## Publicar ou desativar um link

Use `PATCH /v1/payment-links/{id}` para alterar o status ou editar dados.

**status** `string`

`active` para publicar; `disabled` para impedir novas intencoes.

**name** `string`

Novo nome (1 a 80 caracteres).

**description** `string`

Nova descricao (ate 300 caracteres).

**amountCents** `integer`

Novo valor em centavos.

```bash curl theme={"theme":"github-dark-default"}
curl -X PATCH https://api.bunnipay.com.br/v1/payment-links/550e8400-e29b-41d4-a716-446655440003 \
  -H "Content-Type: application/json" \
  -H "X-API-Key: SUA_CHAVE" \
  -d '{
    "status": "active"
  }'
```

> [!WARNING]
>
> Publicar (`status=active`) exige conta ativa e habilitada, valor dentro do limite e acima da tarifa. `disabled` impede novas intencoes, mas nao cancela pagamentos em andamento. Alteracoes sao auditadas.

## URL publica

Apos publicar, o link fica disponivel em:

```
https://api.bunnipay.com.br/pay/{slug}
```

O `slug` e retornado nos dados do link e segue o padrao `^[a-f0-9]{32}$`.

## Fluxo de checkout publico

O checkout publico e feito sem chave de API. O pagador acessa o link, o frontend consulta os dados publicos e cria a intencao de pagamento.

**1. Consultar dados publicos do link**

O frontend chama `GET /public/payment-links/{slug}` para obter titulo, descricao, valor e `version`.

```bash curl theme={"theme":"github-dark-default"}
curl https://api.bunnipay.com.br/public/payment-links/abc123...def
```

A resposta inclui `version` (hash de 64 caracteres hex), necessario no proximo passo.

**2. Criar ou recuperar Pix do checkout**

Envie `POST /public/payment-links/{slug}/checkout` com:

* Header `If-Match` contendo a `version` consultada.
* Header `Idempotency-Key` para identificar a compra.
* Corpo vazio `{}`.

```bash curl theme={"theme":"github-dark-default"}
curl -X POST https://api.bunnipay.com.br/public/payment-links/abc123...def/checkout \
  -H "Content-Type: application/json" \
  -H "If-Match: a1b2c3...f0" \
  -H "Idempotency-Key: compra-001-unica" \
  -d '{}'
```

Se o link foi alterado desde a consulta, a API retorna erro `LINK_CHANGED` (HTTP 428). Atualize os dados e repita.

**3. Guardar checkoutToken**

A resposta do checkout devolve `checkoutToken` (43 caracteres). Guarde-o de forma segura e **nao o inclua na URL**.

```json theme={"theme":"github-dark-default"}
{
  "data": {
    "id": "...",
    "checkoutToken": "tok_...",
    "copyPaste": "...",
    "qrSvg": "...",
    "expiresAt": "..."
  }
}
```

**4. Acompanhar situacao da compra**

Use `GET /public/payment-links/{slug}/checkouts/{id}` com header `X-Checkout-Token` para consultar o status do Pix.

```bash curl theme={"theme":"github-dark-default"}
curl https://api.bunnipay.com.br/public/payment-links/abc123...def/checkouts/550e8400-e29b-41d4-a716-446655440004 \
  -H "X-Checkout-Token: tok_..."
```

A consulta funciona mesmo se o link for desativado posteriormente.

> [!NOTE]
>
> A repeticao idempotente pode recuperar a intencao original apos edicao ou desativacao do link.

## Erros comuns

| HTTP | Causa | Acao recomendada |
| - | - | - |
| 400 | Campos, parametros ou headers invalidos | Revise o corpo e os headers. |
| 401 | Token de checkout ausente ou invalido | Verifique `X-Checkout-Token`. |
| 403 | Conta sem habilitacao financeira | Complete a habilitacao. |
| 404 | Link ou pagamento nao encontrado | Confira o `slug` ou o ID da compra. |
| 409 | Link alterado/desativado ou intencao em processamento | Aguarde e repita com dados atualizados. |
| 428 | `If-Match` desatualizado | Reconsulte o link e atualize `If-Match`. |
| 429 | Limite de requisicoes excedido | Aguarde o intervalo de `Retry-After`. |
| 502 | Provedora indisponivel | Preserve a chave da compra e tente novamente. |
| 503 | Checkout ou infraestrutura indisponivel | Entre em contato com o suporte. |


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