Documentação da API

O Argentrix Payment Gateway expõe uma API REST com formato JSON. Todas as requisições devem ser feitas sobre HTTPS.

Base URL

https://api.argentrix.com.br

Versão

Formato

application/json

Headers obrigatórios em todas as requisições:

Content-Type: application/json
Authorization: Bearer <jwt_token> (rotas protegidas)
Idempotency-Key: <uuid-v4> (criação de transações)
X-Request-ID (opcional, propagado nas respostas)

Autenticação

Troque suas credenciais de API (client_id + client_secret) por um JWT Bearer Token com validade de 1 hora. Use o token em todas as rotas protegidas.

POST/v1/auth

Request — Header

Authorization: ApiKey {client_id}:{client_secret}

Response 200

{
  "access_token": "eyJhbGciOiJIUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Response 401

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Credenciais inválidas ou expiradas.",
    "request_id": "uuid-v4",
    "timestamp": "2026-04-03T10:00:00Z"
  }
}

JWT Claims incluídos no token:

company_id — UUID da empresa
client_id — Identificador da credencial
env — sandbox ou production
scope — Permissões: cashin:write, cashin:read, cashout:write, cashout:read, balance:read
exp — Expiração (1 hora)

Cashin — Cobrança PIX

Criar Cashin

POST/v1/cashinJWTIdempotency-Key

Request Body

{
  "reference_id": "pedido-001",
  "amount": 10000,
  "description": "Compra #001",
  "callback_url": "https://merchant.com/webhook",
  "expiration_time": 3600,
  "integration_id": null,
  "payer": {
    "name": "João Silva",
    "document": "12345678900",
    "email": "joao@email.com",
    "phone": "11999998888"
  },
  "reject_payment_if_possible": false,
  "metadata": { "invoice_id": "INV-001" }
}

Campos obrigatórios: reference_id (único por empresa),amount (centavos, int64 — R$100,00 = 10000),callback_url. O Idempotency-Key header previne processamento duplicado.

Objeto payer (opcional — pagador esperado):

name — nome completo do pagador esperado
document — CPF (11 dígitos) ou CNPJ (14 dígitos), com ou sem máscara
email — obrigatório para Mercado Pago
phone — telefone com DDD (ex.: 11999998888)

Campos legados first_name, last_name e document_number ainda são aceitos para retrocompatibilidade, mas estão depreciados.

Mercado Pago exige payer.email: cobranças PIX via Mercado Pago falham se o email do pagador não for enviado. Sem ele, o gateway retorna422 VALIDATION_ERROR. Para integrações ARXBANK, Transfeera e Owem, o campo é opcional mas fortemente recomendado (permite cálculo de risk_level).

Anti-fraude — reject_payment_if_possible:

Quando true, solicita ao banco parceiro que rejeite pagamentos cujo CPF/CNPJ não bate com o declarado em payer.document. Suportado apenas por Transfeera (quando payer.document está preenchido) e ARXBANK. MP e Owem não oferecem essa proteção nativa — retornamreject_applied_by_bank: false.

Response 201 Created

{
  "cashin_id": "uuid-v4",
  "reference_id": "pedido-001",
  "status": "pending",
  "amount": 10000,
  "currency": "BRL",
  "bank_code": "arxbank",
  "pix_qr_code": "00020126580014br.gov.bcb.pix...",
  "pix_qr_image": "data:image/png;base64,...",
  "pix_e2e_id": null,
  "expires_at": "2026-04-03T11:00:00Z",
  "created_at": "2026-04-03T10:00:00Z",
  "paywall_link": "https://dashboard.argentrix.com.br/paywall/uuid-v4"
}

paywall_link: URL pública whitelabel que você pode compartilhar com o pagador final. A página aplica o tema configurado em /dashboard/paywall(logo, cores, fonte, canais de contato) e faz polling automático para refletir a confirmação do pagamento em tempo real.

Consultar Cashin

GET/v1/cashin/:idJWT

Response 200

