ARCHE Developer Docs

API pública

Public API v1 · 1.0.0-rc.3

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.

1

Crie uma API Key

Abra Desenvolvedores no dashboard e gere uma chave para o ambiente habilitado.

2

Crie um PIX

Envie POST /v1/payments com uma Idempotency-Key.

3

Consulte o pagamento

Use o payment_id em GET /v1/payments/{payment_id}.

4

Confirme por webhook

Valide HMAC e torne o processamento idempotente por event_id.

Quick start · criar PIX
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.

Base URL desta documentação: https://api.nexorapay.me

Autenticaçã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.

Header
Authorization: Bearer SUA_API_KEY

Verifique 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.

GET/v1/auth/check

Valida a credencial e o escopo do merchant sem executar operações financeiras.

Permissão: Somente API Key ativa

cURL · verificar API Key
curl https://api.nexorapay.me/v1/auth/check \
  -H "Authorization: Bearer SUA_API_KEY"
200 · exemplo de resposta (IDs ilustrativos)
{
  "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.

TEST

Integração, QA e homologação. Mantenha credenciais separadas de LIVE.

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.

POST/v1/payments

Cria um pagamento PIX no merchant/ambiente da API Key.

Permissão: payments.create

cURL · PIX
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"
  }'
202 · exemplo de resposta
{
  "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:

CREATEDPROCESSINGPENDINGOVERDUEAUTHORIZEDPAIDFAILEDCANCELEDEXPIRED
OVERDUE é 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.

POST/v1/payments

Cria um boleto e inicia o processamento no provider configurado.

Permissão: payments.create

cURL · boleto
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

O cartão não passa pela API pública

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.

POST/v1/payments

Cria a intenção de pagamento CARD no modo provider-hosted.

Permissão: payments.create

cURL · cartão Hosted Checkout
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

1

Crie o pagamento

Envie CARD com due_date e card_installments.

2

Consulte payment_id

Leia card_experience e artifacts.

3

Aja pelo campo action

WAIT: aguarde. OPEN_CHECKOUT: abra CARD_CHECKOUT_URL. NONE: nenhuma ação do usuário.

4

Finalize por estado/webhook

Não trate abertura do checkout como pagamento confirmado.

Ações públicas possíveis:

WAITOPEN_CHECKOUTNONE

Códigos públicos de experiência do cartão:

PREPARINGPAYMENT_REQUIREDRISK_REVIEWAUTHORIZEDMANUAL_REVIEWSUCCEEDEDCANCELEDEXPIREDRISK_REJECTEDAUTHENTICATION_FAILEDDECLINED

Regra: 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

GET/v1/payments/{payment_id}

Retorna o pagamento somente se ele pertencer ao escopo da API Key.

Permissão: payments.read

cURL · consultar pagamento
curl https://api.nexorapay.me/v1/payments/{payment_id} \
  -H "Authorization: Bearer SUA_API_KEY"
200 · exemplo
{
  "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

GET/v1/balances

Retorna 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 · saldos
curl https://api.nexorapay.me/v1/balances \
  -H "Authorization: Bearer SUA_API_KEY"

Withdrawals

Saques PIX

POST/v1/withdrawals

Cria saque para uma chave PIX. Limites, compliance, risco e saldo continuam sendo autoridade do backend.

Permissão: withdrawals.create

cURL · criar saque
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
GET/v1/withdrawals/{withdrawal_id}

Consulta um saque no escopo da API Key.

Permissão: withdrawals.read

Consulta

Refunds

GET/v1/refunds

Lista reembolsos já existentes no escopo da chave.

Permissão: refunds.read

GET/v1/refunds/{refund_id}

Consulta um reembolso específico.

Permissão: refunds.read

REQUESTEDPROCESSINGPENDINGSUCCEEDEDFAILEDCANCELED

Criaçã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.

Header obrigatório
Idempotency-Key: pedido_123_pix

Guarde 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.

Primeira página → próxima página
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.

Headers e assinatura
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_body
Node.js · validar assinatura
import {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.created

Pagamento criado

payment.paid

Pagamento pago

payment.failed

Pagamento falhou

payment.canceled

Pagamento cancelado

payment.expired

Pagamento expirado

withdrawal.created

Saque criado

withdrawal.succeeded

Saque concluído

withdrawal.failed

Saque falhou

withdrawal.canceled

Saque 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.

Envelope de erro
{
  "error": {
    "code": "permission_denied",
    "message": "The API key does not have permission for this operation.",
    "request_id": "req_01H..."
  }
}
CódigoHTTPSignificadoPróxima ação
authentication_required401Envie a API Key em Authorization: Bearer.Corrija a autenticação.
invalid_api_key401A chave é inválida, expirada ou revogada.Gere/use uma chave válida.
permission_denied403A chave não possui a permissão exigida.Ajuste as permissões da chave.
not_found404O recurso não existe dentro do escopo desta chave.Confirme o ID e o ambiente.
route_not_found404A rota pública solicitada não existe.Corrija a URL/versão.
method_not_allowed405O endpoint não aceita esse método HTTP.Use o método documentado.
invalid_json400O body não é um objeto JSON válido.Corrija o JSON.
payload_too_large413O body excede o limite da API.Reduza o payload.
validation_error422Um ou mais campos são inválidos.Corrija os campos antes de repetir.
idempotency_conflict409A mesma Idempotency-Key foi usada para outra intenção.Não troque o payload da mesma chave.
method_not_ready409O método de pagamento não está pronto para a conta.Revise a configuração do método.
merchant_not_eligible409A conta não está elegível para a operação.Resolva a pendência da conta.
payment_blocked409O pagamento não pôde ser preparado.Não faça retry agressivo.
operation_not_available409A operação não está disponível para a conta.Revise a disponibilidade/configuração.
operation_blocked409Controles de conta, limite ou risco bloquearam a operação.Revise a causa antes de repetir.
insufficient_balance409O saldo disponível é insuficiente.Aguarde/adicione saldo disponível.
too_many_requests429O limite temporário foi atingido.Respeite Retry-After e use backoff.
temporarily_unavailable503A API está temporariamente indisponível.Repita com backoff; em POST financeiro, mantenha a mesma Idempotency-Key.
internal_error500A 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.

11 de 11 operações
GET/v1/healthAPI health

API health

https://api.nexorapay.me/v1/health

Respostas documentadas

200

A 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/check

Respostas documentadas

200401404429503

A 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/balances

Respostas documentadas

200401403429503

A 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/payments

Respostas documentadas

202401403409413422429503

A 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/payments

Parâmetros

limitcursorstatus

Respostas documentadas

200401403422429503

A 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_id

Respostas documentadas

200401403404429503

A 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/refunds

Parâmetros

limitcursorstatus

Respostas documentadas

200401403422429503

A 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_id

Respostas documentadas

200401403404429503

A 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/withdrawals

Parâmetros

limitcursorstatus

Respostas documentadas

200401403422429503

A 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/withdrawals

Respostas documentadas

202401403409413422429503

A 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_id

Respostas documentadas

200401403404429503

A 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 v1

PIX, 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.