Skip to main content
API docs by Redocly

SPB (1.0.0)

Download OpenAPI specification:Download

Arquitetura do Sistema

Arquitetura do Sistema

API Gateway

API Gateway para integração com o Sistema de Pagamentos Brasileiro (SPB)

Serviço principal que atua como interface de comunicação com o Banco Central do Brasil, oferecendo:

  • Gerenciamento de Operações: Endpoints REST para criar, listar, buscar operações;
  • Comunicação com BCB: Envio e recebimento de mensagens via IBM MQ;
  • Segurança de Dados: Criptografia e descriptografia das mensagens com gerenciamento de chaves públicas/privadas;
  • Persistência Completa: Armazenamento de todas as etapas do processo com rastreamento de eventos;
  • Validação de Schemas: Validação automática de mensagens XML contra schemas XSD do BCB;
  • Idempotência: Garantia de processamento único através de chaves de idempotência;
  • Autenticação: Controle de acesso aos endpoints;
  • Autorização: Controle de acesso baseado em roles.

Long Polling Service

Serviço de Long Polling para consumo assíncrono de respostas do BCB

API que fornece interface de long polling para consumo em tempo real de mensagens provenientes do Banco Central:

  • Long Polling: Endpoint /pullNext para consumo assíncrono de respostas do SPB com conexão mantida até chegada de novas mensagens;
  • Autenticação: Controle de acesso aos endpoints.

STR Service

Serviço especializado para transações STR (Sistema de Transferência de Reservas)

Microsserviço focado no gerenciamento de transações STR com o Banco Central, fornecendo:

  • API de Transações: Endpoints REST para criar e consultar transações STR de múltiplos tipos (STR0005, STR0006, STR0007, STR0008, STR0025, STR0034, STR0037, STR0041, STR0051);
  • Controle de Limites: Gerenciamento de limites transacionais por tipo de transação e tipo de entrada (débito/crédito) com validação em tempo real;
  • Validação de Negócio: Validações condicionais avançadas baseadas em regras específicas de cada tipo de transação;
  • Integração com API: Comunicação com o serviço principal (API) para submissão e processamento de transações;
  • Gestão de Ciclo de Vida: Acompanhamento completo do status das transações (submitted, pending, settled, canceled, rejected, refunded, error);
  • Idempotência: Garantia de processamento único através de chaves de idempotência;
  • Scheduled Jobs (Cron): Processamento automatizado de tarefas agendadas para reconciliação e sincronização;
  • Autenticação: Controle de acesso aos endpoints.
📖 Sistema de Filtros de Consulta - Clique para expandir

Muitos endpoints de listagem suportam um sistema flexível de filtros de consulta que permite operações complexas de filtragem.

Estrutura do Filtro:

Cada filtro requer 3 componentes:

  • queryFilter[{index}][column] - A coluna/campo para filtrar
  • queryFilter[{index}][operation] - A operação de comparação a ser usada
  • queryFilter[{index}][value] OU queryFilter[{index}][valueArray][] - O(s) valor(es) para comparar

Operações:

Operações de Valor Único (use com o parâmetro value):

  • EQUALS: Igual a
  • NOT_EQUALS: Diferente de
  • ILIKE: Contém (use % para definir prefixo e sufixo)
  • NOT_ILIKE: Não contém (use % para definir prefixo e sufixo)
  • HIGHER: Maior que
  • LOWER: Menor que
  • AFTER_DATE: Data após a data especificada
  • BEFORE_DATE: Data antes da data especificada
  • EQUALS_DATE: Data igual à data especificada
  • AFTER_DATETIME: DataHora após a datahora especificada
  • BEFORE_DATETIME: DataHora antes da datahora especificada
  • EQUALS_DATETIME: DataHora igual à datahora especificada

Operações de Array (use com o parâmetro valueArray):

  • IN: Valor corresponde a qualquer um no array
  • NOT_IN: Valor não corresponde a nenhum no array
  • BETWEEN_DATETIME: DataHora entre dois valores (requer 2 valores em valueArray)

Exemplos:

  • Filtro único: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=active
  • Filtro de array: ?queryFilter[0][column]=type&queryFilter[0][operation]=IN&queryFilter[0][valueArray][0]=TYPE1&queryFilter[0][valueArray][1]=TYPE2
  • Múltiplos filtros: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=active&queryFilter[1][column]=type&queryFilter[1][operation]=IN&queryFilter[1][valueArray][0]=TYPE1

OAuth2

Endpoints de autenticação OAuth2

Obter token de acesso OAuth2

Obtém um token de acesso usando OAuth2 Client Credentials ou Authorization Code flow.

path Parameters
realm
required
string
Example: cloudspb

O nome do realm de autenticação

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Enum: "client_credentials" "authorization_code" "refresh_token"

Tipo de concessão OAuth2

client_id
required
string

Identificador do cliente emitido pelo servidor de autorização

client_secret
string

Segredo do cliente (obrigatório para client_credentials e authorization_code)

code
string