{
  "cashin_id": "uuid-v4",
  "reference_id": "pedido-001",
  "status": "approved",
  "amount": 10000,
  "currency": "BRL",
  "bank_code": "arxbank",
  "pix_e2e_id": "E12345678901234567890123456789012",
  "description": "Compra #001",
  "expires_at": "2026-04-03T11:00:00Z",
  "paid_at": "2026-04-03T10:30:00Z",
  "payer": {
    "name": "João Silva",
    "document": "12345678900",
    "bank": "001",
    "pix_key": "joao@email.com"
  },
  "expected_payer": {
    "name": "João Silva",
    "document": "12345678900",
    "email": "joao@email.com",
    "phone": "11999998888"
  },
  "reject_payment_if_possible": false,
  "reject_applied_by_bank": null,
  "risk_level": "LOW",
  "risk_assessed_at": "2026-04-03T10:30:00Z",
  "timeline": {
    "created_at": "2026-04-03T10:00:00Z",
    "bank_callback_at": "2026-04-03T10:30:00Z",
    "webhook_sent_at": "2026-04-03T10:30:01Z",
    "client_fetch_at": "2026-04-03T10:30:05Z"
  },
  "metadata": { "invoice_id": "INV-001" },
  "created_at": "2026-04-03T10:00:00Z",
  "updated_at": "2026-04-03T10:30:00Z"
}

payer é o pagador real (preenchido após o pagamento).expected_payer é o declarado na criação (null se não enviado).risk_level é calculado comparando os dois quando ambos existem — veja Anti-fraude & Risk Level.

Cashout — Transferência PIX

Criar Cashout

PUT/v1/cashoutJWTIdempotency-Key

Request Body

{
  "reference_id": "salary-001",
  "amount": 50000,
  "description": "Pagamento salário",
  "callback_url": "https://merchant.com/webhook",
  "recipient": {
    "pix_key_type": "cpf",
    "pix_key": "12345678900",
    "name": "João Silva",
    "document": "12345678900",
    "email": "joao@email.com",
    "phone": "11999998888"
  },
  "reject_payment_if_possible": false,
  "integration_id": null,
  "metadata": { "employee_id": "EMP-001" }
}

Campos adicionais em recipient (opcionais):

email — e-mail do destinatário (usado por alguns bancos para notificação)
phone — telefone com DDD

Anti-fraude — reject_payment_if_possible (guardrail DICT):

Quando true, o gateway compara os dados declarados emrecipient.name/document com o titular real devolvido pelo banco (actual_recipient, resolvido via DICT) e registra um alerta imutável no audit trail se a divergência for HIGH, VERY_HIGH ouEXTREME. Não aborta cashouts já liquidados.

Tipos de chave PIX aceitos (pix_key_type):

cpf

CPF (11 dígitos)

cnpj

CNPJ (14 dígitos)

email

E-mail

phone

Telefone (+55...)

random

Chave aleatória (EVP)

Response 202 Accepted

{
  "cashout_id": "uuid-v4",
  "reference_id": "salary-001",
  "status": "pending",
  "amount": 50000,
  "currency": "BRL",
  "bank_code": "arxbank",
  "pix_e2e_id": null,
  "created_at": "2026-04-03T10:00:00Z"
}

Consultar Cashout

GET/v1/cashout/:idJWT

Response 200

{
  "cashout_id": "uuid-v4",
  "reference_id": "salary-001",
  "status": "approved",
  "amount": 50000,
  "currency": "BRL",
  "bank_code": "arxbank",
  "pix_e2e_id": "E12345678901234567890123456789012",
  "description": "Pagamento salário",
  "recipient": {
    "pix_key_type": "cpf",
    "pix_key": "12345678900",
    "name": "João Silva",
    "document": "12345678900",
    "email": "joao@email.com",
    "phone": "11999998888",
    "bank": "041"
  },
  "actual_recipient": {
    "name": "João Silva",
    "document": "12345678900"
  },
  "reject_payment_if_possible": false,
  "reject_applied_by_bank": null,
  "risk_level": "LOW",
  "risk_assessed_at": "2026-04-03T10:15:00Z",
  "timeline": {
    "created_at": "2026-04-03T10:00:00Z",
    "bank_callback_at": "2026-04-03T10:15:00Z",
    "webhook_sent_at": "2026-04-03T10:15:01Z",
    "client_fetch_at": null
  },
  "metadata": { "employee_id": "EMP-001" },
  "created_at": "2026-04-03T10:00:00Z",
  "updated_at": "2026-04-03T10:15:00Z"
}

