Bancarização de crédito

Bancarização é o fluxo em que a conta autenticada origina uma operação de crédito (CCB) para um devedor pessoa física. Nesta jornada a própria conta é o cessionário: ela recebe a cessão da operação, sem escolher outro fundo ou cessionário no pedido.

Use esta documentação se você integra com credencial de conta da API de Contas. Credencial BaaS não opera esta jornada.

O que a API cobre:

Consultar os produtos de crédito publicados para a conta
Criar a solicitação com os dados do devedor e da operação
Acompanhar o status até a contratação
Reenviar o convite de cadastro, se o devedor ainda não tiver conta
Cancelar a solicitação antes da criação do empréstimo (Loan)

O que não entra nesta API: approve, reject e PIN. Se a conta exigir assinatura conjunta, a criação deixa a solicitação em WAITING_JOINT_APPROVAL para o Finance.

Referência OpenAPI: API de Contas — Bancarização.

Pré-requisitos

Certificado mTLS da credencial de conta. Veja Configurando certificado mTLS.
Token OAuth da credencial de conta (não use credencial BaaS para esta jornada).
IP da origem na allow-list da credencial.

Scope	Uso
`credit.products.read`	Listar e consultar produtos
`credit.bankarization.applications.read`	Listar e consultar solicitações da conta
`credit.bankarization.applications.write`	Criar, cancelar e reenviar convite

A conta autenticada é o cessionário. Enviar assignment resulta em 400. Credencial institucional sem accountId recebe 403. Os paths não usam o prefixo /api/v2.

Endpoints

Método	Path	Scope
`GET`	`/credit/bankarization/products`	`credit.products.read`
`GET`	`/credit/bankarization/products/{productId}`	`credit.products.read`
`POST`	`/credit/bankarization/applications`	`credit.bankarization.applications.write`
`GET`	`/credit/bankarization/applications`	`credit.bankarization.applications.read`
`GET`	`/credit/bankarization/applications/{requestId}`	`credit.bankarization.applications.read`
`POST`	`/credit/bankarization/applications/{requestId}/cancel`	`credit.bankarization.applications.write`
`POST`	`/credit/bankarization/applications/{requestId}/notifications/resend`	`credit.bankarization.applications.write`

Idempotency-Key é obrigatório na criação e no reenvio (até 160 caracteres). Replay com o mesmo payload devolve a solicitação original; não estende a expiração.

A listagem devolve só solicitações criadas por esta API. Pedidos criados no Finance não aparecem aqui.

Fluxo

Listar produtos publicados para a conta
Consultar parâmetros e faixas de taxa
POST /applications com devedor PF + operação (sem assignment)
Acompanhar GET /applications/{requestId}
Se nextAction=CUSTOMER_REGISTRATION, reenviar convite quando necessário
Cancelar antes do Loan, se preciso

Catálogo da conta:

publicações INSTITUTIONAL se a conta não tem tenant BaaS
publicações BAAS se a conta pertence a um parceiro

Criar solicitação

curl -X POST "https://secureapi.onz.finance/credit/bankarization/applications" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: account-ccb-2026-08-20-001" \
  -d '{
    "creditProductId": 42,
    "debtor": {
      "personType": "NATURAL_PERSON",
      "document": "52998224725",
      "name": "Maria Silva",
      "email": "[email protected]",
      "phone": "11999999999"
    },
    "operation": {
      "amount": "10000.00",
      "term": 12,
      "period": "MONTHLY",
      "firstDueDate": "2026-09-10"
    }
  }'

Resposta 202 Accepted:

{
  "requestId": "c55fa769-6364-4e1c-968b-d4880aa9a952",
  "externalRequestId": null,
  "status": "READY",
  "nextAction": "INTERNAL_CREDIT_FLOW",
  "expiresAt": "2026-08-27T12:00:00.000Z",
  "pricing": {
    "bankarizationFeeRate": "2.00",
    "bankarizationFeeBase": "LOAN_PRINCIPAL",
    "bankarizationFeeAmount": "200.00"
  },
  "links": {
    "self": "/public/gw_banking/v1/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952"
  }
}

