BrasilCash BaaS — API do Parceiro (v1)

Esta API permite que o seu sistema consulte as contas dos seus clientes, gere links de abertura de conta (onboarding) e emita as credenciais que cada conta usa para operar.

Listar contas — GET /v1/accounts

Consultar conta — GET /v1/accounts/{id}

Onboarding

Criar link de onboarding — POST /v1/onboards

Listar onboardings — GET /v1/onboards

Credenciais da conta

Criar credencial — POST /v1/account/credentials

Fluxo típico de integração

Visão geral

Ambiente	URL base
Homologação	`https://<url-de-homologacao>`
Produção	`https://<url-de-producao>`

Todas as rotas desta documentação ficam sob o prefixo /v1. Sua chave só dá acesso aos dados do seu próprio parceiro: contas e onboardings de outros parceiros nunca aparecem e, se consultados pelo id, respondem como inexistentes (404).

Autenticação

Toda requisição precisa do header X-Api-Key com a chave de API do parceiro:

Como obter a chave

A chave é gerada no Painel do parceiro, em Chaves de API, por um usuário administrador, ou enviada pela Brasil Cash.

A chave completa é exibida uma única vez, no momento da criação. Guarde-a em um cofre de segredos; a Brasil Cash não consegue recuperá-la depois. Se ela for perdida, gere uma nova pelo Painel.

Toda chave nova passa por análise da Brasil Cash e só funciona depois de aprovada.

A chave é vinculada a uma lista de IPs permitidos. Chamadas feitas de qualquer outro IP são recusadas.

Uma chave pode ter data de expiração.

Quando a chave é recusada

Chave ausente, inválida, em análise, rejeitada, expirada ou usada de um IP fora da lista recebem a mesma resposta 401. Por segurança, a API não informa qual foi o motivo:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Invalid or inactive X-Api-Key",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Se receber 401 com uma chave que deveria funcionar, verifique se ela já foi aprovada, se não expirou e se o IP de saída do seu servidor está na lista da chave.

Convenções

Formato: requisições e respostas em JSON (Content-Type: application/json), com nomes de campos em camelCase.

Datas: respostas em UTC, no formato ISO 8601 (2026-03-14T13:22:05.123Z). Filtros de data usam yyyy-MM-dd e são inclusivos.

Enums: enviados e recebidos como texto ("Active", "PJ").

Documentos: CPF e CNPJ são devolvidos só com dígitos.

Ids: UUIDs (8d1e4f2a-3b5c-4d6e-8f7a-9b0c1d2e3f4a).

Paginação

As listagens recebem Page e PageSize na query string e devolvem:

{
  "items": [ ... ],
  "page": 1,
  "pageSize": 50,
  "total": 132
}

Parâmetro	Padrão	Regra
`Page`	1	Começa em 1
`PageSize`	50	Entre 1 e 200 itens por página

total é a quantidade de itens que atendem aos filtros, considerando todas as páginas.

Erros

Os erros seguem o padrão RFC 7807 (Content-Type: application/problem+json). Informe o traceId ao suporte da Brasil Cash para agilizar a análise de um problema.

Status	Significado
`400`	Dados inválidos. O campo `errors` diz qual campo falhou e por quê
`401`	Chave ausente, inválida ou não autorizada para o IP de origem
`404`	Recurso não encontrado (ou pertencente a outro parceiro)
`409`	Regra de negócio impede a operação. O motivo vem em `detail`
`429`	Limite de requisições excedido
`502`	Um serviço interno da Brasil Cash não respondeu. Tente novamente em instantes

Exemplo de erro de validação (400):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "expirationDays": ["Between 30 and 90"]
  },
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Exemplo de regra de negócio (409):

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.10",
  "title": "Business rule violated",
  "status": 409,
  "detail": "Account is not active",
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-00"
}

Limite de requisições

Cada chave pode fazer até 120 requisições por minuto. Ao exceder, a API responde 429 com o header Retry-After indicando quantos segundos esperar antes de tentar de novo.

Contas

Objeto conta

