# Links de pagamento

Um link de pagamento é uma URL reutilizável. Quem tiver o link pode pagar o valor que você definiu. Crie, liste, consulte e exclua links com a sua chave de API.

## Endpoints

Todas as rotas usam a mesma autenticação do restante de `/v1`: um token Bearer de `POST /v1/auth/token` e o header `x-fluxis-api-key`. Veja [Credenciais de API](/pt/docs/developers/api-credentials).

| Método | Rota | Papel |
| ------ | ---- | ----- |
| `POST` | `/v1/payment-links` | `write` |
| `GET` | `/v1/payment-links` | `read` |
| `GET` | `/v1/payment-links/:id` | `read` |
| `DELETE` | `/v1/payment-links/:id` | `write` |

O ponto de venda precisa pertencer à credencial e ser um ponto de venda online de valor fixo. Um ponto de venda de outra conta responde 403.

## Criar

`POST /v1/payment-links` responde `201`.

| Campo | Obrigatório | Notas |
| ----- | ----------- | ----- |
| `point_of_sale_id` | sim | UUID de um ponto de venda online que a chave pode usar |
| `name` | sim | Nome que o comprador vê |
| `amount` | sim | Decimal positivo em texto, com até 2 casas, por exemplo `"25.00"` |
| `currency` | sim | `USD` ou `ARS` |
| `external_id` | não | Sua referência interna de pedido ou fatura. O comprador não a vê como título do produto |
| `expiration` | não | Tempo unix em segundos, UTC. Se você omitir, o link não vence |
| `payment_options` | não | Subconjunto das opções do ponto de venda. Vazio usa as do ponto de venda |
| `image` | não | URL `http` ou `https`, com até 255 caracteres |

Header opcional `Idempotency-Key`: 8 a 64 letras, dígitos, `_` ou `-`. A mesma chave e o mesmo body repetem o `201` original por 24 horas. A mesma chave com outro body responde `409`.

O status é `deleted`, depois `disabled`, depois `expired` e, se não, `active`. `never_expires` é `true` quando `expiration` foi omitido.

## Listar e consultar

`GET /v1/payment-links` aceita `page` (padrão 1), `page_size` (padrão 20, máximo 100), `point_of_sale_id` e `status` (`active`, `expired`, `disabled`, `deleted` ou `all`). O status padrão é `active`.

`GET /v1/payment-links/:id` devolve o link, as estatísticas de pagamento e os cinco pagamentos mais recentes. Um link excluído ainda pode ser lido.

## Excluir

`DELETE /v1/payment-links/:id` faz uma exclusão lógica e responde `200`. Excluir um link que já está excluído responde sucesso e deixa `already_deleted` em `true`. Os pagamentos existentes são mantidos.

O [MCP para comerciantes](/pt/docs/developers/mcp) exclui em dois passos. Este endpoint REST exclui em um único request.