Nas chamadas use os paths simplificados (/credit/bankarization/...). O campo links.self (e o header Location) devolve o path canônico do gateway.

Regras do body:

sem assignment
somente devedor NATURAL_PERSON (CPF)
valores monetários e taxas como string decimal (ex.: "10000.00")
telefone brasileiro aceita E.164 +55 e formatos nacionais; a API normaliza para DDD + número (10–11 dígitos)

Se a conta exigir quorum de assinatura, status vem WAITING_JOINT_APPROVAL e nextAction vem JOINT_APPROVAL. A aprovação continua no Finance.

Consultar, cancelar e reenviar

curl -X GET "https://secureapi.onz.finance/credit/bankarization/applications?page=1&limit=25" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer <access_token>"

curl -X GET "https://secureapi.onz.finance/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer <access_token>"

curl -X POST "https://secureapi.onz.finance/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952/cancel" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer <access_token>"

curl -X POST "https://secureapi.onz.finance/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952/notifications/resend" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer <access_token>" \
  -H "Idempotency-Key: resend-2026-08-20-001"

A conta A não lê nem cancela solicitação da conta B. Cancelamento é idempotente e só é aceito antes da criação do Loan. O reenvio não devolve links, tokens nem códigos de convite e não estende a expiração.

Status e nextAction

Cancelamento só é aceito antes da criação do Loan. Estados terminais não exigem nova ação do integrador.

`status`	Significado
`RECEIVED`	Solicitação recebida; processamento inicial
`WAITING_JOINT_APPROVAL`	Aguarda aprovação conjunta no Finance
`WAITING_ACCOUNT_APPROVAL`	Cadastro do devedor em análise
`WAITING_ACCOUNT_REGULARIZATION`	Conta do devedor precisa regularização
`REQUIRES_ACCOUNT_SELECTION`	Há mais de uma conta elegível (não selecionada nesta API)
`READY`	Pronta para o fluxo interno de crédito
`PROCESSING`	Em processamento
`RETRY_PENDING`	Aguardando nova tentativa; pode incluir `Retry-After`
`LOAN_CREATED`	Loan criado; cancelamento não é mais aceito
`AWAITING_SIGNATURES`	Aguardando assinaturas do contrato
`AWAITING_LOAN_APPROVAL`	Aguardando aprovação do Loan
`ASSIGNMENT_PENDING`	Cessão em andamento
`COMPLETED`	Concluída (terminal)
`REJECTED`	Rejeitada (terminal)
`EXPIRED`	Expirada (terminal)
`FAILED`	Falhou (terminal)
`CANCELED`	Cancelada (terminal)

`nextAction`	Significado
`INTERNAL_CREDIT_FLOW`	Solicitação segue o fluxo interno de crédito
`CUSTOMER_REGISTRATION`	Convite de cadastro PF ativo
`WAIT_ACCOUNT_APPROVAL`	Cadastro em análise, sem convite ativo
`WAIT_ACCOUNT_REGULARIZATION`	Conta do devedor precisa regularização
`ACCOUNT_SELECTION_REQUIRED`	Há mais de uma conta elegível (não selecionada nesta API)
`JOINT_APPROVAL`	Conta em assinatura conjunta; approve/PIN no Finance
`NONE`	Estado terminal ou sem ação do integrador

Erros

Respostas de erro usam RFC 7807 (application/problem+json).

HTTP	Quando
`400`	Body inválido ou `assignment` enviado
`401`	Token ausente ou inválido
`403`	Credencial sem `accountId`, scope ou mTLS/IP ausente
`404`	Solicitação de outra conta
`409`	Conflito de estado (ex.: já existe Loan)
`422`	Produto/política/saldo não permitem a operação
`502`	Falha de gateway
`503`	Serviço temporariamente indisponível; pode incluir `Retry-After`

Pré-requisitos​

Endpoints​

Fluxo​

Criar solicitação​

Consultar, cancelar e reenviar​

Status e nextAction​

Erros​