recipient é o destinatário declarado no POST.actual_recipient é o titular real devolvido pelo banco (via DICT ou webhook). Divergências geram risk_level — veja a próxima seção.

Anti-fraude & Risk Level

O gateway compara os dados declarados na criação da transação (payer no cashin, recipient no cashout) com os dados reais devolvidos pelo banco parceiro (via webhook, polling ou DICT). A comparação gera um risk_level persistido na transação.

Vocabulário de risk_level

Status	Valor	Descrição
Baixo	LOW	Nome e documento batem exatamente (normalizados, removendo acentos/caixa).
Médio	MEDIUM	Documento idêntico, mas nome com leve divergência (ex.: abreviação).
Alto	HIGH	Apenas um dos campos (nome OU documento) bate.
Muito alto	VERY_HIGH	Nem nome nem documento batem, mas algum dado auxiliar bate.
Extremo	EXTREME	Nenhum dado do declarado bate com o real.

Quando risk_level aparece:

Só é calculado quando há dados declarados e o banco já devolveu dados reais.
null em transações pendentes ou sem payer/recipient declarado.
risk_assessed_at marca o instante da avaliação.
O documento do banco pode vir mascarado (ex.: ***.018.798-**) — o gateway trata essa máscara no comparador.

Proteções automáticas

Cashin — reject_payment_if_possible:

Pede ao banco parceiro que rejeite pagamentos de pagadores com CPF/CNPJ diferente do declarado, antes do valor cair na conta. O camporeject_applied_by_bank na resposta indica se a proteção foi honrada:true (aplicada), false (banco não suporta) ounull (não solicitada).

Cashout — guardrail DICT:

Quando o cashout é criado com reject_payment_if_possible: true e o banco devolve um actual_recipient cujo risco é HIGH,VERY_HIGH ou EXTREME, o gateway grava um alerta imutávelrisk_guardrail no audit trail. Transferências já liquidadas não são revertidas automaticamente.

Suporte por banco

Banco	reject (cashin)	risk_level	Observações
arxbank	Suportado	Sim	Mock bank sandbox — simula aceitação.
transfeera	Suportado	Sim	Só honrado quando `payer.document` é enviado.
mercadopago	Não	Sim	Exige `payer.email`. Sem `reject` nativo.
owem	Não	Sim	Sem `reject` nativo; risk calculado via webhook.

Status de Transação

Ambas as transações (cashin e cashout) utilizam um conjunto universal de status. Cada tipo possui estados finais diferentes.

Cashin (Cobrança PIX)

Status	Valor	Descrição
Pendente	pending	Cobrança criada, aguardando pagamento do pagador (estado inicial e padrão enquanto o banco não confirma).
Processando	processing	Estado transiente durante o processamento de um webhook de aprovação (dura segundos).
Aprovado	approved	Pagamento confirmado. Valor creditado. Estado final.
Falhou	failed	Pagamento falhou definitivamente. Estado final.
Cancelado	cancelled	Cobrança cancelada pelo sistema ou operador. Estado final.
Expirado	expired	Cobrança expirou sem pagamento. Estado final.

Fluxo webhook: pending → processing → approved | failed | expired | cancelled
Fluxo polling: pending → approved (direto) — processing é pulado quando não há webhook ativo.

Cashout (Transferência PIX)

Status	Valor	Descrição
Pendente	pending	Transferência aceita pelo banco, aguardando confirmação da liquidação.
Processando	processing	Estado transiente durante processamento do webhook de confirmação.
Aprovado	approved	Transferência concluída. Valor enviado. Estado final.
Falhou	failed	Transferência falhou definitivamente. Estado final.
Cancelado	cancelled	Transferência cancelada antes do processamento. Estado final.
Estornado	reversed	Valor devolvido ao remetente (refund/chargeback). Estado final.

Fluxo webhook: pending → processing → approved | failed | cancelled | reversed
Bancos com liquidação síncrona (ex.: Owem) podem ir direto pending → approved na própria criação.

Importante: diferente do comportamento antigo, a transação permanece empendingaté o gateway receber a confirmação real do banco parceiro (via webhook ou polling). O estadoprocessingé reservado para a janela de processamento do webhook de aprovação, e tipicamente dura segundos.

