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",
  "expires_in": 3600,
  "integration_id": null,
  "metadata": { "invoice_id": "INV-001" }
}

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

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"
}

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"
  },
  "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"
}

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"
  },
  "integration_id": null,
  "metadata": { "employee_id": "EMP-001" }
}

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",
    "bank": "041"
  },
  "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"
}

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.
Processando	processing	Pagamento detectado, em confirmação pelo banco.
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: pending → processing → approved | failed | cancelled | expired

Cashout (Transferência PIX)

Status	Valor	Descrição
Pendente	pending	Transferência criada, aguardando processamento.
Processando	processing	Transferência sendo processada pelo banco parceiro.
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: pending → processing → approved | failed | cancelled | reversed

Saldo

Saldo interno (Argentrix)

GET/v1/balanceJWT

Retorna o saldo calculado: soma dos cashins aprovados menos cashouts enviados.

Response 200

{
  "balance": {
    "available": 500000,
    "currency": "BRL"
  }
}

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