Código de autorização (obrigatório para concessão authorization_code)

redirect_uri
string

URI de redirecionamento (obrigatório para concessão authorization_code)

refresh_token
string

Token de atualização (obrigatório para concessão refresh_token)

scope
string

Lista de escopos separados por espaço

Responses

Response Schema: application/json
access_token
required
string

O token de acesso para usar nas requisições da API

token_type
required
string

Tipo de token (sempre "Bearer")

expires_in
required
integer

Número de segundos até o token expirar

refresh_token
string

Token de atualização (se aplicável)

scope
string

Lista de escopos concedidos separados por espaço

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "refresh_token_value",
  • "scope": "operations:write operations:read"
}

Operations

Endpoints de gerenciamento de operações

Criar uma nova operação

Cria uma nova operação com o documento XML fornecido. Este endpoint processa operações bancárias de acordo com os padrões do SPB (Sistema de Pagamentos Brasileiro).

O endpoint suporta idempotência através do cabeçalho X-Idempotency-Key e pode opcionalmente aguardar a conclusão da operação através do cabeçalho X-Response-Timeout-Seconds.

Authorizations:
OAuth2
header Parameters
X-Idempotency-Key
required
string <uuid>
Example: 550e8400-e29b-41d4-a716-446655440000

UUID v4 para garantir a idempotência da requisição

X-Recipient
string
Example: 12345679

Identificador do participante destinatário (obrigatório para alguns tipos de operação)

X-Message-Type
string
Default: Request
Enum: "Request" "Response"

Tipo de mensagem (padrão é "Request" se não fornecido)

X-Domain
string
Example: SPB01

Substituição de domínio para tipos de operação GEN

Request Body schema: application/xml
required

Documento XML contendo os detalhes da operação de acordo com os padrões do SPB

object

Responses

Response Schema: application/json
id
required
string^[0-9]{21}$

Identificador único da operação

sender
required
string

Identificador do participante remetente

recipient
required
string

Identificador do participante destinatário

domain
required
string
Enum: "SPB01" "SPB02" "MES01" "MES02" "MES03"

Domínio da operação

operation_type
required
string

Tipo de operação (ex: STR, GEN, etc.)

event_type
required
string

Tipo de evento principal para a operação

status
required
string
Enum: "request_processing" "response_processing" "request_pending" "response_pending" "request_awaiting" "response_awaiting" "successful" "failed" "canceled"

Status atual da operação

created_at
required
string <date-time>

Registro de data/hora quando a operação foi criada

Array of objects (Event)

List of events associated with this operation

Request samples

Content type
application/xml
<GEN0001>
  <CodMsg>GEN0001</CodMsg>
  <ISPBEmissor>12345678</ISPBEmissor>
  <ISPBDestinatario>12345679</ISPBDestinatario>
  <MsgECO>ONZ</MsgECO>
</GEN0001>

Response samples

Content type
application/json
{
  • "id": "12345678202510206585020",
  • "sender": "12345678",
  • "recipient": "12345679",
  • "domain": "SPB01",
  • "operation_type": "GEN",
  • "event_type": "GEN0001",
  • "status": "request_processing",
  • "created_at": "2025-10-20T12:08:46.656-03:00",
  • "events": [
    ]
}

Listar operações com paginação

Recupera uma lista paginada de operações. Suporta filtragem e ordenação.

Exemplos de filtros:

  • Filtro único: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=successful
  • Filtro de array: ?queryFilter[0][column]=operation_type&queryFilter[0][operation]=IN&queryFilter[0][valueArray][0]=STR&queryFilter[0][valueArray][1]=GEN
  • Múltiplos filtros: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=successful&queryFilter[1][column]=sender&queryFilter[1][operation]=EQUALS&queryFilter[1][value]=12345678
Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Número da página (baseado em 1)

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=25

Número de itens por página

sortBy
string
Example: sortBy=created_at

Campo para ordenar (deve ser usado com 'order')

order
string
Enum: "asc" "desc"
Example: order=asc

Ordem de classificação (deve ser usado com 'sortBy')

queryFilter[{index}][column]
string
Enum: "id" "original_id" "sender" "recipient" "domain" "operation_type" "event_type" "status" "created_at" "updated_at"
Example: queryFilter[{index}][column]=operation_type

Nome da coluna para filtrar.

⚠️ Verifique a seção "Sistema de Filtros de Consulta" no topo desta documentação da API para uso completo de filtros, operações e exemplos.

queryFilter[{index}][operation]
string
Enum: "EQUALS" "NOT_EQUALS" "ILIKE" "NOT_ILIKE" "HIGHER" "LOWER" "IN" "NOT_IN" "AFTER_DATE" "BEFORE_DATE" "EQUALS_DATE" "AFTER_DATETIME" "BEFORE_DATETIME" "EQUALS_DATETIME" "BETWEEN_DATETIME"
Example: queryFilter[{index}][operation]=EQUALS
queryFilter[{index}][value]
string
queryFilter[{index}][valueArray]
string

