Do primeiro request ao webhook em poucos minutos.
Use uma API Key, crie o pagamento, consulte o estado e receba a confirmação por webhook. O escopo de tenant, merchant e ambiente é definido pela própria chave.
Esta documentação é pública e não exige login. Uma conta autorizada no dashboard da sua plataforma só é necessária para criar API Keys e administrar webhooks.
Crie uma API Key
Abra Desenvolvedores no dashboard e gere uma chave para o ambiente habilitado.
Crie um PIX
Envie POST /v1/payments com uma Idempotency-Key.
Consulte o pagamento
Use o payment_id em GET /v1/payments/{payment_id}.
Confirme por webhook
Valide HMAC e torne o processamento idempotente por event_id.
curl -X POST https://api.nexorapay.me/v1/payments \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Idempotency-Key: pedido_123_pix" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "PIX",
"amount_minor": 15000,
"currency": "BRL",
"payer": {"name": "Cliente Exemplo", "tax_id": "12345678901"},
"client_reference": "pedido_123"
}'Atenção ao ambiente: uma chave LIVE cria cobranças reais. O comando acima é um exemplo de integração, não um simulador. Confira merchant, valor em centavos e Idempotency-Key antes de enviá-lo.
https://api.nexorapay.meAutenticação
API Keys
Bearer
Envie a chave no header Authorization. Não coloque a chave em URL, frontend público ou logs.
Escopo automático
Tenant, merchant, ambiente, estado da chave e permissões são resolvidos no backend.
Authorization: Bearer SUA_API_KEYVerifique sua conexão antes de cobrar
Use esta rota sem movimentação financeira para conferir a API Key e o merchant/ambiente reconhecidos pelo servidor. Não é necessário conceder permissão para criar pagamentos ou saques. Uma chave revogada, expirada ou de outra White Label não passa na autenticação.
/v1/auth/checkValida a credencial e o escopo do merchant sem executar operações financeiras.
Permissão: Somente API Key ativa
curl https://api.nexorapay.me/v1/auth/check \
-H "Authorization: Bearer SUA_API_KEY"{
"data": {
"object": "api_key_connection",
"authenticated": true,
"environment": "LIVE",
"tenant_id": "00000000-0000-4000-8000-000000000001",
"merchant_id": "00000000-0000-4000-8000-000000000002",
"api_version": "v1"
}
}Não envie X-Tenant-Id, X-Merchant-Id ou X-Environment. Esses seletores não fazem parte da API pública.
Ambientes
TEST e LIVE
Cada chave pertence a um único ambiente. Use TEST para integração e homologação e LIVE para operações reais. Trocar o header não troca o ambiente: para mudar de ambiente, use a chave correspondente.
Atualmente, o painel de autoatendimento em produção emite chaves apenas para LIVE. A emissão de chaves TEST ainda não está disponível nessa tela. Não use uma chave LIVE como se fosse sandbox. O backend reconhece escopos TEST separados, mas a homologação completa do fluxo TEST e seus provedores ainda precisa ser comprovada antes da liberação pública.
Integração, QA e homologação. Mantenha credenciais separadas de LIVE.
Operações reais. Só use quando a conta e os métodos estiverem liberados.
Pagamentos
PIX
Crie o pagamento, guarde o payment_id e use os artifacts retornados na consulta para apresentar o PIX copia e cola quando disponível.
/v1/paymentsCria um pagamento PIX no merchant/ambiente da API Key.
Permissão: payments.create
curl -X POST https://api.nexorapay.me/v1/payments \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Idempotency-Key: pedido_123_pix" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "PIX",
"amount_minor": 15000,
"currency": "BRL",
"payer": {"name": "Cliente Exemplo", "tax_id": "12345678901"},
"client_reference": "pedido_123"
}'{
"data": {
"payment_id": "4b4550f0-e42d-4e88-a0d4-c0580f55a121",
"payment_method": "PIX",
"status": "CREATED",
"environment": "TEST",
"card_experience": null
}
}Envie amount_minor como inteiro JSON, em centavos (por exemplo, 15000 para R$ 150,00), nunca como string, decimal ou valor em reais. Em saques, a mesma regra vale para requested_amount_minor. O limite do payload é 32 KiB.
A criação é assíncrona. Consulte o pagamento e use webhook para confirmação definitiva. Estados públicos:
CREATEDPROCESSINGPENDINGOVERDUEAUTHORIZEDPAIDFAILEDCANCELEDEXPIREDOVERDUE é um estado comercial: a cobrança venceu, mas ainda pode ser paga depois. Se houver confirmação tardia do provider, o status passa para PAID.Pagamentos
Boleto
Boleto usa o mesmo endpoint de pagamentos. due_date é obrigatório e card_installments não deve ser enviado.
/v1/paymentsCria um boleto e inicia o processamento no provider configurado.
Permissão: payments.create
curl -X POST https://api.nexorapay.me/v1/payments \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Idempotency-Key: pedido_124_boleto" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "BOLETO",
"amount_minor": 25990,
"currency": "BRL",
"payer": {"name": "Cliente Exemplo", "tax_id": "12345678901"},
"due_date": "2026-12-15",
"client_reference": "pedido_124"
}'Na consulta, os artifacts públicos possíveis incluem BOLETO_BARCODE, BOLETO_DIGITABLE_LINE e BOLETO_URL. Não dependa de identificadores internos do provider.
Pagamentos
Cartão via Hosted Checkout
Nunca envie PAN, CVV ou token legado de cartão para estes endpoints. A API prepara uma experiência hospedada pelo provider e expõe somente o artifact público CARD_CHECKOUT_URL.
/v1/paymentsCria a intenção de pagamento CARD no modo provider-hosted.
Permissão: payments.create
curl -X POST https://api.nexorapay.me/v1/payments \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Idempotency-Key: pedido_125_card" \
-H "Content-Type: application/json" \
-d '{
"payment_method": "CARD",
"amount_minor": 39990,
"currency": "BRL",
"payer": {"name": "Cliente Exemplo", "tax_id": "12345678901"},
"due_date": "2026-12-15",
"card_installments": 3,
"client_reference": "pedido_125"
}'Fluxo do checkout
Crie o pagamento
Envie CARD com due_date e card_installments.
Consulte payment_id
Leia card_experience e artifacts.
Aja pelo campo action
WAIT: aguarde. OPEN_CHECKOUT: abra CARD_CHECKOUT_URL. NONE: nenhuma ação do usuário.
Finalize por estado/webhook
Não trate abertura do checkout como pagamento confirmado.
Ações públicas possíveis:
WAITOPEN_CHECKOUTNONECódigos públicos de experiência do cartão:
PREPARINGPAYMENT_REQUIREDRISK_REVIEWAUTHORIZEDMANUAL_REVIEWSUCCEEDEDCANCELEDEXPIREDRISK_REJECTEDAUTHENTICATION_FAILEDDECLINEDRegra: só abra o checkout quando card_experience.action === "OPEN_CHECKOUT" e existir um artifact CARD_CHECKOUT_URL. Em WAIT, consulte novamente com backoff. Em NONE, não force nova ação do pagador.
Leitura
Consultar pagamentos
/v1/payments/{payment_id}Retorna o pagamento somente se ele pertencer ao escopo da API Key.
Permissão: payments.read
curl https://api.nexorapay.me/v1/payments/{payment_id} \
-H "Authorization: Bearer SUA_API_KEY"{
"data": {
"payment_id": "4b4550f0-e42d-4e88-a0d4-c0580f55a121",
"payment_method": "PIX",
"amount_minor": 15000,
"currency": "BRL",
"status": "PAID",
"succeeded_refund_amount_minor": 0,
"open_refund_amount_minor": 0,
"client_reference": "pedido_123",
"due_date": null,
"card_installments": null,
"created_at": "2026-10-05T18:30:00Z",
"updated_at": "2026-10-05T18:31:04Z",
"paid_at": "2026-10-05T18:31:04Z",
"artifacts": [],
"card_experience": null
}
}PAID significa que o pagamento do pagador foi confirmado. OVERDUE significa que a cobrança venceu, mas não é terminal e ainda pode virar PAID. Nenhum desses estados deve ser usado para inferir saldo sacável; para isso consulte /v1/balances.
Ledger
Saldos
/v1/balancesRetorna saldos autoritativos do ledger para o escopo da chave.
Permissão: balances.read
MERCHANT_AVAILABLE é a referência para disponibilidade de saque. MERCHANT_PENDING representa dinheiro confirmado ainda aguardando settlement.
curl https://api.nexorapay.me/v1/balances \
-H "Authorization: Bearer SUA_API_KEY"Withdrawals
Saques PIX
/v1/withdrawalsCria saque para uma chave PIX. Limites, compliance, risco e saldo continuam sendo autoridade do backend.
Permissão: withdrawals.create
curl -X POST https://api.nexorapay.me/v1/withdrawals \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Idempotency-Key: saque_12345678" \
-H "Content-Type: application/json" \
-d '{
"requested_amount_minor": 10000,
"currency": "BRL",
"destination": {"type":"PIX_KEY","pix_key_type":"EVP","pix_key":"sua-chave-pix"},
"client_reference": "saque_123"
}'A chave PIX não volta em leitura; os endpoints de consulta expõem somente uma dica mascarada do destino.
REQUESTEDREVIEWRESERVEDPROCESSINGSUCCEEDEDFAILEDCANCELED/v1/withdrawals/{withdrawal_id}Consulta um saque no escopo da API Key.
Permissão: withdrawals.read
Consulta
Refunds
/v1/refundsLista reembolsos já existentes no escopo da chave.
Permissão: refunds.read
/v1/refunds/{refund_id}Consulta um reembolso específico.
Permissão: refunds.read
REQUESTEDPROCESSINGPENDINGSUCCEEDEDFAILEDCANCELEDCriação de refund ainda não está aberta na API pública. O executor no provider, reconciliação e financialização no ledger ainda não estão fechados de ponta a ponta. POST /v1/refunds permanece fail-closed.
Proteção financeira
Idempotência
POST /v1/payments e POST /v1/withdrawals exigem Idempotency-Key. Ela representa uma intenção lógica, não uma tentativa HTTP.
Retry correto
Timeout sem resposta conclusiva: repita o mesmo request com a mesma chave.
Nova intenção
Novo pagamento ou novo saque: gere uma nova chave.
Conflito
Mesma chave + payload incompatível retorna idempotency_conflict.
Idempotency-Key: pedido_123_pixGuarde a chave junto ao identificador do pedido no seu sistema. Não gere uma chave nova automaticamente só porque sua conexão caiu. Se um POST retornar 503 ou houver timeout, mantenha o mesmo corpo e a mesma chave para um retry seguro; depois consulte o recurso antes de tentar uma nova intenção.
Listagens
Paginação por cursor
Pagamentos, refunds e saques usam cursor opaco. Não decodifique nem altere o cursor; apenas devolva o valor recebido em next_cursor.
GET https://api.nexorapay.me/v1/payments?limit=50
Resposta:
{"data":{"object":"payment_list","items":[...],"next_cursor":"<cursor_opaco>"}}
GET https://api.nexorapay.me/v1/payments?limit=50&cursor=<cursor_opaco>O limit aceita de 1 a 100. O filtro opcional status deve usar um status documentado para aquela coleção. Um cursor pertence à coleção que o criou.
Confirmação assíncrona
Webhooks
Webhooks são enviados por HTTPS/443. Valide a assinatura antes de processar o JSON e torne seu consumidor idempotente usando X-Arche-Event-Id.
X-Arche-Event-Id: <uuid>
X-Arche-Delivery-Id: <uuid>
X-Arche-Timestamp: <unix_seconds>
X-Arche-Signature: v1=<hex_hmac_sha256>
signing_input = X-Arche-Timestamp + '.' + raw_request_bodyimport {createHmac,timingSafeEqual} from "node:crypto";
function verifyWebhook({secret,timestamp,rawBody,signature}) {
const ts = Number(timestamp);
if (!Number.isSafeInteger(ts) || Math.abs(Date.now()/1000-ts)>300) return false;
if (!/^v1=[0-9a-f]{64}$/.test(signature) || !Buffer.isBuffer(rawBody)) return false;
const expected = createHmac("sha256", secret)
.update(timestamp + ".").update(rawBody).digest();
const received = Buffer.from(signature.slice(3), "hex");
return received.length === expected.length
&& timingSafeEqual(received, expected);
}Use o corpo original como Buffer, sem reconstruir JSON, valide a janela de 5 minutos e use X-Arche-Event-Id como chave única persistida no seu banco. A verificação de assinatura não substitui a idempotência; um mesmo evento pode ser reenviado.
Teste de webhook sem movimentação financeira
No dashboard, abra Desenvolvedores → Webhooks, cadastre um endpoint HTTPS público e clique em Testar webhook. O sistema coloca um evento sintético webhook.test na mesma fila de entregas, com assinatura HMAC. O payload traz data.test=true e data.kind="WEBHOOK_ENDPOINT_TEST": ele não representa cobrança, estorno nem saque.
O resultado inicial QUEUED indica apenas enfileiramento. Consulte a aba Entregas, clique em Atualizar e verifique as tentativas, o código HTTP e o status final. Um teste por endpoint a cada 60 segundos, com limite de 50 por merchant em 24 horas. A requisição exige autorização para gerenciar webhooks e uma sessão com 2FA.
O evento webhook.test é um teste interno, entregue somente quando solicitado no painel. Ele não é um dos 9 eventos financeiros públicos disponíveis para assinatura contínua. O consumidor deve reconhecê-lo como teste e nunca registrar receita ou saldo a partir dele.
Pode haver nova entrega
Falhas de transporte/resposta podem gerar novas tentativas. A política atual permite até 8 tentativas, com backoff que começa em 5s e é limitado a 600s.
Responda rapidamente
Depois de validar e aceitar o evento, responda 200 ou 204. Faça trabalho pesado de forma assíncrona no seu sistema.
Eventos oficiais (9)
payment.createdPagamento criado
payment.paidPagamento pago
payment.failedPagamento falhou
payment.canceledPagamento cancelado
payment.expiredPagamento expirado
withdrawal.createdSaque criado
withdrawal.succeededSaque concluído
withdrawal.failedSaque falhou
withdrawal.canceledSaque cancelado
payment.processing não está no catálogo porque não é um evento oficialmente emitido pelo backend atual.
Diagnóstico
Erros
Todos os erros públicos usam o mesmo envelope. Nunca dependa da mensagem para lógica; use error.code e guarde request_id para rastreamento.
{
"error": {
"code": "permission_denied",
"message": "The API key does not have permission for this operation.",
"request_id": "req_01H..."
}
}| Código | HTTP | Significado | Próxima ação |
|---|---|---|---|
authentication_required | 401 | Envie a API Key em Authorization: Bearer. | Corrija a autenticação. |
invalid_api_key | 401 | A chave é inválida, expirada ou revogada. | Gere/use uma chave válida. |
permission_denied | 403 | A chave não possui a permissão exigida. | Ajuste as permissões da chave. |
not_found | 404 | O recurso não existe dentro do escopo desta chave. | Confirme o ID e o ambiente. |
route_not_found | 404 | A rota pública solicitada não existe. | Corrija a URL/versão. |
method_not_allowed | 405 | O endpoint não aceita esse método HTTP. | Use o método documentado. |
invalid_json | 400 | O body não é um objeto JSON válido. | Corrija o JSON. |
payload_too_large | 413 | O body excede o limite da API. | Reduza o payload. |
validation_error | 422 | Um ou mais campos são inválidos. | Corrija os campos antes de repetir. |
idempotency_conflict | 409 | A mesma Idempotency-Key foi usada para outra intenção. | Não troque o payload da mesma chave. |
method_not_ready | 409 | O método de pagamento não está pronto para a conta. | Revise a configuração do método. |
merchant_not_eligible | 409 | A conta não está elegível para a operação. | Resolva a pendência da conta. |
payment_blocked | 409 | O pagamento não pôde ser preparado. | Não faça retry agressivo. |
operation_not_available | 409 | A operação não está disponível para a conta. | Revise a disponibilidade/configuração. |
operation_blocked | 409 | Controles de conta, limite ou risco bloquearam a operação. | Revise a causa antes de repetir. |
insufficient_balance | 409 | O saldo disponível é insuficiente. | Aguarde/adicione saldo disponível. |
too_many_requests | 429 | O limite temporário foi atingido. | Respeite Retry-After e use backoff. |
temporarily_unavailable | 503 | A API está temporariamente indisponível. | Repita com backoff; em POST financeiro, mantenha a mesma Idempotency-Key. |
internal_error | 500 | A chamada não pôde ser concluída. | Guarde request_id; retry cauteloso com a mesma Idempotency-Key quando aplicável. |
Confiabilidade
Rate limits
Quando a API responder 429 too_many_requests, respeite o header Retry-After e use backoff. Não fixe no cliente um número permanente de requests por minuto: os controles operacionais podem evoluir.
OpenAPI
Referência da API
A lista abaixo é renderizada do OpenAPI versionado. O host resolvido para esta documentação é https://api.nexorapay.me.
GET/v1/healthAPI health
API health
https://api.nexorapay.me/v1/healthRespostas documentadas
200A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/auth/checkValidate API key and resolved merchant scope
Read-only connectivity check. Requires a valid active Bearer API key for the requested White Label API hostname. Does not require a financial permission and does not create payments or withdrawals.
https://api.nexorapay.me/v1/auth/checkRespostas documentadas
200401404429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/balancesList merchant balances
Returns ledger-backed balances for the merchant and environment bound to the API key. Requires balances.read. MERCHANT_PENDING is confirmed money still awaiting settlement; MERCHANT_AVAILABLE is the amount eligible for withdrawals, subject to the normal withdrawal controls.
https://api.nexorapay.me/v1/balancesRespostas documentadas
200401403429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
POST/v1/paymentsCreate a PIX, boleto, or hosted card payment
Creates a payment in the merchant/environment bound to the API key. CARD uses PROVIDER_HOSTED / HOSTED_INVOICE only: no card number, CVV, or card token is accepted by this API. Provider processing is asynchronous.
https://api.nexorapay.me/v1/paymentsRespostas documentadas
202401403409413422429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/paymentsList payments
Cursor-paginated payment list for the merchant/environment bound to the API key. Requires payments.read.
https://api.nexorapay.me/v1/paymentsParâmetros
limitcursorstatusRespostas documentadas
200401403422429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/payments/{payment_id}Get a payment
Returns a payment only from the merchant/environment bound to the API key. Requires payments.read.
https://api.nexorapay.me/v1/payments/{payment_id}Parâmetros
payment_idRespostas documentadas
200401403404429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/refundsList refunds
Read-only refund list for the API-key scope. Requires refunds.read. Refund creation remains intentionally unavailable because provider execution and ledger financialization are not yet implemented end-to-end.
https://api.nexorapay.me/v1/refundsParâmetros
limitcursorstatusRespostas documentadas
200401403422429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/refunds/{refund_id}Get a refund
Get a refund
https://api.nexorapay.me/v1/refunds/{refund_id}Parâmetros
refund_idRespostas documentadas
200401403404429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/withdrawalsList withdrawals
Cursor-paginated withdrawals for the API-key scope. Requires withdrawals.read.
https://api.nexorapay.me/v1/withdrawalsParâmetros
limitcursorstatusRespostas documentadas
200401403422429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
POST/v1/withdrawalsCreate a PIX withdrawal
Creates a withdrawal to a PIX key. The API key scope determines tenant, merchant, and TEST/LIVE. Account limits, compliance, risk controls, available balance, and the merchant withdrawal mode remain authoritative.
https://api.nexorapay.me/v1/withdrawalsRespostas documentadas
202401403409413422429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
GET/v1/withdrawals/{withdrawal_id}Get a withdrawal
Get a withdrawal
https://api.nexorapay.me/v1/withdrawals/{withdrawal_id}Parâmetros
withdrawal_idRespostas documentadas
200401403404429503A especificação OpenAPI JSON contém os schemas completos. Requisições financeiras não são executadas pelo navegador desta documentação.
Versão
Changelog
1.0.0-rc.3candidate v1PIX, boleto, cartão Hosted Checkout, pagamentos paginados, saldos, saques PIX, leitura de refunds, envelope estável de erros, idempotência financeira e 9 eventos oficiais de webhook. RC.3 acrescenta a rota de verificação GET /v1/auth/check sem movimentação financeira e regras mais estritas de validação. RC.2 já havia alinhado o status comercial, incluindo OVERDUE.
Refund creation, browser CORS e um Try it que execute dinheiro real continuam fora deste release candidate.