# OriPay API

> API PIX servidor a servidor da OriPay: cobranças por QR dinâmico (cash-in), transferências para chave PIX (cash-out), devoluções, saldo, extrato e webhooks assinados. Valores sempre em centavos (inteiro). URL base: https://api.oripaysolutions.com.br/v1

Regras que um agente deve seguir ao gerar código para esta API:

- Autenticação: `Authorization: Bearer oripay_live_...`. Só existe produção; sandbox e chaves de teste ainda não existem (em breve). A chave só funciona de IPs cadastrados no OriPay Web. Nunca coloque a chave em front-end, app mobile, log ou repositório.
- Todo `POST` que cria recurso (`/pix/charges`, `/pix/transfers`, `/pix/received/{id}/refunds`) exige `Idempotency-Key` (8 a 128 caracteres ASCII visíveis). Em timeout, erro de rede ou 5xx, repita com a MESMA chave. Nunca gere uma chave nova para "tentar de novo": isso pode pagar duas vezes.
- Todo recurso tem `external_id` (ID do sistema do cliente, único por conta e tipo) e cobranças e transferências aceitam `metadata` (até 20 chaves texto, sem dados pessoais). Use-os para ligar cada PIX ao cliente final.
- Os corpos são estritos: campo desconhecido devolve `400 validation_error`. Valores de 1 a 100000000 centavos.
- Transferências e PIX recebidos não têm campo de tarifa; tarifas são linhas `pix_fee`/`monthly_fee` no extrato. A chave de destino volta só como `pix_key_masked`.
- Transferência `pending` não é falha. Espere o webhook `transfer.completed` ou `transfer.failed`; não reenvie.
- Webhooks: valide o header `oripay-signature` (`t=<unix>,v1=<hex>`, HMAC-SHA256 de `"<t>.<corpo bruto>"`, tolerância de 300 s, aceite se qualquer `v1` bater), deduplique por `oripay-event-id`, responda 2xx em até 10 s e não dependa da ordem dos eventos.
- Chaves, IPs, URL e secret do webhook não são alteráveis pela API; só no OriPay Web (Conta → API), com PIN.
- Decida erros pelo campo `error.code`, nunca pelo texto. Exceção: o antifraude responde `403 { "error": "risk_score_exceeded" }` em transferências e devoluções.

## Começando

- [Introdução](https://docs.oripaysolutions.com.br/index.md): o que a API faz e convenções (centavos, UTC, snake_case)
- [Quickstart](https://docs.oripaysolutions.com.br/quickstart.md): da chave ao primeiro PIX recebido
- [Ambientes](https://docs.oripaysolutions.com.br/guias/ambientes.md): produção; sandbox em breve

## Fundamentos

- [Autenticação](https://docs.oripaysolutions.com.br/guias/autenticacao.md): chave de API, scopes, IPs liberados, rotação
- [Segurança e headers](https://docs.oripaysolutions.com.br/guias/seguranca.md): headers de request e resposta, checklist
- [Idempotência](https://docs.oripaysolutions.com.br/guias/idempotencia.md): `Idempotency-Key` e retries seguros
- [Mapeamento de clientes](https://docs.oripaysolutions.com.br/guias/mapeamento-de-clientes.md): `external_id`, `metadata` e `payer`
- [Status](https://docs.oripaysolutions.com.br/guias/status.md): ciclo de vida de cobranças, transferências e devoluções
- [Erros](https://docs.oripaysolutions.com.br/guias/erros.md): formato, códigos e quando repetir
- [Limites](https://docs.oripaysolutions.com.br/guias/limites.md): limites PIX por janela e rate limit

## Fluxos PIX

- [Cobranças](https://docs.oripaysolutions.com.br/guias/cobrancas.md): criar QR dinâmico, quem pagou, ligação pelo txid
- [PIX recebidos](https://docs.oripaysolutions.com.br/guias/recebimentos.md): todo crédito, com ou sem cobrança
- [Transferências](https://docs.oripaysolutions.com.br/guias/transferencias.md): enviar PIX para chave
- [Devoluções](https://docs.oripaysolutions.com.br/guias/devolucoes.md): devolver PIX recebido, total ou parcial
- [Saldo e extrato](https://docs.oripaysolutions.com.br/guias/conciliacao.md): conciliação diária

## Webhooks

- [Webhooks](https://docs.oripaysolutions.com.br/guias/webhooks.md): eventos, formato, headers e retentativas
- [Assinatura](https://docs.oripaysolutions.com.br/guias/webhooks-assinatura.md): validação em Node.js, Python e PHP
- [Testar, listar e reenviar](https://docs.oripaysolutions.com.br/guias/webhooks-testes.md): evento de teste, entregas e reenvio

## Referência

- [OpenAPI 3.1](https://docs.oripaysolutions.com.br/api-reference/openapi.yaml): todos os endpoints e schemas
- [Integrando com IA](https://docs.oripaysolutions.com.br/guias/integrando-com-ia.md): MCP de busca na documentação

## Optional

- [Documentação completa em um arquivo](https://docs.oripaysolutions.com.br/llms-full.txt)