Saldo

Saldo interno (Argentrix)

GET/v1/balanceJWT

Retorna o saldo global da empresa e o saldo controlado em cada banco parceiro. Um cashout só pode ser enviado via um banco que tenha saldo suficiente — não basta ter saldo global se ele estiver concentrado em outro banco.

Response 200

{
  "balance": {
    "available": 10000,
    "currency": "BRL"
  },
  "banks": {
    "owem":        { "available": 2000, "currency": "BRL" },
    "mercadopago": { "available": 8000, "currency": "BRL" }
  }
}

balance.available é líquido (já desconta tarifas do gateway). banks.<code>.available é cashin aprovado − cashout enviado por banco, útil para decidir qual integração usar em um próximo cashout.

Saldo por banco parceiro

GET/v1/bankbalanceJWT

Retorna o saldo disponível em cada banco parceiro integrado.

Response 200

{
  "balances": [
    {
      "bank_code": "arxbank",
      "bank_name": "ARX Mock Bank",
      "available": 99999999,
      "blocked": 0,
      "currency": "BRL"
    }
  ]
}

Webhooks

Quando o status de uma transação muda, enviamos um POST para o callback_url configurado na transação. O payload é assinado com HMAC-SHA256 usando o webhook_secret da sua empresa.

Payload enviado ao seu servidor

{
  "event": "cashin.approved",
  "transaction_id": "uuid-v4",
  "transaction_type": "cashin",
  "status": "approved",
  "timestamp": "2026-04-03T10:30:00Z"
}

Headers enviados:

X-Argentrix-Signature — sha256=hex(hmac_sha256(secret, timestamp + "." + body))
X-Argentrix-Timestamp — Unix timestamp
X-Request-ID — UUID de correlação
Content-Type — application/json

Validação da assinatura:

expected = hex(hmac_sha256(webhook_secret, timestamp + "." + raw_body))
if expected == signature_from_header:
    # payload é autêntico

Eventos possíveis:

cashin.pending

cashout.pending

cashin.processing

cashout.processing

cashin.approved

cashout.approved

cashin.failed

cashout.failed

cashin.cancelled

cashout.cancelled

cashin.expired

cashout.reversed

Retry policy: Em caso de falha (HTTP != 2xx), o webhook é reenviado com backoff exponencial: 5s, 15s, 45s, 2min, 10min. Máximo de 5 tentativas.

Erros

Todos os erros seguem o formato padrão abaixo. Use o campo code para tratamento programático.

Formato de erro

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Descrição legível do erro.",
    "request_id": "uuid-v4",
    "timestamp": "2026-04-03T10:00:00Z"
  }
}

HTTP	Code	Descrição
400	BAD_REQUEST	Corpo da requisição inválido ou malformado.
401	UNAUTHORIZED	Token JWT ausente, inválido ou expirado.
403	FORBIDDEN	Sem permissão para acessar este recurso.
404	NOT_FOUND	Recurso não encontrado.
422	VALIDATION_ERROR	Campos inválidos na requisição.
422	DUPLICATE_REFERENCE	reference_id já utilizado nesta empresa.
422	DUPLICATE_IDEMPOTENCY_KEY	Idempotency-Key já processada.
429	RATE_LIMITED	Excedeu o limite de requisições (10/min no /auth).
500	INTERNAL_ERROR	Erro interno do servidor.
503	BANK_UNAVAILABLE	Banco parceiro temporariamente indisponível.

Health Check

GET/health/live

Liveness probe. Sempre retorna 200 se o processo está rodando.

{ "status": "ok" }

GET/health/ready

Readiness probe. Verifica conectividade com Postgres, Mongo e Redis.

{
  "status": "ok",
  "checks": {
    "postgres": "ok",
    "mongo": "ok",
    "redis": "ok"
  }
}

Rate Limiting

Endpoint	Limite	Janela
POST /v1/auth	10 requisições	por minuto / por IP
Demais endpoints	100 requisições	por segundo / por empresa

Rate limiting é implementado via Redis. Quando Redis está indisponível, o rate limiting é desabilitado (graceful degradation).