Responses

Response Schema: application/json
required
object (PaginationMeta)
required
Array of objects (Operation)

List of operations

Response samples

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

Obter operação por ID

Recupera uma operação específica por seu identificador único. Retorna os detalhes da operação incluindo todos os eventos associados.

Authorizations:
OAuth2
path Parameters
operation_id
required
string
Example: 12345678202510206585020

Identificador único da operação

Responses

Response Schema: application/json
id
required
string^[0-9]{21}$

Identificador único da operação

sender
required
string

Identificador do participante remetente

recipient
required
string

Identificador do participante destinatário

domain
required
string
Enum: "SPB01" "SPB02" "MES01" "MES02" "MES03"

Domínio da operação

operation_type
required
string

Tipo de operação (ex: STR, GEN, etc.)

event_type
required
string

Tipo de evento principal para a operação

status
required
string
Enum: "request_processing" "response_processing" "request_pending" "response_pending" "request_awaiting" "response_awaiting" "successful" "failed" "canceled"

Status atual da operação

created_at
required
string <date-time>

Registro de data/hora quando a operação foi criada

Array of objects (Event)

List of events associated with this operation

Response samples

Content type
application/json
{
  • "id": "08240446202509246654421",
  • "sender": "08240446",
  • "recipient": "12345679",
  • "domain": "SPB01",
  • "operation_type": "GEN",
  • "event_type": "GEN0001",
  • "status": "successful",
  • "created_at": "2025-09-24T17:10:14.986-03:00",
  • "events": [
    ]
}

LongPolling

Endpoints de long polling para consumo de respostas do SPB

Endpoint de long polling para consumir respostas do SPB

Endpoint de long polling que permite aos clientes consumir respostas do SPB em tempo real.

O endpoint funciona da seguinte forma:

  • Use "start" como parâmetro pullNext para a requisição inicial
  • A resposta inclui um cabeçalho "onz-pull-next" com o próximo token de pull
  • Use o token do cabeçalho nas requisições subsequentes
  • O endpoint aguardará novas mensagens e as retornará quando disponíveis

Autenticação é obrigatória e o ISPB do usuário é usado para determinar a fila.

Authorizations:
OAuth2
path Parameters
pullNext
required
string
Example: start

Token de pull para long polling. Use "start" para a requisição inicial, então use o token retornado no cabeçalho "onz-pull-next" para requisições subsequentes.

Responses

Response Headers
onz-pull-next
string
Example: "a1b2c3d4e5"

Token a ser usado para a próxima requisição de long polling

Response Schema: application/json
One of
id
required
string

Unique identifier for the message

operation_id
string or null

Reference to the parent operation

event_type
string or null

Type of the event

message_type
required
string
Enum: "request" "response" "report" "support"

Type of message

sender
required
string

Identificador do participante remetente

recipient
required
string

Identificador do participante destinatário

plaintext
string or null

Plaintext XML document content

created_at
required
string <date-time>

Timestamp when the message was created

Response samples

Content type
application/json
Example
{
  • "id": "msg_12345",
  • "operation_id": "12345678202510206585020",
  • "event_type": "GEN0001R1",
  • "message_type": "response",
  • "sender": "12345679",
  • "recipient": "12345678",
  • "plaintext": "<?xml version=\"1.0\"?><DOC xmlns=\"http://www.bcb.gov.br/GEN/GEN0001.xsd\">...</DOC>",
  • "created_at": "2025-10-20T12:08:47.656-03:00"
}

Transactions

Endpoints de gerenciamento de transações STR

Criar uma nova transação STR

Cria uma nova transação STR do tipo especificado. Suporta vários tipos de transação STR incluindo STR0008 (transferências de pagamento) e outros.

A transação será processada de forma assíncrona e seu status pode ser rastreado via endpoint GET.

Authorizations:
OAuth2
path Parameters
transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"
Example: STR0008

Tipo de transação STR a ser criada

Request Body schema: application/json
required

Detalhes da transação incluindo informações do remetente e destinatário

idempotency_key
required
string <uuid>

UUID for request idempotency

institution_control_number
string or null

Optional control number from the institution

required
object (BankAccount)
required
object (BankAccount)
amount
required
number <double> >= 0.01

Transaction amount in BRL

reason
required
integer

Transaction reason code

identifier_code
string or null

Optional identifier code

description
string or null

Optional transaction description

schedule_datetime
string or null <date-time>

Optional scheduled execution datetime

priority
integer or null [ 0 .. 9 ]

Transaction priority (0-9)

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

str_id
string or null

STR identifier assigned by SPB

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of STR transaction

entry_type
required
string
Enum: "debit" "credit"

Transaction entry type

status
required
string
Enum: "processing" "submitted" "pending" "canceled" "settled" "refunded" "rejected" "failed" "error"

Current status of the transaction

failed_reason
string or null

Reason for failure (if status is failed or error)

object (BankAccount)
object (BankAccount)
contract_number
string or null

Contract number (for specific transaction types)