Campo	Tipo	Descrição
`id`	uuid	Identificador da conta
`type`	texto	`PF` (pessoa física) ou `PJ` (pessoa jurídica)
`status`	texto	`Pending`, `Active`, `Blocked` ou `Closed`
`document`	texto	CPF ou CNPJ, só dígitos
`name`	texto	Nome completo ou razão social
`tradingName`	texto \| null	Nome fantasia (PJ)
`accountNumber`	texto \| null	Número da conta. Preenchido quando a conta é aberta
`accountBranch`	texto \| null	Agência. Preenchida quando a conta é aberta
`riskLevel`	texto	`Low`, `Medium` ou `High`
`createdAt`	data-hora	Data de criação (UTC)

Status da conta

Status	Significado
`Pending`	Em abertura, ainda não pode operar
`Active`	Ativa
`Blocked`	Bloqueada temporariamente
`Closed`	Encerrada

Listar contas

GET /v1/accounts

Lista as contas do parceiro, das mais recentes para as mais antigas.

Parâmetros de query (todos opcionais)

Parâmetro	Descrição
`Status`	`Pending`, `Active`, `Blocked` ou `Closed`
`Name`	Parte do nome, da razão social ou do nome fantasia
`Document`	Parte do CPF/CNPJ. Pontuação é ignorada (`123.456` equivale a `123456`)
`CreatedFrom`	Criadas a partir desta data, inclusive (`yyyy-MM-dd`)
`CreatedTo`	Criadas até esta data, inclusive (`yyyy-MM-dd`)
`Page`	Página (padrão 1)
`PageSize`	Itens por página (padrão 50, máximo 200)

Exemplo

Resposta 200

