Skip to main content
API docs by Redocly

API de Contas

Download OpenAPI specification:Download

A API de Contas da ONZ foi criada para integrar sistemas corporativos a serviços financeiros, com foco em gestão de contas, pagamentos, movimentações financeiras e notificações operacionais. Por meio desta API REST, sua aplicação pode consultar saldos e extratos, iniciar pagamentos, acompanhar transações, configurar webhooks e operar fluxos financeiros de forma segura, rastreável e escalável.

Esta documentação descreve os recursos disponíveis, os parâmetros obrigatórios e opcionais, os cabeçalhos necessários, os formatos esperados e os exemplos de resposta para cenários de sucesso e erro.

Objetivo da API

O objetivo desta API é oferecer uma interface padronizada para que empresas acessem recursos bancários diretamente, sem depender de processos manuais. Ela permite automatizar operações como Pix, TED, transferências internas, pagamentos de boletos, consulta de saldo, conciliação de extratos e recebimento de notificações por webhook.

O que cada grupo de endpoints representa

  • Autenticação: emissão de tokens OAuth 2.0 para acesso seguro aos recursos da API.
  • Contas: consulta de saldo, extrato transacional e extratos consolidados por período.
  • Contas BaaS: listagem e consulta das contas filhas criadas dentro de um BaaS.
  • Onboardings BaaS: criação, envio de documentos e acompanhamento dos processos de abertura de conta vinculados ao BaaS.
  • Credenciais BaaS: geração de credenciais de API (Contas e QR Codes/Pix) para contas filhas do BaaS.
  • Pix: criação, consulta e devolução de pagamentos Pix por chave, QR Code ou dados bancários.
  • Boletos: consulta, pagamento e acompanhamento de pagamentos de boletos.
  • TED: criação e consulta de transferências TED para outras instituições.
  • Transferências internas: criação e consulta de transferências entre contas da mesma instituição.
  • Infrações: consulta e resposta a contestações relacionadas a operações Pix.
  • Webhooks: cadastro de URLs para receber notificações assíncronas sobre eventos financeiros.

Credenciamento para uso da API

Antes de iniciar a integração:
  1. Solicite a habilitação da conta que será usada na integração;
  2. Crie as credenciais de API no ambiente administrativo pelo menu "Configurações" -> "API Contas" -> "Nova credencial";
  3. Para operar múltiplas contas de um BaaS, crie credenciais pelo menu "Configurações" -> "API BaaS" -> "Nova credencial BaaS";
  4. Solicite o certificado digital de integração.

Credenciais BaaS e seleção da conta alvo

Credenciais BaaS possuem `clientId` com prefixo `baas_` e são emitidas pela conta dona do BaaS. Elas permitem consultar recursos do BaaS e operar contas filhas vinculadas a esse BaaS.

Para endpoints operacionais de conta, como saldos, transações, Pix, TED, boletos, transferências internas, infrações e webhooks, envie o cabeçalho x-account-id com o identificador interno da conta filha que será operada. O cabeçalho é obrigatório apenas para tokens emitidos por credenciais BaaS. Tokens de credenciais de conta continuam operando a própria conta da credencial.

Endpoints de escopo BaaS, como GET /accounts, GET /accounts/{id}, POST /onboarding, POST /onboarding/{id}/images, GET /onboardings e GET /onboardings/{id}, não exigem x-account-id.

Autenticação

Esta seção descreve como obter tokens de acesso OAuth 2.0 para autenticar chamadas corporativas. Cada requisição aos recursos protegidos deve enviar um token válido no cabeçalho Authorization.

Obter token de acesso.

O primeiro passo para utilizar a API corporativa é a autenticação. Nesta etapa, o servidor de autorização valida as credenciais do cliente e emite um token de acesso.

A API utiliza tokens Bearer do OAuth 2.0. Toda requisição a recursos protegidos deve incluir o token no cabeçalho HTTP Authorization. Após obter o token, sua aplicação pode acessar os endpoints compatíveis com os escopos concedidos.

Escopos
Os escopos definem quais recursos bancários poderão ser acessados pelo token.

Recurso Escopo de leitura Escopo de escrita Acessível via
Pix pix.read pix.write Token corporativo
Boletos billets.read billets.write Token corporativo
Webhook webhook.read webhook.write Token corporativo
Transações transactions.read Token corporativo
Conta account.read Token corporativo
Infrações infractions.read infractions.write Token corporativo
Transferências internas internal-transfer.read internal-transfer.write Token corporativo
TED ted.read ted.write Token corporativo
Contas BaaS baas.accounts.read Credencial BaaS
Onboardings BaaS baas.onboarding.read baas.onboarding.write Credencial BaaS
Credenciais BaaS baas.credentials.write Credencial BaaS
Request Body schema:
required
clientId
required
string