amount
required
number <double>

Transaction amount in BRL

reason
required
integer

Transaction reason code

identifier_code
string or null

Identifier code

description
string or null

Transaction description

schedule_datetime
string or null <date-time>

Scheduled execution datetime

priority
integer or null

Transaction priority

created_at
required
string <date-time>

Timestamp when the transaction was created

Request samples

Content type
application/json
{
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "institution_control_number": "CTRL123456",
  • "sender_entity": {
    },
  • "receiver_entity": {
    },
  • "amount": 1000.5,
  • "reason": 1,
  • "identifier_code": "ID12345",
  • "description": "Payment description",
  • "schedule_datetime": "2025-10-21T14:30:00Z",
  • "priority": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "operation_id": "12345678202510206585020",
  • "control_number": "CTRL123456",
  • "str_id": "STR123456",
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "status": "processing",
  • "sender_entity": {
    },
  • "receiver_entity": {
    },
  • "amount": 1000.5,
  • "reason": 1,
  • "identifier_code": "ID12345",
  • "description": "Payment description",
  • "schedule_datetime": "2025-10-21T14:30:00Z",
  • "priority": 1,
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Obter transação por ID

Recupera uma transação específica por seu identificador único

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único da transação

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

str_id
string or null

STR identifier assigned by SPB

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of STR transaction

entry_type
required
string
Enum: "debit" "credit"

Transaction entry type

status
required
string
Enum: "processing" "submitted" "pending" "canceled" "settled" "refunded" "rejected" "failed" "error"

Current status of the transaction

failed_reason
string or null

Reason for failure (if status is failed or error)

object (BankAccount)
object (BankAccount)
contract_number
string or null

Contract number (for specific transaction types)

amount
required
number <double>

Transaction amount in BRL

reason
required
integer

Transaction reason code

identifier_code
string or null

Identifier code

description
string or null

Transaction description

schedule_datetime
string or null <date-time>

Scheduled execution datetime

priority
integer or null

Transaction priority

created_at
required
string <date-time>

Timestamp when the transaction was created

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "operation_id": "12345678202510206585020",
  • "control_number": "CTRL123456",
  • "str_id": "STR123456",
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "status": "processing",
  • "failed_reason": "Insufficient balance",
  • "sender_entity": {
    },
  • "receiver_entity": {
    },
  • "contract_number": "CONTRACT123",
  • "amount": 1000.5,
  • "reason": 1,
  • "identifier_code": "ID12345",
  • "description": "Payment description",
  • "schedule_datetime": "2025-10-21T14:30:00Z",
  • "priority": 1,
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Listar transações com paginação

Recupera uma lista paginada de transações. Suporta filtragem por vários critérios.

Exemplos de filtros:

  • Filtro único: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=settled
  • Filtro de array: ?queryFilter[0][column]=transaction_type&queryFilter[0][operation]=IN&queryFilter[0][valueArray][0]=STR0008&queryFilter[0][valueArray][1]=STR0025
  • Múltiplos filtros: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=settled&queryFilter[1][column]=entry_type&queryFilter[1][operation]=EQUALS&queryFilter[1][value]=debit
Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Número da página (baseado em 1)

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=25

Número de itens por página

sortBy
string
Example: sortBy=created_at

Campo para ordenar (deve ser usado com 'order')

order
string
Enum: "asc" "desc"
Example: order=asc

Ordem de classificação (deve ser usado com 'sortBy')

queryFilter[{index}][column]
string
Enum: "id" "idempotency_key" "operation_id" "control_number" "str_id" "transaction_type" "entry_type" "status" "failed_reason" "sender_ispb" "sender_agency" "sender_account_type" "sender_account_number" "sender_entity_type" "sender_entity_number" "sender_entity_name" "receiver_ispb" "receiver_agency" "receiver_account_type" "receiver_account_number" "receiver_entity_type" "receiver_entity_number" "receiver_entity_name" "contract_number" "amount" "reason" "identifier_code" "description" "schedule_datetime" "priority" "retry_count" "created_at"
Example: queryFilter[{index}][column]=transaction_type

Nome da coluna para filtrar.

⚠️ Verifique a seção "Sistema de Filtros de Consulta" no topo desta documentação da API para uso completo de filtros, operações e exemplos.

queryFilter[{index}][operation]
string
Enum: "EQUALS" "NOT_EQUALS" "ILIKE" "NOT_ILIKE" "HIGHER" "LOWER" "IN" "NOT_IN" "AFTER_DATE" "BEFORE_DATE" "EQUALS_DATE" "AFTER_DATETIME" "BEFORE_DATETIME" "EQUALS_DATETIME" "BETWEEN_DATETIME"
Example: queryFilter[{index}][operation]=EQUALS
queryFilter[{index}][value]
string
queryFilter[{index}][valueArray]
string

Responses

Response Schema: application/json
required
Array of objects (Transaction)

List of transactions

page
required
integer <int32>

Current page number

per_page
required
integer <int32>

Number of items per page

total
required
integer <int32>

Total number of transactions

total_pages
required
integer <int32>

Total number of pages

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 1,
  • "per_page": 2,
  • "total": 30,
  • "total_pages": 15
}

