API BaaS — Banking as a Service

Axia Banking as a Service — Implemente contas digitais, PIX e cobranças em minutos.

Base URL: https://baas-gtw.axiadigitalsolutions.com (production) · Versão: v1

A API REST de Blockchain Bank As A Service do ecossistema Axia. Os dados (rotas, campos, exemplos) estão em inglês; as explicações são localizáveis. Para o catálogo interativo, veja a Referência interativa.

1. O que é Banking as a Service (BaaS)

A Axia oferece uma API unificada para que você integre serviços bancários sem lidar diretamente com a complexidade de instituições financeiras.

Componentes-chave

BaaS Gateway (Common/Frontend/API-Gateway) — API REST unificada, sua porta de entrada
Provider BaaS — Instituição financeira autorizada pelo Bacen
Blockchain/Ledger Service (BLS) — Registro imutável de operações bancárias na Axia

O que você consegue fazer

✅ Criar contas digitais (PF/PJ)
✅ Receber pagamentos via PIX (chaves, transferências, webhooks)
✅ Emitir e gerenciar cobranças (boleto, PIX dinâmico)
✅ Consultar saldos e extratos
✅ Executar transferências interbancárias (TED/DOC)
✅ Integrar webhooks para eventos em tempo real

Modelo de Segurança

OAuth 2.0 Client Credentials — Autenticação máquina-a-máquina
JWT Bearer tokens — Autorização stateless com claims identificadores
Assinatura HMAC — Validação de webhooks
Criptografia TLS 1.3 — Todas as conexões (HTTPS obrigatório)

2. Fluxo End-to-End (Criar Conta → Receber PIX)

Aqui está como funciona tipicamente uma integração completa:

Etapa 1: Autenticar

POST /v1/authentication/oauth/access-token

Você envia suas credenciais (client_id + client_secret) e recebe um Bearer token válido por 1h.

Etapa 2: Criar Conta

POST /v1/bank-accounts/create

Envia dados do cliente (PF: CPF, nome, DOB; PJ: CNPJ, razão social). Retorna onBoardingId no status PROCESSING.

Etapa 3: Verificar Onboarding (KYC)

GET /v1/bank-accounts/checkOnboarding?onBoardingId=...

Você faz polling até o status virar APPROVED. Aí a conta está pronta.

Etapa 4: Registrar Chave PIX

POST /v1/pix/create

Você gera uma chave PIX (CPF, telefone, email, aleatória) e recebe a chave + QR Code.

Etapa 5: Receber Pagamento

Webhook POST /notifications/pix-payment-in

GlobalSCM envia um webhook quando o cliente recebe um PIX. Você processa em tempo real.

3. Fluxo de Sequência (Mermaid)

4. Tabela de Endpoints Principais

Grupo	Endpoint	Método	Descrição
Auth	`/v1/authentication/oauth/access-token`	POST	Obter Bearer token via Client Credentials
Contas	`/v1/bank-accounts/create`	POST	Criar conta (PF/PJ) com KYC
Contas	`/v1/bank-accounts/getAccounts`	GET	Listar contas
Contas	`/v1/bank-accounts/checkOnboarding`	GET	Verificar status de KYC (onBoardingId)
Saldo	`/v1/bank-accounts/balance`	GET	Saldo atual + disponível
Extrato	`/v1/bank-accounts/history`	GET	Histórico de transações
PIX	`/v1/pix/create`	POST	Registrar chave PIX
PIX	`/v1/pix/getKeys`	GET	Listar chaves PIX da conta
PIX	`/v1/pix/transfer`	POST	Fazer transferência PIX
PIX	`/v1/pix/createStaticQRCode`	POST	Gerar QR Code estático
PIX	`/v1/pix/pixPayByQRCode`	POST	Pagar via QR Code
Boleto	`/v1/bills/CreateCharge`	POST	Emitir cobrança (boleto)
Boleto	`/v1/bills/checkBill`	GET	Consultar boleto
Webhooks	`/v1/webhooks/register`	POST	Registrar URL para eventos
Webhooks	`/v1/webhooks/list`	GET	Listar eventos

Eventos de Webhook suportados

pix-payment-in — PIX recebido
pix-transfer-out — PIX enviado
bill-payment-confirmed — Boleto pago
onboarding-approved — KYC aprovado
account-balance-updated — Saldo alterado
(mais eventos — ver Webhooks)

5. Primeiros Passos

5.1. Setup Inicial (5 min)

Solicitar credentials ao time Axia (client_id + client_secret)
Obter Bearer token — POST /v1/authentication/oauth/access-token
Testar com cURL — Validate o token fazendo GET /v1/bank-accounts/getAccounts

5.2. Criar Conta (10 min)

Preparar dados do cliente (CPF + dados pessoa física, ou CNPJ + PJ)
POST /v1/bank-accounts/create com payload
Receber onBoardingId
Fazer polling em /v1/bank-accounts/checkOnboarding?onBoardingId=... até APPROVED (tipicamente 1-5 min, manual review)

