Bancarização de crédito

A Banking API expõe a jornada de bancarização do crédito. O intake segue o credential_type do token:

BAAS — parceiro informa o cessionário (assignment)
ACCOUNT — a credencial atua como cessionário da própria conta vinculada ao token; o body não leva assignment

Approve, reject e PIN não fazem parte desta API. Se a conta estiver em assinatura conjunta, a criação deixa a solicitação em WAITING_JOINT_APPROVAL para o Finance.

Referência OpenAPI: API Reference.

Pré-requisitos

mTLS e token OAuth (POST /auth/token). Veja Authentication & mTLS e Requisitos de Segurança.
IP da origem na allow-list da credencial.
Credencial com credential_id positivo no JWT.

Credencial	Token	Scopes	Cessionário
`BAAS`	`baas_id` UUID + `credential_id`	`credit.products.read`, `credit.bankarization.applications.read`, `credit.bankarization.applications.write`	`assignment.assigneeExternalId` + CNPJ
`ACCOUNT`	`account_id` positivo + `credential_id`	os mesmos scopes	conta autenticada; credencial precisa estar vinculada a `accountId`

fee-rules.* e baas-users.* continuam somente BaaS. Credencial ACCOUNT institucional sem accountId recebe 403.

Identificadores (baasId, accountId, credentialId) vêm somente do token. Cabeçalhos públicos x-client-id, x-credential-id, x-baas-id e x-account-id são descartados e reconstruídos.

Endpoints

Método	Path	Scope	Quem usa
`GET`	`/credit/bankarization/products`	`credit.products.read`	BAAS e ACCOUNT
`GET`	`/credit/bankarization/products/{productId}`	`credit.products.read`	BAAS e ACCOUNT
`POST`	`/credit/bankarization/applications`	`credit.bankarization.applications.write`	BAAS e ACCOUNT
`GET`	`/credit/bankarization/applications`	`credit.bankarization.applications.read`	somente ACCOUNT
`GET`	`/credit/bankarization/applications/{requestId}`	`credit.bankarization.applications.read`	BAAS e ACCOUNT
`POST`	`/credit/bankarization/applications/{requestId}/cancel`	`credit.bankarization.applications.write`	BAAS e ACCOUNT
`POST`	`/credit/bankarization/applications/{requestId}/notifications/resend`	`credit.bankarization.applications.write`	BAAS e ACCOUNT

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 ACCOUNT devolve só solicitações do canal da API da conta. Pedidos criados no Finance (JWT) não aparecem aqui.

Fluxo ACCOUNT (cessionário da própria conta)

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 (ACCOUNT)

curl -X POST "https://api.bancodigital.com/credit/bankarization/applications" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_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, com Location da solicitação:

{
  "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 desta documentação, use os paths simplificados (/credit/bankarization/...). O campo links.self (e o header Location) devolve o path canônico do gateway.

Regras do body ACCOUNT:

sem assignment (cessionário arbitrário é rejeitado com 400)
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.

Fluxo BAAS (parceiro)

O parceiro escolhe o cessionário publicado no produto:

curl -X POST "https://api.bancodigital.com/credit/bankarization/applications" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: partner-ccb-2026-08-20-001" \
  -d '{
    "externalRequestId": "erp-8891",
    "creditProductId": 42,
    "debtor": {
      "personType": "NATURAL_PERSON",
      "document": "52998224725",
      "name": "Maria Silva",
      "email": "[email protected]"
    },
    "operation": {
      "amount": "10000.00",
      "term": 12,
      "period": "MONTHLY",
      "firstDueDate": "2026-09-10"
    },
    "assignment": {
      "assigneeExternalId": "fundo-exemplo",
      "assigneeDocument": "11222333000181"
    }
  }'

assignment.assigneeDocument é CNPJ; accountId interno não entra no contrato público
PJ exige representative (CPF, nome e e-mail)
GET /applications (listagem) não está disponível para BAAS (403)

O detalhe do produto para BAAS inclui assignees públicos. ACCOUNT não recebe essa lista: o cessionário é a própria conta.

Consultar e listar

# ACCOUNT: listar solicitações da conta autenticada
curl -X GET "https://api.bancodigital.com/credit/bankarization/applications?page=1&limit=25" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

# BAAS ou ACCOUNT: detalhe
curl -X GET "https://api.bancodigital.com/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

Isolamento: a conta A não lê nem cancela solicitação da conta B. A credencial ACCOUNT também não opera pedidos criados no Finance.

Cancelar e reenviar convite

curl -X POST "https://api.bancodigital.com/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952/cancel" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN"

curl -X POST "https://api.bancodigital.com/credit/bankarization/applications/c55fa769-6364-4e1c-968b-d4880aa9a952/notifications/resend" \
  --cert client.pem --key client.key \
  -H "Authorization: Bearer SEU_TOKEN" \
  -H "Idempotency-Key: resend-2026-08-20-001"

Cancelamento é idempotente e só é aceito antes da criação do Loan. O reenvio devolve a aplicação sanitizada: links, tokens e códigos de convite nunca são expostos e a expiração não é estendida.

Status e `nextAction`

`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

PF sem conta: CUSTOMER_REGISTRATION enquanto o convite está ativo; WAIT_ACCOUNT_APPROVAL quando o cadastro está em análise. PJ sem conta permanece indisponível nesta fase.

RETRY_PENDING pode incluir retryAt e o header Retry-After (limitado, sem contexto do cliente).

Erros

Respostas de erro usam RFC 7807 (application/problem+json). O x-request-id é propagado. Falhas de gateway aparecem como 502; indisponibilidade temporária como 503 (pode incluir Retry-After). O campo error.code da aplicação usa catálogo público fechado:

BANKARIZATION_PROCESSING_RETRY
BANKARIZATION_PROCESSING_FAILED
BANKARIZATION_REQUEST_EXPIRED
BANKARIZATION_INVITATION_EXPIRED
BANKARIZATION_INVITATION_REVOKED
BANKARIZATION_INVITATION_DELIVERY_PENDING
BANKARIZATION_ONBOARDING_STATUS_UNAVAILABLE
BANKARIZATION_INVITATION_NOT_RESENDABLE
BANKARIZATION_VOLUME_LIMIT_REACHED
BANKARIZATION_INTAKE_DISABLED
BANKARIZATION_ASSIGNEE_INSUFFICIENT_FUNDS

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

Fora desta API

Approve / reject / PIN (permanecem no Finance)
Contrato de parceiro (cessionário arbitrário) na credencial ACCOUNT
API de Contas legado (/api/v2)

Pré-requisitos​

Endpoints​

Fluxo ACCOUNT (cessionário da própria conta)​

Criar solicitação (ACCOUNT)​

Fluxo BAAS (parceiro)​

Consultar e listar​

Cancelar e reenviar convite​

Status e nextAction​

Erros​

Fora desta API​