Aceitar uma transação pendente

Aprova uma transação que está em status pendente. Esta operação é tipicamente usada para transações que requerem aprovação manual.

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único da transação

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

str_id
string or null

STR identifier assigned by SPB

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of STR transaction

entry_type
required
string
Enum: "debit" "credit"

Transaction entry type

status
required
string
Enum: "processing" "submitted" "pending" "canceled" "settled" "refunded" "rejected" "failed" "error"

Current status of the transaction

failed_reason
string or null

Reason for failure (if status is failed or error)

object (BankAccount)
object (BankAccount)
contract_number
string or null

Contract number (for specific transaction types)

amount
required
number <double>

Transaction amount in BRL

reason
required
integer

Transaction reason code

identifier_code
string or null

Identifier code

description
string or null

Transaction description

schedule_datetime
string or null <date-time>

Scheduled execution datetime

priority
integer or null

Transaction priority

created_at
required
string <date-time>

Timestamp when the transaction was created

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "operation_id": "12345678202510206585020",
  • "control_number": "CTRL123456",
  • "str_id": "STR123456",
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "status": "processing",
  • "failed_reason": "Insufficient balance",
  • "sender_entity": {
    },
  • "receiver_entity": {
    },
  • "contract_number": "CONTRACT123",
  • "amount": 1000.5,
  • "reason": 1,
  • "identifier_code": "ID12345",
  • "description": "Payment description",
  • "schedule_datetime": "2025-10-21T14:30:00Z",
  • "priority": 1,
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Rejeitar uma transação pendente

Rejeita uma transação que está em status pendente. Uma vez rejeitada, a transação não pode ser processada posteriormente.

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único da transação

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

str_id
string or null

STR identifier assigned by SPB

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of STR transaction

entry_type
required
string
Enum: "debit" "credit"

Transaction entry type

status
required
string
Enum: "processing" "submitted" "pending" "canceled" "settled" "refunded" "rejected" "failed" "error"

Current status of the transaction

failed_reason
string or null

Reason for failure (if status is failed or error)

object (BankAccount)
object (BankAccount)
contract_number
string or null

Contract number (for specific transaction types)

amount
required
number <double>

Transaction amount in BRL

reason
required
integer

Transaction reason code

identifier_code
string or null

Identifier code

description
string or null

Transaction description

schedule_datetime
string or null <date-time>

Scheduled execution datetime

priority
integer or null

Transaction priority

created_at
required
string <date-time>

Timestamp when the transaction was created

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "550e8400-e29b-41d4-a716-446655440000",
  • "operation_id": "12345678202510206585020",
  • "control_number": "CTRL123456",
  • "str_id": "STR123456",
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "status": "processing",
  • "failed_reason": "Insufficient balance",
  • "sender_entity": {
    },
  • "receiver_entity": {
    },
  • "contract_number": "CONTRACT123",
  • "amount": 1000.5,
  • "reason": 1,
  • "identifier_code": "ID12345",
  • "description": "Payment description",
  • "schedule_datetime": "2025-10-21T14:30:00Z",
  • "priority": 1,
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Transaction Limits

Endpoints de configuração de limites de transação

Criar um limite de transação

Cria uma nova configuração de limite de transação. Os limites de transação controlam o valor máximo permitido para tipos específicos de transação e tipos de entrada (débito/crédito).

Apenas um limite ativo por combinação transaction_type + entry_type é permitido.

Authorizations:
OAuth2
Request Body schema: application/json
required

Configuração do limite de transação

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of transaction to limit

entry_type
required
string
Enum: "debit" "credit"

Entry type to limit

max_amount
required
number <double> [ 0 .. 999999999.99 ]

Maximum allowed amount in BRL

is_active
boolean or null

Whether the limit is active (defaults to true)

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction limit

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of transaction

entry_type
required
string
Enum: "debit" "credit"

Entry type

max_amount
required
number <double>

Maximum allowed amount in BRL

is_active
required
boolean

Whether the limit is active

created_at
required
string <date-time>

Timestamp when the limit was created

updated_at
required
string <date-time>

Timestamp when the limit was last updated

Request samples

Content type
application/json
{
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "max_amount": 15000,
  • "is_active": true
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "max_amount": 15000,
  • "is_active": true,
  • "created_at": "2025-10-21T10:00:00.000-03:00",
  • "updated_at": "2025-10-21T10:00:00.000-03:00"
}

Listar todos os limites de transação

Recupera todos os limites de transação configurados

Authorizations:
OAuth2

Responses

Response Schema: application/json
Array
id
required
integer <int64>

Unique identifier for the transaction limit

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of transaction

entry_type
required
string
Enum: "debit" "credit"

Entry type

max_amount
required
number <double>

Maximum allowed amount in BRL

is_active
required
boolean