5.3. Registrar PIX (2 min)

POST /v1/pix/create com tipo (CPF, telefone, email, aleatória)
Receber chave PIX formatada
POST /v1/pix/createStaticQRCode para QR Code estático
Expor ao cliente para receber pagamentos

5.4. Processar Webhook (implementação contínua)

Registrar sua URL em /v1/webhooks/register
Implementar POST /seu/endpoint que receba JSON + header X-Signature: <HMAC-SHA256>
Validar assinatura com seu webhook_secret
Processar evento (ex: crédito na conta do cliente) + retornar 200 OK

6. Estrutura da Documentação

Você está no guia introdutório. A seguir, tópicos aprofundados:

Core

Autenticação — OAuth, tipos de grant, refreshing tokens
Contas bancárias — Criar contas (PF/PJ), KYC, onboarding flow
Saldo & Transações — Consultar saldo, extrato, histórico

Operações de Pagamento

PIX — Chaves, transferências, QR Code dinâmico, SPB
Cobranças & Pagamentos — Boleto, cobrança recorrente, pagamento
Transferências — TED/DOC, transferências interbancárias, agendamento

Integração Avançada

Webhooks — Registrar listeners, assinatura HMAC, retry automático
Antifraude & Aprovação — Fluxo de aprovação, idempotência
Tratamento de Erros — Códigos de erro, debugging, suporte

Referência

Referência interativa — Catálogo completo via OpenAPI

7. Características Destacadas

Async First

Operações críticas (abertura de conta, KYC) são assíncronas com polling. Você faz polling até conclusão; não bloqueamos a conexão.

Idempotência Nativa

Endpoints de criação aceitam Idempotency-Key header — mesma requisição enviada 2x retorna a mesma resposta sem duplicação.

Webhooks com Retry

Se seu endpoint falhar, tentamos automaticamente até 5x com backoff exponencial (1s, 2s, 4s, 8s, 16s).

Multi-Tenant Ready

Cada integrador é isolado. Seu client_id limita você aos dados do seu tenant.

Auditoria Completa

Toda operação é registrada em Blockchain/Ledger — histórico imutável para compliance.

8. Exemplo: Criar Conta + PIX em 3 Passos

bash

# Passo 1: Autenticar
TOKEN=$(curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/authentication/oauth/access-token \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": "YOUR_CLIENT_ID",
    "client_secret": "YOUR_CLIENT_SECRET",
    "grant_type": "client_credentials"
  }' | jq -r '.data.access_token')

# Passo 2: Criar conta
ACCOUNT=$(curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/bank-accounts/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-client-id: YOUR_TENANT_ID" \
  -d '{
    "customerType": "PF",
    "cpf": "12345678900",
    "fullName": "João da Silva",
    "birthDate": "1990-05-15",
    "email": "joao@example.com"
  }')

ONBOARDING_ID=$(echo $ACCOUNT | jq -r '.data.onBoardingId')

# Passo 3: Aguardar KYC (polling simples)
for i in {1..30}; do
  STATUS=$(curl -X GET "https://baas-gtw.axiadigitalsolutions.com/v1/bank-accounts/checkOnboarding?onBoardingId=$ONBOARDING_ID" \
    -H "Authorization: Bearer $TOKEN" \
    -H "x-client-id: YOUR_TENANT_ID" | jq -r '.data.status')
  
  if [ "$STATUS" = "APPROVED" ]; then
    echo "✅ Conta aprovada!"
    break
  fi
  
  echo "⏳ Status: $STATUS, tentando novamente em 10s..."
  sleep 10
done

# Passo 4: Registrar PIX
PIX=$(curl -X POST https://baas-gtw.axiadigitalsolutions.com/v1/pix/create \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -H "x-client-id: YOUR_TENANT_ID" \
  -d '{
    "accountId": "'$(echo $ACCOUNT | jq -r '.data.accountId')'",
    "keyType": "CPF",
    "keyValue": "12345678900"
  }')

echo "✅ PIX registrado:"
echo $PIX | jq '.data.pixKey, .data.qrCode'

9. Glossário Rápido

Termo	Significado
BaaS	Banking as a Service — API para operações bancárias
GlobalSCM	Provider (instituição financeira real autorizado Bacen)
BLS	Blockchain/Ledger Service — auditoria imutável Axia
PIX	Sistema de pagamentos instantâneos (SPB, Bacen)
Onboarding	Processo de KYC (verificação de identidade)
Webhook	Callback HTTPS — você recebe eventos em tempo real
Idempotência	Mesma requisição 2x = mesma resposta (sem duplicação)
HMAC-SHA256	Assinatura de webhooks para validação

Getting Started

Prerequisites

To integrate with the Axia BaaS Gateway, you will need:

Client ID and Client Secret — provided upon registration in the Developer Portal
x-client-id — your tenant identifier (required for financial transactions)

Authentication Flow

All API calls (except authentication itself) require a Bearer token obtained via the OAuth endpoint:

1. Encode your credentials:  Base64("Client_ID:Client_Secret")
2. POST /v1/authentication/oauth/access-token  →  receive Bearer token
3. Use the Bearer token in the Authorization header for all subsequent requests

Common Headers

Header	Required	Description
`Authorization`	Yes	`Basic <base64>` for auth endpoints; `Bearer <token>` for all others
`Content-Type`	Yes (POST/PUT)	`application/json`
`x-client-id`	Yes (financial ops)	Your tenant identifier
`Idempotency-Key`	Recommended	UUID to prevent duplicate transactions

Standard Response Format

json

{
  "status": "CONFIRMED",
  "data": { },
  "message": "",
  "when": 1710700000000
}

Field	Description
`status`	`CONFIRMED`, `PROCESSING`, or `ERROR`
`data`	Operation-specific response payload
`message`	Error description (when `status` = `ERROR`)
`when`	Timestamp in milliseconds

Quick Reference

Complete API Endpoint Summary

Method	Endpoint	Description
Authentication
POST	`/v1/authentication/oauth/access-token`	Get Bearer token
POST	`/v1/authentication/oauth/introspect`	Validate token
POST	`/v1/authentication/oauth/revoke`	Revoke token
Bank Accounts
POST	`/v1/bank-accounts/create`	Create account (PF/PJ)
GET	`/v1/bank-accounts/checkOnboarding`	Check onboarding status
GET	`/v1/bank-accounts/balance`	Get account balance
GET	`/v1/bank-accounts/history`	Get transaction history
GET	`/v1/bank-accounts/getTransactionById`	Get transaction receipt
GET	`/v1/bank-accounts/getAccounts`	List accounts
GET	`/v1/bank-accounts/getAccountInfoNaturalPerson`	Get PF account info
GET	`/v1/bank-accounts/getAccountInfoLegalPerson`	Get PJ account info
PUT	`/v1/bank-accounts/updateAccountInfoLegalPerson`	Update PJ info
POST	`/v1/bank-accounts/generateInternalTransferRequest`	Internal transfer
POST	`/v1/bank-accounts/generateExternalTransferRequest`	External transfer (TED)
POST	`/v1/bank-accounts/closeAccount`	Close account
PIX
POST	`/v1/pix/create`	Register PIX key
POST	`/v1/pix/exclude`	Remove PIX key
GET	`/v1/pix/getKeys`	List PIX keys
POST	`/v1/pix/getAccountInfoByPixKey`	Look up account by PIX key
POST	`/v1/pix/transfer`	Execute PIX transfer
GET	`/v1/pix/check`	Check PIX status
POST	`/v1/pix/createStaticQRCode`	Create static QR Code
GET	`/v1/pix/getStaticQRCode`	Get QR Code data
POST	`/v1/pix/getQRCodeDataByEmv`	Parse QR Code EMV
POST	`/v1/pix/pixPayByQRCode`	Pay via QR Code
POST	`/v1/pix/reverse`	Reverse PIX transaction
Bills
POST	`/v1/bills/payBill`	Pay a bill (boleto)
POST	`/v1/bills/checkBill`	Check bill details
POST	`/v1/bills/CreateCharge`	Create a charge
POST	`/v1/bills/CheckCharge`	Check charge status
POST	`/v1/bills/getChargePDF`	Get charge PDF

10. Suporte & SLA

Documentação: Você está aqui 👋
Email: suporte@axiadigitalsolutions.com
SLA: 99.9% uptime (com retry automático de webhooks)

Pronto para começar? Clique em Autenticação e configure seu primeiro token. 🚀

API BaaS — Banking as a Service ​

1. O que é Banking as a Service (BaaS) ​

Componentes-chave ​

O que você consegue fazer ​

Modelo de Segurança ​

2. Fluxo End-to-End (Criar Conta → Receber PIX) ​

Etapa 1: Autenticar ​

Etapa 2: Criar Conta ​

Etapa 3: Verificar Onboarding (KYC) ​

Etapa 4: Registrar Chave PIX ​

Etapa 5: Receber Pagamento ​

3. Fluxo de Sequência (Mermaid) ​

4. Tabela de Endpoints Principais ​

Eventos de Webhook suportados ​

5. Primeiros Passos ​

5.1. Setup Inicial (5 min) ​

5.2. Criar Conta (10 min) ​

5.3. Registrar PIX (2 min) ​

5.4. Processar Webhook (implementação contínua) ​

6. Estrutura da Documentação ​

Core ​

Operações de Pagamento ​

Integração Avançada ​

Referência ​

7. Características Destacadas ​

Async First ​

Idempotência Nativa ​

Webhooks com Retry ​

Multi-Tenant Ready ​

Auditoria Completa ​

8. Exemplo: Criar Conta + PIX em 3 Passos ​

9. Glossário Rápido ​

Getting Started ​

Prerequisites ​

Authentication Flow ​

Common Headers ​

Standard Response Format ​

Quick Reference ​

Complete API Endpoint Summary ​

10. Suporte & SLA ​