Identificador da credencial. Credenciais BaaS usam prefixo baas_.

clientSecret
required
string
grantType
required
string
Default: "client_credentials"
scope
string

Responses

Request samples

Content type
{
  • "clientId": "string",
  • "clientSecret": "string",
  • "grantType": "client_credentials",
  • "scope": "string"
}

Response samples

Content type
application/json
{
  • "tokenType": "string",
  • "expiresAt": 0,
  • "refreshExpiresIn": 0,
  • "notBeforePolicy": 0,
  • "accessToken": "string",
  • "scope": "string"
}

Contas

Os endpoints de contas permitem consultar saldo, listar transações, obter detalhes de movimentações e gerar extratos consolidados para apoiar conciliação, auditoria e acompanhamento financeiro.

Listar contas do BaaS.

Lista as contas filhas pertencentes ao BaaS da credencial autenticada. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

A conta dona do BaaS não é retornada nesta listagem.

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1

Número da página para paginação.

perPage
integer [ 1 .. 100 ]
Default: 20

Quantidade máxima de itens por página.

status
integer

Status interno da conta.

type
string

Tipo da conta.

document
string

Documento do titular da conta.

accountNumber
integer

Número da conta.

createdAtStart
string <date-time>

Data inicial de criação da conta (ISO 8601).

createdAtEnd
string <date-time>

Data final de criação da conta (ISO 8601).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar conta do BaaS.

Retorna os dados públicos de uma conta filha do BaaS da credencial autenticada. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

Authorizations:
OAuth2
path Parameters
id
required
integer <int64>

Identificador interno da conta filha.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar transações da conta.

Authorizations:
OAuth2
query Parameters
event_date_start
required
string <date-time>

Data inicial do período de consulta (ISO 8601).

event_date_end
required
string <date-time>

Data final do período de consulta (ISO 8601).

page_offset
integer >= 0
Default: 0

Posição inicial da paginação.

page_limit
integer [ 1 .. 100 ]
Default: 10

Quantidade máxima de itens por página.

sort_by
string
Default: "EVENT_DATE"
Enum: "EVENT_DATE" "AMOUNT"

Campo utilizado para ordenar os dados.

sort_order
string
Default: "ASC"
Enum: "ASC" "DESC"

Direção da ordenação.

filter
string

Filtra transações pelo documento do pagador ou recebedor.

header Parameters
x-account-id
integer <int64>

Identificador interno da conta filha que será operada. Obrigatório quando o token foi emitido por uma credencial BaaS (clientId com prefixo baas_) em endpoints operacionais de conta. Não é necessário para credenciais de conta comuns nem para endpoints de escopo BaaS.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar detalhes de uma transação.

Authorizations:
OAuth2
path Parameters
transactionId
required
number

ID da transação.

header Parameters
x-account-id
integer <int64>

Identificador interno da conta filha que será operada. Obrigatório quando o token foi emitido por uma credencial BaaS (clientId com prefixo baas_) em endpoints operacionais de conta. Não é necessário para credenciais de conta comuns nem para endpoints de escopo BaaS.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Consultar saldo da conta.

Authorizations:
OAuth2
header Parameters
x-account-id
integer <int64>

Identificador interno da conta filha que será operada. Obrigatório quando o token foi emitido por uma credencial BaaS (clientId com prefixo baas_) em endpoints operacionais de conta. Não é necessário para credenciais de conta comuns nem para endpoints de escopo BaaS.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Consultar extrato consolidado da conta.

Este endpoint retorna dados consolidados de extrato com base no período e no agrupamento informados. Validações aplicadas:

  • O período máximo permitido é de 12 meses quando agrupado por MONTH.
  • O período máximo permitido é de 60 dias quando agrupado por DAY.
  • O mês final não pode ser posterior ao mês atual quando agrupado por MONTH.
  • A data final deve ser anterior à data atual quando agrupada por DAY.
Authorizations:
OAuth2
header Parameters
x-account-id
integer <int64>

Identificador interno da conta filha que será operada. Obrigatório quando o token foi emitido por uma credencial BaaS (clientId com prefixo baas_) em endpoints operacionais de conta. Não é necessário para credenciais de conta comuns nem para endpoints de escopo BaaS.

Request Body schema: application/json
required
One of
groupBy
required
any
Value: "DAY"
initialDate
required
string <date>