Whether the limit is active

created_at
required
string <date-time>

Timestamp when the limit was created

updated_at
required
string <date-time>

Timestamp when the limit was last updated

Response samples

Content type
application/json
[
  • {
    },
  • {
    }
]

Obter limite de transação por ID

Recupera um limite de transação específico por seu identificador único

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único do limite de transação

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction limit

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of transaction

entry_type
required
string
Enum: "debit" "credit"

Entry type

max_amount
required
number <double>

Maximum allowed amount in BRL

is_active
required
boolean

Whether the limit is active

created_at
required
string <date-time>

Timestamp when the limit was created

updated_at
required
string <date-time>

Timestamp when the limit was last updated

Response samples

Content type
application/json
{
  • "id": 1,
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "max_amount": 15000,
  • "is_active": true,
  • "created_at": "2025-10-21T10:00:00.000-03:00",
  • "updated_at": "2025-10-21T10:00:00.000-03:00"
}

Atualizar limite de transação

Atualiza um limite de transação existente. Apenas os campos max_amount e is_active podem ser atualizados. Os campos transaction_type e entry_type não podem ser alterados após a criação.

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único do limite de transação

Request Body schema: application/json
required

Campos a serem atualizados

max_amount
number or null <double> [ 0 .. 999999999.99 ]

Updated maximum allowed amount in BRL

is_active
boolean or null

Whether the limit is active

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the transaction limit

transaction_type
required
string
Enum: "STR0005" "STR0006" "STR0007" "STR0008" "STR0025" "STR0034" "STR0037" "STR0041" "STR0051"

Type of transaction

entry_type
required
string
Enum: "debit" "credit"

Entry type

max_amount
required
number <double>

Maximum allowed amount in BRL

is_active
required
boolean

Whether the limit is active

created_at
required
string <date-time>

Timestamp when the limit was created

updated_at
required
string <date-time>

Timestamp when the limit was last updated

Request samples

Content type
application/json
{
  • "max_amount": 20000,
  • "is_active": false
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "transaction_type": "STR0008",
  • "entry_type": "debit",
  • "max_amount": 20000,
  • "is_active": false,
  • "created_at": "2025-10-21T10:00:00.000-03:00",
  • "updated_at": "2025-10-21T10:05:00.000-03:00"
}

Excluir limite de transação

Exclui uma configuração de limite de transação

Authorizations:
OAuth2
path Parameters
id
required
integer
Example: 1

Identificador único do limite de transação

Responses

Response samples

Content type
application/json
{
  • "message": "Invalid request"
}

Balances

Endpoints de consulta e sincronização de saldos

Obter registro de saldo mais recente

Recupera o registro de saldo mais recente para o participante autenticado. Retorna as informações de sincronização de saldo mais recentes incluindo detalhes da operação e status.

Authorizations:
OAuth2

Responses

Response Schema: application/json
id
required
integer <int32>

Unique identifier for the balance record

idempotency_key
required
string <uuid>

Unique key to ensure idempotent operations

operation_id
required
string

SPB operation identifier

control_number
string or null

Control number for the balance operation

ispb
required
string^\d{8}$

ISPB of the participant

amount
number or null <double>

Balance amount in BRL cents

status
required
string
Enum: "submitted" "success" "error"

Status of the balance operation

created_at
required
string <date-time>

Timestamp when the balance record was created

Response samples

Content type
application/json
{
  • "id": 87,
  • "idempotency_key": "8dcaa585-2ad2-4b07-b170-48ca121732b7",
  • "operation_id": "08253539202510214585523",
  • "control_number": "e12ada419a047087e6d5",
  • "ispb": "08253539",
  • "amount": 2065965141.6,
  • "status": "success",
  • "created_at": "2025-10-21T17:00:00.672-03:00"
}

Sincronizar saldo com SPB

Dispara uma sincronização de saldo com o sistema SPB. Esta operação busca as informações de saldo mais recentes do SPB e atualiza o cache local.

Authorizations:
OAuth2
Request Body schema: application/json
required

Balance synchronization request details

idempotency_key
required
string <uuid>

Unique key to ensure idempotent operations

control_number
string or null

Optional control number for the balance operation

Responses

Response Schema: application/json
id
required
integer <int32>

Unique identifier for the balance record

idempotency_key
required
string <uuid>

Unique key to ensure idempotent operations

operation_id
required
string

SPB operation identifier

control_number
string or null

Control number for the balance operation

ispb
required
string^\d{8}$

ISPB of the participant

amount
number or null <double>

Balance amount in BRL cents

status
required
string
Enum: "submitted" "success" "error"

Status of the balance operation

created_at
required
string <date-time>

Timestamp when the balance record was created

Request samples

Content type
application/json
{
  • "idempotency_key": "8dcaa585-2ad2-4b07-b170-48ca121732b7",
  • "control_number": "e12ada419a047087e6d5"
}

Response samples