{
  "items": [
    {
      "id": "8d1e4f2a-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
      "type": "PJ",
      "status": "Active",
      "document": "12345678000190",
      "name": "Loja Exemplo Ltda",
      "tradingName": "Loja Exemplo",
      "accountNumber": "1234567",
      "accountBranch": "0001",
      "riskLevel": "Low",
      "createdAt": "2026-03-14T13:22:05.123Z"
    },
    {
      "id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
      "type": "PF",
      "status": "Pending",
      "document": "12345678909",
      "name": "Maria da Silva",
      "tradingName": null,
      "accountNumber": null,
      "accountBranch": null,
      "riskLevel": "Medium",
      "createdAt": "2026-09-02T18:40:11.004Z"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 2
}

Consultar conta

GET /v1/accounts/{id}

Devolve uma conta do parceiro pelo id.

Exemplo

Resposta 200

{
  "id": "8d1e4f2a-3b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "PJ",
  "status": "Active",
  "document": "12345678000190",
  "name": "Loja Exemplo Ltda",
  "tradingName": "Loja Exemplo",
  "accountNumber": "1234567",
  "accountBranch": "0001",
  "riskLevel": "Low",
  "createdAt": "2026-03-14T13:22:05.123Z"
}

Erros

Status	`detail`	Quando
`404`	`Account not found`	A conta não existe ou pertence a outro parceiro

Onboarding

O onboarding é o cadastro do seu cliente final para abertura de conta. Você gera um link de onboarding e o envia ao cliente; ele abre o link, preenche os dados e envia os documentos. Após a aprovação, a conta aparece em GET /v1/accounts.

O link e o fluxo de cadastro usam a marca e os termos configurados para o seu parceiro no Painel.

Objeto onboarding

Campo	Tipo	Descrição
`id`	uuid	Identificador do onboarding
`kycOnboardingLinkId`	uuid	Mesmo valor de `id` (mantido por compatibilidade)
`personTypeHint`	texto \| null	`PF` ou `PJ`, se informado na criação ou já identificado no cadastro
`status`	texto	Situação do cadastro (tabela abaixo)
`inviteCode`	texto \| null	Código de convite informado na criação
`applicantName`	texto \| null	Nome de quem está se cadastrando, quando já informado
`stepsCompleted`	número	Etapas concluídas
`stepsTotal`	número	Total de etapas do cadastro
`createdAt`	data-hora	Data de criação do link (UTC)
`expiresAt`	data-hora	Data em que o link expira (UTC)
`onboardingUrl`	texto \| null	Link que o cliente final abre. Vem preenchido apenas enquanto o link pode ser usado (`Created` ou `InProgress`)

Status do onboarding

Status	Significado
`Created`	Link criado, ainda não aberto pelo cliente
`InProgress`	Cliente está preenchendo o cadastro
`UnderReview`	Cadastro enviado, em análise pela Brasil Cash
`Completed`	Cadastro aprovado
`Rejected`	Cadastro reprovado
`Expired`	Link expirou antes da conclusão

Criar link de onboarding

POST /v1/onboards

Corpo (todos os campos são opcionais; pode-se enviar {})

Campo	Tipo	Descrição
`personTypeHint`	texto	`PF` ou `PJ`, se você já sabe o tipo de cliente
`expirationDays`	número	Validade do link em dias, de 30 a 90
`inviteCode`	texto	Código livre de até 32 caracteres, para você identificar a origem do convite

Exemplo

Resposta 201

{
  "linkToken": "Zk3pQ8vX1mN7rT2wY5bC",
  "onboard": {
    "id": "5c7e9a1b-2d4f-4e6a-8b0c-1d3e5f7a9b2c",
    "kycOnboardingLinkId": "5c7e9a1b-2d4f-4e6a-8b0c-1d3e5f7a9b2c",
    "personTypeHint": "PF",
    "status": "Created",
    "inviteCode": "CAMPANHA-OUT26",
    "applicantName": null,
    "stepsCompleted": 0,
    "stepsTotal": 0,
    "createdAt": "2026-10-19T12:00:00Z",
    "expiresAt": "2026-11-18T12:00:00Z",
    "onboardingUrl": "https://onboarding.brasilcash.com.br/o/Zk3pQ8vX1mN7rT2wY5bC"
  }
}

Envie onboard.onboardingUrl ao seu cliente. Guarde onboard.id para acompanhar o cadastro pela listagem.

linkToken é o token do link e aparece somente nesta resposta.

Erros

Status	Exemplo de mensagem	Quando
`400`	`expirationDays`: `Between 30 and 90`	`expirationDays` fora de 30 a 90
`400`	`personTypeHint`: `Must be PF or PJ`	Tipo de pessoa inválido
`400`	`inviteCode`: `Max 32 characters`	Código de convite muito longo
`409`	`O tenant de onboarding deste parceiro está inativo`	O onboarding do parceiro está desativado. Fale com a Brasil Cash
`409`	`Este parceiro ainda não tem um tenant de onboarding configurado…`	O onboarding do parceiro ainda não foi configurado. Fale com a Brasil Cash
`502`	`The Kyc API did not answer; try again`	Instabilidade temporária. Tente novamente

Listar onboardings

GET /v1/onboards

Lista os links de onboarding criados pelo parceiro, com o andamento de cada cadastro.

Parâmetros de query (todos opcionais)

Parâmetro	Descrição
`Search`	Busca por nome de quem está se cadastrando, código de convite ou documento
`Status`	`Created`, `InProgress`, `UnderReview`, `Completed`, `Rejected` ou `Expired`
`PersonType`	`PF` ou `PJ`
`CreatedFrom`	Criados a partir desta data, inclusive (`yyyy-MM-dd`)
`CreatedTo`	Criados até esta data, inclusive (`yyyy-MM-dd`)
`Page`	Página (padrão 1)
`PageSize`	Itens por página (padrão 50, máximo 200)

Exemplo

Resposta 200

{
  "items": [
    {
      "id": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "kycOnboardingLinkId": "9e8d7c6b-5a4f-4e3d-8c2b-1a0f9e8d7c6b",
      "personTypeHint": "PJ",
      "status": "InProgress",
      "inviteCode": "PARCEIRO-2026",
      "applicantName": "Padaria Pão Quente Ltda",
      "stepsCompleted": 2,
      "stepsTotal": 5,
      "createdAt": "2026-10-01T09:15:00Z",
      "expiresAt": "2026-11-30T09:15:00Z",
      "onboardingUrl": "https://onboarding.brasilcash.com.br/o/Hq9sL2kV6pD4xW8nF1gJ"
    }
  ],
  "page": 1,
  "pageSize": 20,
  "total": 1
}

Erros

Status	Exemplo de mensagem	Quando
`400`	`status`: `One of Created, InProgress, UnderReview, Completed, Rejected, Expired`	`Status` inválido
`400`	`personType`: `Must be PF or PJ`	`PersonType` inválido
`502`	`The Kyc API did not answer; try again`	Instabilidade temporária

Credenciais da conta

Cada conta ativa pode ter uma credencial própria, usada para operar essa conta na API transacional da Brasil Cash (consulta de saldo, extrato e, quando liberado, movimentações). É você, parceiro, quem emite essa credencial em nome do seu cliente.

Criar credencial

POST /v1/account/credentials

Corpo

Campo	Tipo	Obrigatório	Descrição
`accountId`	uuid	Sim	Conta do parceiro, com status `Active`
`name`	texto	Sim	Nome para identificar a credencial (até 100 caracteres)
`allowedIps`	texto	Sim	IP(s) de onde a credencial será usada. Vários IPs separados por vírgula. Sem máscara/CIDR

Exemplo

Resposta 201

{
  "id": "7b9d1f3a-5c7e-4a9b-8d1f-3a5c7e9b1d3f",
  "name": "Gateway - Cliente X",
  "clientId": "bc_pub_A7kP2mX9qL4vN8rT1wY3",
  "clientSecret": "bc_sec_Q2w8E4r6T1y3U5i7O9p0A2s4D6f8G1h3J5k7L9z0",
  "username": "bc_usr_k3m9p2x7",
  "password": "Rk7#mQ2v@Xn9pL4w",
  "permissions": ["statement", "balance"],
  "selfApprove": false,
  "allowedIps": "203.0.113.10, 203.0.113.11",
  "status": "PendingReview"
}

Campo	Descrição
`clientId`	Identificador público da credencial
`clientSecret`	Segredo da credencial. Exibido somente nesta resposta
`username`	Usuário gerado para a conta
`password`	Senha gerada. Exibida somente nesta resposta
`permissions`	Permissões da credencial. Toda credencial nasce com `statement` (extrato) e `balance` (saldo)
`selfApprove`	Se as operações dispensam aprovação. Sempre `false` na criação
`allowedIps`	IPs autorizados, normalizados
`status`	`PendingReview`: a credencial passa por análise da Brasil Cash antes de ser liberada

Importante: guarde clientSecret e password com segurança assim que recebê-los. A Brasil Cash não armazena esses valores em texto e não consegue reenviá-los. Em caso de perda, revogue a credencial pelo Painel e crie outra.

Permissões de movimentação (além de saldo e extrato) são liberadas pela Brasil Cash; não é possível pedi-las nesta chamada.

Erros

Status	Exemplo de mensagem	Quando
`400`	`name`: `Required, max 100 characters`	Nome ausente ou longo demais
`400`	`allowedIps`: `Informe o IP que a sua API vai usar`	`allowedIps` ausente
`400`	`allowedIps`: `'10.0.0.0/24' não é um IP válido (informe só IPs, sem máscara)`	Item que não é um IP
`404`	`Account not found`	A conta não existe ou pertence a outro parceiro
`409`	`Account is not active`	A conta não está com status `Active`
`409`	`Account already has an active credential; revoke it before creating another`	A conta já tem uma credencial. Revogue a atual pelo Painel

Fluxo típico de integração

Obtenha a chave de API no Painel (ou com a Brasil Cash), cadastre os IPs do seu servidor e aguarde a aprovação.

Gere um link de onboarding com POST /v1/onboards e envie o onboardingUrl ao seu cliente.

Acompanhe o cadastro com GET /v1/onboards, filtrando por Status ou buscando pelo inviteCode.

Quando o onboarding chegar a Completed, localize a conta em GET /v1/accounts (por exemplo, filtrando por Document) e aguarde o status Active.

Emita a credencial da conta com POST /v1/account/credentials e guarde clientSecret e password com segurança.

BrasilCash BaaS — API do Parceiro (v1)

Visão geral#

Autenticação#

Como obter a chave#

Quando a chave é recusada#

Convenções#

Paginação#

Erros#

Limite de requisições#

Contas#

Objeto conta#

Listar contas#

Consultar conta#

Onboarding#

Objeto onboarding#

Criar link de onboarding#

Listar onboardings#

Credenciais da conta#

Criar credencial#

Fluxo típico de integração#

Visão geral

Autenticação

Como obter a chave

Quando a chave é recusada

Convenções

Paginação

Erros

Limite de requisições

Contas

Objeto conta

Listar contas

Consultar conta

Onboarding

Objeto onboarding

Criar link de onboarding

Listar onboardings

Credenciais da conta

Criar credencial

Fluxo típico de integração