Formato: YYYY-MM-DD

finalDate
required
string <date>

Formato: YYYY-MM-DD

Responses

Request samples

Content type
application/json
Example
{
  • "groupBy": "DAY",
  • "initialDate": "2025-05-01",
  • "finalDate": "2025-05-03"
}

Response samples

Content type
application/json
Example
{
  • "data": [
    ]
}

Consultar extrato consolidado por hora.

Este endpoint retorna dados consolidados de extrato agrupados por hora para uma data específica. A data informada não pode ser posterior à data atual.

Authorizations:
OAuth2
header Parameters
x-account-id
integer <int64>

Identificador interno da conta filha que será operada. Obrigatório quando o token foi emitido por uma credencial BaaS (clientId com prefixo baas_) em endpoints operacionais de conta. Não é necessário para credenciais de conta comuns nem para endpoints de escopo BaaS.

Request Body schema: application/json
required
date
required
string <date>

Formato: YYYY-MM-DD

Responses

Request samples

Content type
application/json
{
  • "date": "2025-05-01"
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Onboardings

Os endpoints de onboardings permitem criar processos de abertura de conta, enviar documentos de identificação e acompanhar o status no contexto de uma credencial BaaS.

Criar onboarding no BaaS.

Cria um novo processo de abertura de conta vinculado ao BaaS da credencial autenticada. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

O onboarding é criado com status Aguardando aprovação (1). A análise e aprovação são realizadas pelo time operacional da instituição.

A funcionalidade depende da preferência ENABLE_ONBOARDING_API_ENDPOINT estar habilitada no ambiente.

Authorizations:
OAuth2
Request Body schema: application/json
required
One of
accountType
string
Default: "NATURAL_PERSON"
Value: "NATURAL_PERSON"
required
object (BaasOnboardingPersonInput)

Responses

Request samples

Content type
application/json
Example
{
  • "accountType": "NATURAL_PERSON",
  • "person": {
    }
}

Response samples

Content type
application/json
{
  • "message": "Onboarding created successfully",
  • "id": "4fdd34d2-e9fa-4bb5-bfeb-84281f77f19a",
  • "status": 1
}

Enviar imagem do onboarding.

Envia documentos de identificação e selfie para um onboarding previamente criado. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

Tipos aceitos:

  • FRONT: frente do documento
  • BACK: verso do documento
  • SELFIE: selfie do titular

O upload só é permitido enquanto o onboarding estiver com status Pendente (0) ou Aguardando aprovação (1). Arquivos devem estar em JPG ou PNG, com tamanho máximo de 10 MB.

A funcionalidade depende da preferência ENABLE_ONBOARDING_API_ENDPOINT estar habilitada no ambiente.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Identificador do onboarding.

Request Body schema: multipart/form-data
required
type
required
string
Enum: "FRONT" "BACK" "SELFIE"

Tipo da imagem enviada.

file
required
string <binary>

Arquivo de imagem (JPG ou PNG, máximo 10 MB).

Responses

Request samples

Content type
multipart/form-data
Example
{
  "type": "FRONT",
  "file": "(binary)"
}

Response samples

Content type
application/json
{}

Listar onboardings do BaaS.

Lista os processos de abertura de conta vinculados ao BaaS da credencial autenticada. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1

Número da página para paginação.

perPage
integer [ 1 .. 100 ]
Default: 20

Quantidade máxima de itens por página.

status
integer
Enum: 0 1 2 3 4

Status do onboarding. Onboardings removidos não são retornados.

accountType
string
Enum: "NATURAL_PERSON" "LEGAL_PERSON" "SALARY_ACCOUNT"

Tipo de conta solicitada no onboarding.

document
string

Documento da pessoa ou empresa informada no onboarding.

createdAtStart
string <date-time>

Data inicial de criação do onboarding (ISO 8601).

createdAtEnd
string <date-time>

Data final de criação do onboarding (ISO 8601).

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar onboarding do BaaS.

Retorna os dados públicos de um processo de onboarding vinculado ao BaaS da credencial autenticada. Este endpoint é exclusivo para credenciais BaaS e não exige o cabeçalho x-account-id.

Authorizations:
OAuth2
path Parameters
id
required
string <uuid>

Identificador do onboarding.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Credenciais

Os endpoints de credenciais permitem que a conta dona do BaaS gere credenciais de API (API de Contas e API de QR Codes/Pix) para suas contas filhas. São exclusivos para credenciais BaaS e não exigem o cabeçalho x-account-id.

Gerar credencial da API de Contas para conta filha.

Gera uma nova credencial da API de Contas (clientId e clientSecret) para uma conta filha do BaaS da credencial autenticada.

Este endpoint é exclusivo para credenciais BaaS, não exige o cabeçalho x-account-id e não pode ser utilizado para a própria conta dona do BaaS. A conta filha precisa estar ativa e habilitada para a API de Contas.

O clientSecret é retornado apenas no momento da criação e não pode ser recuperado posteriormente. Cada conta filha pode ter no máximo 10 credenciais ativas da API de Contas.

Authorizations:
OAuth2
path Parameters
accountId
required
integer <int64>

Identificador interno da conta filha.

Request Body schema: application/json
required
description
required
string

Descrição da credencial, para identificação.

allowedIps
required
Array of strings

Lista de IPs autorizados a utilizar a credencial. Aceita endereços IPv4 (ex.: 200.150.100.50) ou faixas em notação CIDR (ex.: 200.150.100.0/24). Pode ser enviada vazia, mas recomenda-se restringir os IPs de origem.

scopes
required
Array of strings
Items Enum: "pix.read" "pix.write" "pix.create" "account.read" "transactions.read" "webhook.read" "webhook.write" "billets.read" "billets.write" "billets.create" "internal-transfer.read" "internal-transfer.write" "internal-transfer.create" "ted.read" "ted.write" "ted.create" "infractions.read" "infractions.write"

Escopos concedidos à credencial. Definem quais recursos a credencial poderá acessar.

Responses

Request samples

Content type
application/json
{
  • "description": "Integração ERP",
  • "allowedIps": [
    ],
  • "scopes": [
    ]
}

Response samples

Content type
application/json
{
  • "clientId": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "clientSecret": "1b9d6bcd-bbfd-4b2d-9b5d-ab8dfbbd4bed",
  • "id": 1234,
  • "description": "Integração ERP",
  • "allowedIps": [
    ]
}

Gerar credencial da API de QR Codes (Pix) para conta filha.

Gera uma nova credencial da API de QR Codes/Pix (clientId e clientSecret) para uma conta filha do BaaS da credencial autenticada e garante que a conta possua uma chave Pix aleatória (EVP) para recebimentos.

Este endpoint é exclusivo para credenciais BaaS, não exige o cabeçalho x-account-id e não pode ser utilizado para a própria conta dona do BaaS. A conta filha precisa estar ativa e habilitada para a API de QR Codes.

O clientSecret é retornado apenas no momento da criação e não pode ser recuperado posteriormente.

Authorizations:
OAuth2
path Parameters
accountId
required
integer <int64>

Identificador interno da conta filha.

Responses

Response samples

Content type
application/json
{
  • "clientId": "000100012345678901234567890",
  • "clientSecret": "Yjg2N2I5ZjNjMDhmNGZhOWE2ZGM0",
  • "pixKey": "e1f2a3b4-c5d6-7890-abcd-ef1234567890",
  • "pixKeyCreated": true
}

Pix

Os endpoints Pix permitem iniciar pagamentos instantâneos, consultar transações, validar QR Codes, consultar chaves Pix e solicitar devoluções. As operações podem ser feitas por chave Pix, QR Code copia e cola ou dados bancários do favorecido.

Sobre chaves Pix

A chave Pix é uma forma simples de identificar o recebedor de uma transferência. Com ela, não é necessário informar agência, conta e demais dados bancários do destinatário. Uma mesma pessoa ou empresa pode possuir mais de uma chave.
Tipo de chave Pix Descrição Validação de formato
CPF Documento de pessoa física ^[0-9]{11}$
CNPJ Documento de pessoa jurídica ^[0-9]{14}$
Telefone Número de telefone ^+[1-9][0-9]\d{1,14}$
E-mail Endereço de e-mail ^[a-z0-9.!#$&'*+\\\\/=?^_`{|}~-]+@[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)*$
EVP (chave aleatória) Chave aleatória gerada pelo Banco Central do Brasil [0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$

QR Code Pix (copia e cola)

Também é possível pagar usando o código conhecido como "copia e cola", padronizado pelo Banco Central do Brasil e representável por QR Code.

Dados bancários do favorecido

Como terceira opção, o pagamento pode ser iniciado informando diretamente os dados bancários do recebedor.

Iniciar pagamento Pix por QR Code.

Permite solicitar um pagamento Pix usando os dados do QR Code no padrão do Banco Central do Brasil. Esse conteúdo também é conhecido como copia e cola.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
qrCode
required
string
creditorDocument
string
priority
string
Enum: "HIGH" "NORM"

Quando definido como HIGH, o pagamento é processado imediatamente, sem passar pela fila. O valor HIGH só é permitido quando creditorDocument for informado.

description
string
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
expiration
integer <int64> (PixCashOutExpiration) [ 1 .. 10800 ]

Tempo máximo, em segundos, que a operação pode permanecer na fila aguardando processamento antes de ser cancelada.

required
object
ispbDeny
Array of strings (IspbDenyList)

Lista de códigos ISPB (Identificador de Sistema de Pagamentos Brasileiro) para os quais o pagamento não será permitido.

Responses

Request samples

Content type
application/json
{
  • "qrCode": "string",
  • "creditorDocument": "string",
  • "priority": "HIGH",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "expiration": 600,
  • "payment": {
    },
  • "ispbDeny": [
    ]
}

Response samples

Content type
application/json
{
  • "endToEndId": "string",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "payment": {
    },
  • "type": "string"
}

Iniciar pagamento Pix por dados bancários.

Permite solicitar um pagamento Pix usando os dados bancários do credor: ISPB, documento, agência, número da conta, tipo de conta e nome.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
priority
string
Enum: "HIGH" "NORM"

Quando definido como HIGH, o pagamento é processado imediatamente, sem passar pela fila. O valor HIGH só é permitido quando creditorDocument for informado.

description
string
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
expiration
integer <int64> (PixCashOutExpiration) [ 1 .. 10800 ]

Tempo máximo, em segundos, que a operação pode permanecer na fila aguardando processamento antes de ser cancelada.

required
object (CreditorData)
required
object
ispbDeny
Array of strings (IspbDenyList)

Lista de códigos ISPB (Identificador de Sistema de Pagamentos Brasileiro) para os quais o pagamento não será permitido.

Responses

Request samples

Content type
application/json
{
  • "priority": "HIGH",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "expiration": 600,
  • "creditorAccount": {
    },
  • "payment": {
    },
  • "ispbDeny": [
    ]
}

Response samples

Content type
application/json
{
  • "endToEndId": "string",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "payment": {
    },
  • "type": "string"
}

Iniciar pagamento Pix por chave Pix.

Permite solicitar um pagamento Pix usando uma chave Pix aceita: CPF, CNPJ, e-mail, telefone ou EVP (chave aleatória).

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
pixKey
required
string

Chave Pix aceita: CPF, CNPJ, e-mail, telefone ou EVP (chave aleatória).

creditorDocument
string
endToEndId
string

Identificador único obtido através da consulta de chave PIX. Este parâmetro é opcional e deve ser utilizado para garantir a baixa correta do saldo da ficha de consultas de chave PIX.

priority
string
Enum: "HIGH" "NORM"

Quando definido como HIGH, o pagamento é processado imediatamente, sem passar pela fila. O valor HIGH só é permitido quando creditorDocument for informado.

description
string
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
expiration
integer <int64> (PixCashOutExpiration) [ 1 .. 10800 ]

Tempo máximo, em segundos, que a operação pode permanecer na fila aguardando processamento antes de ser cancelada.

required
object
ispbDeny
Array of strings (IspbDenyList)

Lista de códigos ISPB (Identificador de Sistema de Pagamentos Brasileiro) para os quais o pagamento não será permitido.

Responses

Request samples

Content type
application/json
{
  • "pixKey": "string",
  • "creditorDocument": "string",
  • "endToEndId": "string",
  • "priority": "HIGH",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "expiration": 600,
  • "payment": {
    },
  • "ispbDeny": [
    ]
}

Response samples

Content type
application/json
{
  • "endToEndId": "string",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "id": 0,
  • "payment": {
    },
  • "type": "string"
}

Consultar Pix por end-to-end-id.

Authorizations:
OAuth2
path Parameters
endToEndId
required
string

EndToEndId do Pix.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Devolver um Pix recebido.

Cria uma devolução para um Pix recebido identificado pelo end-to-end-id.

Authorizations:
OAuth2
path Parameters
endToEndId
required
string

EndToEndId do Pix recebido que será devolvido.

header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
devolutionAmount
required
number <double> >= 0.01
devolutionReason
string

Responses

Request samples

Content type
application/json
{
  • "devolutionAmount": 0.01,
  • "devolutionReason": "string"
}

Response samples

Content type
application/json
{
  • "devolutionEndToEndId": "string",
  • "devolutionAmount": 0.1
}

Consultar Pix por chave de idempotência.

Authorizations:
OAuth2
path Parameters
idempotencyKey
required
string[a-zA-Z0-9]{1,50}

Chave de idempotência do Pix.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar dados de uma chave Pix.

Consulta os dados DICT associados a uma chave Pix.

Authorizations:
OAuth2
path Parameters
key
required
string

Chave Pix a ser consultada.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "tradeName": "string",
  • "keyType": "CPF",
  • "key": "string",
  • "document": "string",
  • "ispb": "string",
  • "ispb_reduced_name": "string",
  • "endToEndId": "string"
}

Obter comprovante Pix em PDF.

Retorna o comprovante do pagamento em PDF codificado em base64.

Authorizations:
OAuth2
path Parameters
endToEndId
required
string

EndToEndId do Pix.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar informações de QR Code Pix copia e cola

Permite enviar o código Pix copia e cola para consultar os detalhes do QR Code. A resposta varia conforme o tipo do QR Code: estático, dinâmico imediato ou dinâmico com vencimento.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
qrCode
required
string

Valor copia e cola do QR Code.

Responses

Request samples

Content type
application/json
{
  • "qrCode": "string"
}

Response samples

Content type
application/json
Example
{
  • "type": "static",
  • "merchantCategoryCode": "0000",
  • "transactionCurrency": "986",
  • "countryCode": "BR",
  • "merchantName": "FRANCISCO DA SILVA",
  • "merchantCity": "RECIFE",
  • "transactionAmount": 10,
  • "txid": "3252890112011017889597792",
  • "chave": "5f84a4c5-c5cb-4599-9f13-7eb4d419dacc",
  • "payload": { },
  • "endToEndId": "E082535392025020714090799201365d",
  • "statusCode": 200
}

Boletos

Os endpoints de boletos permitem consultar informações do título, iniciar o pagamento, listar pagamentos realizados e acompanhar o detalhe de cada operação.

Iniciar pagamento de boleto pela linha digitável.

Permite solicitar o pagamento de um boleto usando a linha digitável.
1 - O pagamento sempre considera o valor atualizado do boleto, incluindo juros e multas quando aplicáveis.
2 - Boletos cujo valor pode ser alterado pelo pagador devem ser pagos por um canal administrativo autorizado.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
digitableCode
required
string

Representação numérica do código de barras do boleto (linha digitável). Informe apenas números.

description
required
string
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
object

Responses

Request samples

Content type
application/json
{
  • "digitableCode": "string",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "payment": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "idempotencyKey": "string",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "digitableCode": "string",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "status": "CANCELED",
  • "transactionType": "PIX",
  • "creditDebitType": "CREDIT",
  • "payment": {
    }
}

Iniciar pagamento de boleto pelo código do boleto.

Permite pagar um boleto previamente consultado usando billetCode.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
billetCode
required
string <= 50 characters

Representação numérica da linha digitável ou do código de barras do boleto. Informe apenas números.

description
required
string
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
object

Responses

Request samples

Content type
application/json
{
  • "billetCode": "string",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "payment": {
    }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "idempotencyKey": "string",
  • "eventDate": "2019-08-24T14:15:22Z",
  • "digitableCode": "string",
  • "description": "string",
  • "paymentFlow": "INSTANT",
  • "status": "CANCELED",
  • "transactionType": "PIX",
  • "creditDebitType": "CREDIT",
  • "payment": {
    }
}

Consultar informações de um boleto.

Consulta dados de um boleto pela linha digitável ou código de barras antes do pagamento.

Authorizations:
OAuth2
Request Body schema: application/json
required
billetCode
required
string <= 50 characters

Representação numérica da linha digitável ou do código de barras do boleto. Informe apenas números.

Responses

Request samples

Content type
application/json
{
  • "billetCode": "string"
}

Response samples

Content type
application/json
{
  • "paymentId": 0,
  • "payDueDate": "2019-08-24T14:15:22Z",
  • "dueDateRegister": "2019-08-24T14:15:22Z",
  • "digitableCode": "string",
  • "maxValue": 0.1,
  • "minValue": 0.1,
  • "originalValue": 0.1,
  • "discountValue": 0.1,
  • "interestValueCalculated": 0.1,
  • "totalUpdated": 0.1,
  • "recipient": "string",
  • "documentRecipient": "string",
  • "allowChangeValue": true
}

Listar pagamentos de boletos.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar detalhes do pagamento de boleto por ID.

Authorizations:
OAuth2
path Parameters
id
required
string

ID do boleto.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar pagamento de boleto por ID.

Authorizations:
OAuth2
path Parameters
id
required
string

ID do boleto.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Obter comprovante de pagamento de boleto em PDF.

Retorna o comprovante do pagamento em PDF codificado em base64.

Authorizations:
OAuth2
path Parameters
id
required
string

ID do pagamento do boleto.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Infrações

Infrações são mecanismos de contestação de operações Pix, geralmente relacionadas a suspeita de fraude. Estes endpoints permitem consultar casos e enviar defesas quando aplicável.

Listar infrações abertas contra a conta.

Authorizations:
OAuth2
query Parameters
last_change_start
required
string <date-time>

Data inicial do período de consulta (ISO 8601).

last_change_end
required
string <date-time>

Data final do período de consulta (ISO 8601).

page_offset
integer >= 0
Default: 0

Posição inicial da paginação.

page_limit
integer [ 1 .. 100 ]
Default: 10

Quantidade máxima de itens por página.

sort_by
string
Default: "EVENT_DATE"
Enum: "EVENT_DATE" "STATUS"

Campo utilizado para ordenar os dados.

status
string
Default: "ALL"
Enum: "ACKNOWLEDGED" "WAITING_ADJUSTMENTS" "DEFENDED" "CLOSED"

Status atual da infração.

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar infração por ID.

Authorizations:
OAuth2
path Parameters
infractionId
required
string

ID da infração.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Enviar defesa para uma infração.

Authorizations:
OAuth2
path Parameters
infractionId
required
string

ID da infração.

Request Body schema: multipart/form-data
required
defense
string
files
Array of strings <binary> [ items <binary > ]

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Webhooks

Utilize webhooks para receber notificações sobre eventos da API assim que eles ocorrerem, como liquidação de Pix, recebimentos, devoluções, falhas em operações de saída e abertura de infrações. Quando um evento assinado acontece, a ONZ envia uma notificação HTTP para a URL configurada no seu ambiente.


Comportamento em caso de falhas recorrentes

Quantidade de falhas Ação
1 a 5 falhas As mensagens enfileiradas serão reenviadas após 2 minutos
6 a 10 falhas As mensagens enfileiradas serão reenviadas em intervalos de 15 minutos
11 a 15 falhas As mensagens enfileiradas serão reenviadas em intervalos de 60 minutos
Mais de 15 falhas O processamento do webhook será desativado

Listar webhooks cadastrados.

Authorizations:
OAuth2

Responses

Response samples

Content type
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

Consultar webhook.

Authorizations:
OAuth2
path Parameters
webhookId
required
string <uuid>

ID do webhook.

Responses

Response samples

Content type
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "type": "TRANSFER",
  • "uri": "http://example.com",
  • "enabled": true
}

Remover um webhook.

Cancela e remove o webhook do processamento. Novas notificações relacionadas a esse webhook serão ignoradas e descartadas.

Authorizations:
OAuth2
path Parameters
webhookId
required
string <uuid>

ID do webhook.

Responses

Response samples

Content type
application/json
{
  • "type": "string",
  • "title": "string",
  • "detail": "string",
  • "instance": "string"
}

Criar webhook para operações de transferência.

Este webhook é acionado quando uma operação de saída é liquidada ou cancelada.

Authorizations:
OAuth2
Request Body schema: application/json
required
uri
required
string <uri>
email
string

E-mail utilizado para realizar as notificações de erros de envio de webhooks

method
string
Default: "POST"
Enum: "POST" "GET" "PUT"
enabled
required
boolean
Default: true
pauseOnFail
boolean
Default: true
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uri": "http://example.com",
  • "email": "string",
  • "method": "POST",
  • "enabled": true,
  • "pauseOnFail": true,
  • "headers": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: {$request.body#/uri}
Content type
application/json
{
  • "data": {
    },
  • "type": "TRANSFER"
}

Criar webhook para operações de recebimento.

Este webhook é acionado quando uma operação de entrada é liquidada.

Authorizations:
OAuth2
Request Body schema: application/json
required
uri
required
string <uri>
email
string

E-mail utilizado para realizar as notificações de erros de envio de webhooks

method
string
Default: "POST"
Enum: "POST" "GET" "PUT"
enabled
required
boolean
Default: true
pauseOnFail
boolean
Default: true
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uri": "http://example.com",
  • "email": "string",
  • "method": "POST",
  • "enabled": true,
  • "pauseOnFail": true,
  • "headers": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: {$request.body#/uri}
Content type
application/json
{
  • "data": {
    },
  • "type": "TRANSFER"
}

Criar webhook para operações de devolução.

Este webhook é acionado quando uma operação de saída é devolvida.

Authorizations:
OAuth2
Request Body schema: application/json
required
uri
required
string <uri>
email
string

E-mail utilizado para realizar as notificações de erros de envio de webhooks

method
string
Default: "POST"
Enum: "POST" "GET" "PUT"
enabled
required
boolean
Default: true
pauseOnFail
boolean
Default: true
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uri": "http://example.com",
  • "email": "string",
  • "method": "POST",
  • "enabled": true,
  • "pauseOnFail": true,
  • "headers": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: {$request.body#/uri}
Content type
application/json
{
  • "data": {
    },
  • "type": "TRANSFER"
}

Criar webhook para falhas em operações de saída.

Este webhook é acionado quando ocorre falha de validação de dados em uma operação de saída.

Authorizations:
OAuth2
Request Body schema: application/json
required
uri
required
string <uri>
email
string

E-mail utilizado para realizar as notificações de erros de envio de webhooks

method
string
Default: "POST"
Enum: "POST" "GET" "PUT"
enabled
required
boolean
Default: true
pauseOnFail
boolean
Default: true
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uri": "http://example.com",
  • "email": "string",
  • "method": "POST",
  • "enabled": true,
  • "pauseOnFail": true,
  • "headers": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: {$request.body#/uri}
Content type
application/json
{
  • "data": {
    }
}

Criar webhook para operações de infração.

Este webhook é acionado quando uma infração é aberta contra a conta do cliente.

Authorizations:
OAuth2
Request Body schema: application/json
required
uri
required
string <uri>
email
string

E-mail utilizado para realizar as notificações de erros de envio de webhooks

method
string
Default: "POST"
Enum: "POST" "GET" "PUT"
enabled
required
boolean
Default: true
pauseOnFail
boolean
Default: true
object

Responses

Callbacks

Request samples

Content type
application/json
{
  • "uri": "http://example.com",
  • "email": "string",
  • "method": "POST",
  • "enabled": true,
  • "pauseOnFail": true,
  • "headers": {
    }
}

Response samples

Content type
application/json
{}

Callback payload samples

Callback
POST: {$request.body#/uri}
Content type
application/json
{
  • "data": {
    },
  • "type": "INFRACTION"
}

Transferências Internas

Os endpoints de transferências internas permitem criar e consultar transferências entre contas da mesma instituição.

Criar transferência interna

Cria uma transferência entre contas da mesma instituição.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
required
object
required
object
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
remittanceInformation
string <= 140 characters

Descrição ou observação da transferência.

Responses

Request samples

Content type
application/json
{
  • "creditorAccount": {
    },
  • "payment": {
    },
  • "paymentFlow": "INSTANT",
  • "remittanceInformation": "Transferência para pagamento"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar transferência interna por EndToEndId

Retorna os detalhes de uma transferência interna pelo identificador único.

Authorizations:
OAuth2
path Parameters
endToEndId
required
string

Identificador único da transferência (EndToEndId).

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar transferência interna por chave de idempotência

Retorna os detalhes de uma transferência interna pela chave de idempotência.

Authorizations:
OAuth2
path Parameters
idempotencyKey
required
string[a-zA-Z0-9]{1,50}

Chave de idempotência usada na criação.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

TED

Os endpoints de TED permitem criar e consultar transferências para contas de outras instituições financeiras.

Criar uma transferência TED.

Cria uma transferência TED para uma conta em outra instituição financeira.

Authorizations:
OAuth2
header Parameters
x-idempotency-key
required
string[a-zA-Z0-9]{1,50}

Identificador único da requisição para controle de idempotência.

Request Body schema: application/json
required
required
object (CreditorData)
paymentFlow
string (PaymentFlowType)
Enum: "INSTANT" "APPROVAL_REQUIRED"

Valor padrão: INSTANT.

  • INSTANT - O pagamento será processado imediatamente.
  • APPROVAL_REQUIRED - O pagamento será processado apenas após aprovação.
required
object
remittanceInformation
string (RemittanceInformation)

Informação adicional enviada pelo pagador ao recebedor junto com o pagamento.

Responses

Request samples

Content type
application/json
{
  • "creditorAccount": {
    },
  • "paymentFlow": "INSTANT",
  • "payment": {
    },
  • "remittanceInformation": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar TED por ID.

Authorizations:
OAuth2
path Parameters
id
required
number

ID da transação TED.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Consultar TED por chave de idempotência.

Authorizations:
OAuth2
path Parameters
idempotencyKey
required
string[a-zA-Z0-9]{1,50}

Chave de idempotência usada na criação.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}