Content type
application/json
{
  • "id": 87,
  • "idempotency_key": "8dcaa585-2ad2-4b07-b170-48ca121732b7",
  • "operation_id": "08253539202510214585523",
  • "control_number": "e12ada419a047087e6d5",
  • "ispb": "08253539",
  • "amount": 2065965141.6,
  • "status": "success",
  • "created_at": "2025-10-21T17:00:00.672-03:00"
}

Criar uma operação de crédito de saldo

Cria uma operação de crédito que transfere fundos para o destinatário especificado. O destinatário receberá o valor especificado em seu saldo.

Authorizations:
OAuth2
Request Body schema: application/json
required

Detalhes da operação de crédito de saldo

idempotency_key
required
string <uuid>

UUID for request idempotency

control_number
string or null

Optional control number from the institution

receiver_ispb
required
string^\d{8}$

ISPB of the receiver participant

amount
required
number <double> >= 0.01

Credit amount in BRL

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the balance operation

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

receiver_ispb
required
string^\d{8}$

ISPB of the receiver participant

amount
required
number <double>

Operation amount in BRL

reason
integer or null
Enum: 1 2

Reason code (only for debit operations)

operation_type
required
string
Enum: "credit" "debit"

Type of balance operation

status
required
string
Enum: "processing" "submitted" "settled" "failed" "canceled"

Status atual da operação

failed_reason
string or null

Reason for failure (if status is failed)

created_at
required
string <date-time>

Registro de data/hora quando a operação foi criada

Request samples

Content type
application/json
{
  • "idempotency_key": "0199f28b-d4f8-7e43-9567-abfe9f6346ea",
  • "control_number": "5",
  • "receiver_ispb": "08253539",
  • "amount": 123
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "0199f28b-d4f8-7e43-9567-abfe9f6346ea",
  • "operation_id": "12345678202510206585020",
  • "control_number": "5",
  • "receiver_ispb": "08253539",
  • "amount": 123,
  • "operation_type": "credit",
  • "status": "processing",
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Criar uma operação de débito de saldo

Cria uma operação de débito que transfere fundos para o destinatário especificado. O saldo do remetente é debitado e o destinatário receberá o valor especificado.

Códigos de razão:

  • 1: Own movement or account in STR Settler (Movimentação própria ou para conta em Liquidante no STR)
  • 2: Return of contribution received incorrectly (Devolução de aporte recebido indevidamente)
Authorizations:
OAuth2
Request Body schema: application/json
required

Detalhes da operação de débito de saldo

idempotency_key
required
string <uuid>

UUID for request idempotency

control_number
string or null

Optional control number from the institution

receiver_ispb
required
string^\d{8}$

ISPB of the receiver participant

amount
required
number <double> >= 0.01

Debit amount in BRL

reason
required
integer
Enum: 1 2

Reason code for the debit operation:

  • 1: Own movement or account in STR Settler (Movimentação própria ou para conta em Liquidante no STR)
  • 2: Return of contribution received incorrectly (Devolução de aporte recebido indevidamente)

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the balance operation

idempotency_key
required
string <uuid>

UUID for request idempotency

operation_id
string or null

Associated SPB operation ID

control_number
string or null

Institution control number

receiver_ispb
required
string^\d{8}$

ISPB of the receiver participant

amount
required
number <double>

Operation amount in BRL

reason
integer or null
Enum: 1 2

Reason code (only for debit operations)

operation_type
required
string
Enum: "credit" "debit"

Type of balance operation

status
required
string
Enum: "processing" "submitted" "settled" "failed" "canceled"

Status atual da operação

failed_reason
string or null

Reason for failure (if status is failed)

created_at
required
string <date-time>

Registro de data/hora quando a operação foi criada

Request samples

Content type
application/json
{
  • "idempotency_key": "0199f28b-d4f8-7e43-9567-abfe9f6346ea",
  • "control_number": "5",
  • "receiver_ispb": "08253539",
  • "amount": 123,
  • "reason": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "0199f28b-d4f8-7e43-9567-abfe9f6346ea",
  • "operation_id": "12345678202510206585020",
  • "control_number": "5",
  • "receiver_ispb": "08253539",
  • "amount": 123,
  • "reason": 1,
  • "operation_type": "debit",
  • "status": "processing",
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Refunds

Endpoints de gerenciamento de reembolsos

Criar um reembolso para uma transação

Cria uma solicitação de reembolso para uma transação liquidada. O reembolso será processado pelo valor total da transação original.

Pré-requisitos:

  • Transação deve estar em status settled
  • Transação deve ser do tipo credito
  • O participante deve ter saldo disponível suficiente para processar o refund
Authorizations:
OAuth2
path Parameters
transaction_id
required
integer
Example: 1

ID da transação a ser reembolsada

Request Body schema: application/json
required

Detalhes do reembolso

idempotency_key
required
string <uuid>

UUID for request idempotency

control_number
string or null [ 1 .. 20 ] characters

Control number for the refund operation (1-20 characters)

reason
required
integer <int32>

Code representing the reason for the refund

description
string or null

Optional description providing additional details about the refund

schedule_datetime
string or null <date-time>

Scheduled datetime for processing the refund (ISO 8601 format)

priority
integer or null <int32>

Priority level for processing the refund

Responses

Response Schema: application/json
id
required
integer <int64>

Unique identifier for the refund

idempotency_key
required
string <uuid>

UUID for request idempotency

transaction_id
required
integer <int64>

ID of the original transaction

transaction_str_id
required
string

STR ID of the original transaction

operation_id
required
string

Associated SPB operation ID for the refund

control_number
string or null

Control number for the refund operation

str_id
string or null

STR identifier for the refund

status
required
string
Enum: "processing" "submitted" "settled" "failed" "canceled"

Current status of the refund

failed_reason
string or null

Reason for refund failure (only present if status is failed)

sender_ispb
required
string

ISPB of the sender institution

receiver_ispb
required
string

ISPB of the receiver institution

amount
required
number <double>

Refund amount in BRL

reason
required
integer <int32>

Code representing the reason for the refund

description
string or null

Optional description providing additional details about the refund

schedule_datetime
string or null <date-time>

Scheduled datetime for processing the refund

priority
integer or null <int32>

Priority level for processing the refund

created_at
required
string <date-time>

Timestamp when the refund was created

Request samples

Content type
application/json
{
  • "idempotency_key": "0199ee0b-91e9-7bb2-b3d6-bf443636d83e",
  • "control_number": "4",
  • "reason": 1,
  • "description": "Customer requested refund",
  • "schedule_datetime": "2025-10-22T14:30:00-03:00",
  • "priority": 1
}

Response samples

Content type
application/json
{
  • "id": 1,
  • "idempotency_key": "0199ee0b-91e9-7bb2-b3d6-bf443636d83e",
  • "transaction_id": 1,
  • "transaction_str_id": "12345678202510206585021",
  • "operation_id": "12345678202510206585022",
  • "control_number": "4",
  • "str_id": "12345678202510206585023",
  • "status": "processing",
  • "failed_reason": "Insufficient balance",
  • "sender_ispb": "12345678",
  • "receiver_ispb": "87654321",
  • "amount": 500,
  • "reason": 1,
  • "description": "Customer requested refund",
  • "schedule_datetime": "2025-10-22T14:30:00-03:00",
  • "priority": 1,
  • "created_at": "2025-10-21T10:00:00.000-03:00"
}

Listar reembolsos com paginação

Recupera uma lista paginada de reembolsos. Suporta filtragem e ordenação.

Exemplos de filtros:

  • Filtro único: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=refunded
  • Filtro de array: ?queryFilter[0][column]=sender_ispb&queryFilter[0][operation]=IN&queryFilter[0][valueArray][0]=12345678&queryFilter[0][valueArray][1]=87654321
  • Múltiplos filtros: ?queryFilter[0][column]=status&queryFilter[0][operation]=EQUALS&queryFilter[0][value]=refunded&queryFilter[1][column]=amount&queryFilter[1][operation]=HIGHER&queryFilter[1][value]=100
Authorizations:
OAuth2
query Parameters
page
integer >= 1
Default: 1
Example: page=1

Número da página (baseado em 1)

perPage
integer [ 1 .. 100 ]
Default: 25
Example: perPage=25

Número de itens por página

sortBy
string
Example: sortBy=created_at

Campo para ordenar (deve ser usado com 'order')

order
string
Enum: "asc" "desc"
Example: order=asc

Ordem de classificação (deve ser usado com 'sortBy')

queryFilter[{index}][column]
string
Enum: "id" "idempotency_key" "transaction_id" "transaction_str_id" "operation_id" "control_number" "str_id" "status" "failed_reason" "sender_ispb" "receiver_ispb" "amount" "reason" "description" "schedule_datetime" "priority" "created_at"
Example: queryFilter[{index}][column]=status

Nome da coluna para filtrar.

⚠️ Verifique a seção "Sistema de Filtros de Consulta" no topo desta documentação da API para uso completo de filtros, operações e exemplos.

queryFilter[{index}][operation]
string
Enum: "EQUALS" "NOT_EQUALS" "ILIKE" "NOT_ILIKE" "HIGHER" "LOWER" "IN" "NOT_IN" "AFTER_DATE" "BEFORE_DATE" "EQUALS_DATE" "AFTER_DATETIME" "BEFORE_DATETIME" "EQUALS_DATETIME" "BETWEEN_DATETIME"
Example: queryFilter[{index}][operation]=EQUALS
queryFilter[{index}][value]
string
queryFilter[{index}][valueArray]
string

Responses

Response Schema: application/json
required
Array of objects (RefundResponse)

List of refunds

page
required
integer <int32>

Current page number

per_page
required
integer <int32>

Number of items per page

total
required
integer <int32>

Total number of refunds

total_pages
required
integer <int32>

Total number of pages

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "page": 1,
  • "per_page": 2,
  • "total": 5,
  • "total_pages": 3
}