API do Serviço SPI

API Endpoint

https://api.dictra.com.br

O Serviço SPI (Sistema de Pagamentos Instantâneos) gerencia o processamento de pagamentos instantâneos brasileiros via BACEN (Banco Central do Brasil). Esta API fornece endpoints para criar pagamentos PIX, consultar saldos, gerenciar pagamentos em lote, pagamentos recorrentes e operações de devolução.

Versão: 1.0.0 Protocolo: ISO 20022 (pacs.008, pacs.002, pacs.004, camt.060, pain.009, pain.011, pain.012) Meta de TPS: 1.500 transações por segundo Referência BACEN: Manual SPI v5.11.1

Autenticação

Todos os endpoints da API (exceto /health e /ready) requerem autenticação JWT.

Authorization: Bearer <jwt_token>

Fluxo de Mensagens ISO 20022

Criação de Pagamento
    ↓
pacs.008 (Transferência de Crédito) → BACEN
    ↓
pacs.002 (Relatório de Status) ← BACEN
    ↓
Pagamento Liquidado/Rejeitado

Tipos de Iniciação de Pagamento (LocalInstrument)

Código	Nome	Chave PIX	TxId	Origem do EndToEndId	Correlação de Token
MANU	Entrada Manual	Não	Não	Gerado pelo SPI	Não
DICT	Consulta de Chave PIX	Obrigatória	Não	Gerado pelo DICT	Sim
QRES	QR Code Estático	Obrigatória	≤25 chars	Gerado pelo SPI	Não
QRDN	QR Code Dinâmico	Obrigatória	26-35 chars	Gerado pelo SPI	Não
INIC	Iniciador de Pagamento	Obrigatória	≤25 chars	Gerado pelo SPI	Não
AUTO	PIX Automático	Opcional	26-35 chars	Gerado pelo SPI	Não
APDN	PIX Automático Dinâmico	Opcional	26-35 chars	Gerado pelo SPI	Não
APES	PIX Automático Estático	Opcional	≤25 chars	Gerado pelo SPI	Não

Importante: Apenas pagamentos iniciados via DICT disparam correlação de devolução de token com o dict-service.

Verificações de Saúde ¶

Endpoints de liveness e readiness probe.

Liveness ¶

GET https://api.dictra.com.br/health

Responses200

Headers

Content-Type: application/json

Body

{
  "status": "healthy",
  "uptime": "2h30m45s",
  "timestamp": "2026-01-24T10:30:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "uptime": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    }
  },
  "required": [
    "status",
    "uptime",
    "timestamp"
  ]
}

Verificar Liveness
GET`/health`

Retorna o status de liveness do serviço.

Readiness ¶

GET https://api.dictra.com.br/ready

Responses200503

Headers

Content-Type: application/json

Body

{
  "status": "healthy",
  "services": {
    "database": "healthy",
    "bacen": "healthy",
    "nats": "healthy"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "services": {
      "type": "object",
      "properties": {
        "database": {
          "type": "string"
        },
        "bacen": {
          "type": "string"
        },
        "nats": {
          "type": "string"
        }
      },
      "required": [
        "database",
        "bacen",
        "nats"
      ]
    }
  },
  "required": [
    "status",
    "services"
  ]
}

Headers

Content-Type: application/json

Body

{
  "status": "unhealthy",
  "services": {
    "database": "healthy",
    "bacen": "unhealthy",
    "nats": "healthy"
  }
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "status": {
      "type": "string"
    },
    "services": {
      "type": "object",
      "properties": {
        "database": {
          "type": "string"
        },
        "bacen": {
          "type": "string"
        },
        "nats": {
          "type": "string"
        }
      }
    }
  },
  "required": [
    "status",
    "services"
  ]
}

Verificar Readiness
GET`/ready`

Retorna o status de readiness do serviço com verificação de dependências.

Pagamentos Principais ¶

Operações de pagamento PIX usando mensagens ISO 20022 pacs.008.

Coleção de Pagamentos ¶

POST https://api.dictra.com.br/api/v1/payments

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "local_instrument": "MANU",
  "priority_type": "PAGPRI",
  "priority_id": 1,
  "purpose": "IPAY",
  "amount": 10000,
  "currency": "BRL",
  "debtor": {
    "ispb": "12345678",
    "name": "João Silva",
    "document": "12345678901",
    "account_no": "00001234567",
    "account_type": "CACC",
    "branch": "0001"
  },
  "creditor": {
    "ispb": "87654321",
    "name": "Maria Oliveira",
    "document": "98765432100",
    "account_no": "00009876543",
    "account_type": "CACC",
    "branch": "0002",
    "proxy": "maria@example.com"
  },
  "tx_id": "abc123",
  "initiating_party": "12345678000199",
  "description": "Pagamento por serviços",
  "dict_end_to_end_id": "E1234567820260124103012345abcde",
  "dict_correlation_id": "uuid-v4-correlation",
  "origin_system": 1
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "local_instrument": {
      "type": "string",
      "enum": [
        "MANU",
        "DICT",
        "QRES",
        "QRDN",
        "INIC",
        "AUTO",
        "APDN",
        "APES"
      ],
      "description": "Tipo de iniciação"
    },
    "priority_type": {
      "type": "string",
      "enum": [
        "PAGPRI",
        "PAGFRD",
        "PAGAGD"
      ],
      "description": "Prioridade do pagamento"
    },
    "priority_id": {
      "type": "number",
      "description": "ID de prioridade (1=ALTA, 2=NORMAL)"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "IPAY",
        "GSCB",
        "OTHR",
        "REFU"
      ],
      "description": "Propósito da transação"
    },
    "amount": {
      "type": "number",
      "description": "Valor em centavos (R$ 100,00)"
    },
    "currency": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string",
          "description": "ISPB de 8 dígitos"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string",
          "description": "CPF ou CNPJ"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string",
          "description": "CACC, SVGS, TRAN"
        },
        "branch": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "branch": {
          "type": "string"
        },
        "proxy": {
          "type": "string",
          "description": "Chave PIX (obrigatória para DICT, QRDN, QRES, INIC)"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "tx_id": {
      "type": "string",
      "description": "ID da transação (obrigatório para QR/INIC)"
    },
    "initiating_party": {
      "type": "string",
      "description": "Obrigatório para INIC"
    },
    "description": {
      "type": "string",
      "description": "Máx 140 caracteres"
    },
    "dict_end_to_end_id": {
      "type": "string",
      "description": "Apenas para pagamentos DICT"
    },
    "dict_correlation_id": {
      "type": "string",
      "description": "Para rastreamento de devolução de token"
    },
    "origin_system": {
      "type": "number"
    }
  },
  "required": [
    "local_instrument",
    "priority_type",
    "priority_id",
    "purpose",
    "amount",
    "currency",
    "debtor",
    "creditor",
    "origin_system"
  ]
}

Responses201400

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "end_to_end_id": "E1234567820260124103012345abcde",
  "message_id": "M1234567820260124103012345abcde",
  "tx_id": "abc123",
  "local_instrument": "DICT",
  "priority_type": "PAGPRI",
  "purpose": "IPAY",
  "amount": 10000,
  "currency": "BRL",
  "debtor": {
    "ispb": "12345678",
    "name": "João Silva",
    "document": "12345678901",
    "account_no": "00001234567",
    "account_type": "CACC"
  },
  "creditor": {
    "ispb": "87654321",
    "name": "Maria Oliveira",
    "document": "98765432100",
    "account_no": "00009876543",
    "account_type": "CACC",
    "proxy": "maria@example.com"
  },
  "status": "ENTRY_RECEIVED",
  "operation_datetime": "2026-01-24T10:30:12Z",
  "created_at": "2026-01-24T10:30:12Z",
  "updated_at": "2026-01-24T10:30:12Z",
  "dict_correlation_id": "uuid-v4-correlation",
  "token_refunded": false
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "end_to_end_id": {
      "type": "string",
      "description": "32 caracteres"
    },
    "message_id": {
      "type": "string",
      "description": "32 caracteres"
    },
    "tx_id": {
      "type": "string"
    },
    "local_instrument": {
      "type": "string"
    },
    "priority_type": {
      "type": "string"
    },
    "purpose": {
      "type": "string"
    },
    "amount": {
      "type": "number"
    },
    "currency": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "proxy": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "status": {
      "type": "string"
    },
    "operation_datetime": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    },
    "dict_correlation_id": {
      "type": "string"
    },
    "token_refunded": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "end_to_end_id",
    "message_id",
    "local_instrument",
    "priority_type",
    "purpose",
    "amount",
    "currency",
    "debtor",
    "creditor",
    "status",
    "operation_datetime",
    "created_at",
    "updated_at",
    "token_refunded"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "validation_failed",
  "message": "Pagamentos DICT requerem chave PIX (CreditorProxy)"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}

Criar Pagamento
POST`/api/v1/payments`

Cria um novo pagamento PIX. Regras de validação se aplicam baseadas no tipo LocalInstrument.

Pagamentos DICT: EndToEndId deve ser fornecido do dict-service (correlação de token). Outros Tipos: EndToEndId é gerado automaticamente pelo SPI.

GET https://api.dictra.com.br/api/v1/payments?status=ACSP&limit=50&offset=0

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "payments": [
    {
      "id": 1,
      "end_to_end_id": "E1234567820260124103012345abcde",
      "message_id": "M1234567820260124103012345abcde",
      "local_instrument": "DICT",
      "amount": 10000,
      "currency": "BRL",
      "status": "ACSP",
      "operation_datetime": "2026-01-24T10:30:12Z",
      "created_at": "2026-01-24T10:30:12Z"
    }
  ],
  "total": 123,
  "limit": 50,
  "offset": 0
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payments": {
      "type": "array"
    },
    "total": {
      "type": "number"
    },
    "limit": {
      "type": "number"
    },
    "offset": {
      "type": "number"
    }
  },
  "required": [
    "payments",
    "total",
    "limit",
    "offset"
  ]
}

Listar Pagamentos
GET`/api/v1/payments{?status,limit,offset}`

Lista pagamentos com filtro de status opcional.

URI Parameters

HideShow

status

string (optional) Example: ACSP

Filtrar por status

Choices: ENTRY_RECEIVED VALIDATED PENDING_BACEN SENT_TO_BACEN ACSP ACCC RJCT PDNG CANC

limit

number (optional) Example: 50

Máximo de resultados (padrão: 50)

offset

number (optional) Example: 0

Offset de paginação

Pagamento ¶

GET https://api.dictra.com.br/api/v1/payments/1

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200404

Headers

Content-Type: application/json

Body

{
  "id": 1,
  "end_to_end_id": "E1234567820260124103012345abcde",
  "message_id": "M1234567820260124103012345abcde",
  "tx_id": "abc123",
  "local_instrument": "DICT",
  "priority_type": "PAGPRI",
  "priority_id": 1,
  "purpose": "IPAY",
  "amount": 10000,
  "currency": "BRL",
  "debtor": {
    "ispb": "12345678",
    "name": "João Silva",
    "document": "12345678901",
    "account_no": "00001234567",
    "account_type": "CACC",
    "branch": "0001"
  },
  "creditor": {
    "ispb": "87654321",
    "name": "Maria Oliveira",
    "document": "98765432100",
    "account_no": "00009876543",
    "account_type": "CACC",
    "branch": "0002",
    "proxy": "maria@example.com"
  },
  "status": "ACSP",
  "reason_code": "ACSP",
  "operation_datetime": "2026-01-24T10:30:12Z",
  "acceptance_datetime": "2026-01-24T10:30:15Z",
  "created_at": "2026-01-24T10:30:12Z",
  "updated_at": "2026-01-24T10:30:15Z",
  "dict_correlation_id": "uuid-v4-correlation",
  "token_refunded": true
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "number"
    },
    "end_to_end_id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "tx_id": {
      "type": "string"
    },
    "local_instrument": {
      "type": "string"
    },
    "priority_type": {
      "type": "string"
    },
    "priority_id": {
      "type": "number"
    },
    "purpose": {
      "type": "string"
    },
    "amount": {
      "type": "number"
    },
    "currency": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "branch": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "account_no": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "branch": {
          "type": "string"
        },
        "proxy": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "status": {
      "type": "string"
    },
    "reason_code": {
      "type": "string"
    },
    "operation_datetime": {
      "type": "string"
    },
    "acceptance_datetime": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    },
    "dict_correlation_id": {
      "type": "string"
    },
    "token_refunded": {
      "type": "boolean"
    }
  },
  "required": [
    "id",
    "end_to_end_id",
    "message_id",
    "local_instrument",
    "priority_type",
    "priority_id",
    "purpose",
    "amount",
    "currency",
    "debtor",
    "creditor",
    "status",
    "operation_datetime",
    "created_at",
    "updated_at",
    "token_refunded"
  ]
}

Headers

Content-Type: application/json

Body

{
  "error": "not_found",
  "message": "Pagamento não encontrado"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "error": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "error",
    "message"
  ]
}

Obter Pagamento
GET`/api/v1/payments/{id}`

Recupera detalhes do pagamento por ID ou EndToEndId.

URI Parameters

HideShow

id: string (required) Example: 1
ID do Pagamento ou EndToEndId

Histórico do Pagamento ¶

GET https://api.dictra.com.br/api/v1/payments/1/history

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

Operações de consulta de saldo BACEN usando mensagens ISO 20022 camt.060.

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payment_id": {
      "type": "number"
    },
    "end_to_end_id": {
      "type": "string"
    },
    "history": {
      "type": "array"
    }
  },
  "required": [
    "payment_id",
    "end_to_end_id",
    "history"
  ]
}

Obter Histórico do Pagamento
GET`/api/v1/payments/{id}/history`

Recupera o histórico de status do pagamento.

URI Parameters

HideShow

id: string (required) Example: 1
ID do Pagamento ou EndToEndId

Saldo Atual ¶

GET https://api.dictra.com.br/api/v1/balance?ispb=12345678

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "available": "1000000.00",
  "blocked": "50000.00",
  "projected": "950000.00",
  "pending_debits": "30000.00",
  "pending_credits": "20000.00",
  "as_of": "2026-01-24T10:30:00Z",
  "source": "bacen"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "available": {
      "type": "string",
      "description": "String decimal"
    },
    "blocked": {
      "type": "string"
    },
    "projected": {
      "type": "string"
    },
    "pending_debits": {
      "type": "string"
    },
    "pending_credits": {
      "type": "string"
    },
    "as_of": {
      "type": "string"
    },
    "source": {
      "type": "string",
      "description": "cache, bacen, calculated"
    }
  },
  "required": [
    "ispb",
    "available",
    "blocked",
    "projected",
    "pending_debits",
    "pending_credits",
    "as_of",
    "source"
  ]
}

Obter Saldo Atual
GET`/api/v1/balance{?ispb}`

Recupera o saldo disponível atual de um participante.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
ISPB do participante de 8 dígitos

Saldo Projetado ¶

GET https://api.dictra.com.br/api/v1/balance/projected?ispb=12345678

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "current_available": "1000000.00",
  "pending_debits": "30000.00",
  "pending_credits": "20000.00",
  "projected_amount": "990000.00",
  "pending_count": 45,
  "as_of": "2026-01-24T10:30:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "current_available": {
      "type": "string"
    },
    "pending_debits": {
      "type": "string"
    },
    "pending_credits": {
      "type": "string"
    },
    "projected_amount": {
      "type": "string"
    },
    "pending_count": {
      "type": "number"
    },
    "as_of": {
      "type": "string"
    }
  },
  "required": [
    "current_available",
    "pending_debits",
    "pending_credits",
    "projected_amount",
    "pending_count",
    "as_of"
  ]
}

Obter Saldo Projetado
GET`/api/v1/balance/projected{?ispb}`

Recupera o saldo projetado com transações pendentes.

URI Parameters

HideShow

ispb: string (required) Example: 12345678

Saldo do Dia Anterior ¶

GET https://api.dictra.com.br/api/v1/balance/previous-day?ispb=12345678

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "date": "2026-01-23",
  "opening_balance": "950000.00",
  "closing_balance": "1000000.00",
  "total_credits": "200000.00",
  "total_debits": "150000.00",
  "transaction_count": 342
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "date": {
      "type": "string"
    },
    "opening_balance": {
      "type": "string"
    },
    "closing_balance": {
      "type": "string"
    },
    "total_credits": {
      "type": "string"
    },
    "total_debits": {
      "type": "string"
    },
    "transaction_count": {
      "type": "number"
    }
  },
  "required": [
    "ispb",
    "date",
    "opening_balance",
    "closing_balance",
    "total_credits",
    "total_debits",
    "transaction_count"
  ]
}

Obter Saldo do Dia Anterior
GET`/api/v1/balance/previous-day{?ispb}`

Recupera o saldo de fechamento do dia anterior.

URI Parameters

HideShow

ispb: string (required) Example: 12345678

Histórico de Saldo ¶

GET https://api.dictra.com.br/api/v1/balance/history?ispb=12345678&from_date=2026-01-01&to_date=2026-01-24

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "from_date": "2026-01-01",
  "to_date": "2026-01-24",
  "entries": [
    {
      "date": "2026-01-23",
      "opening_balance": "950000.00",
      "closing_balance": "1000000.00",
      "total_credits": "200000.00",
      "total_debits": "150000.00",
      "transaction_count": 342
    },
    {
      "date": "2026-01-24",
      "opening_balance": "1000000.00",
      "closing_balance": "1050000.00",
      "total_credits": "250000.00",
      "total_debits": "200000.00",
      "transaction_count": 387
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "from_date": {
      "type": "string"
    },
    "to_date": {
      "type": "string"
    },
    "entries": {
      "type": "array"
    }
  },
  "required": [
    "ispb",
    "from_date",
    "to_date",
    "entries"
  ]
}

Obter Histórico de Saldo
GET`/api/v1/balance/history{?ispb,from_date,to_date}`

Recupera dados históricos de saldo.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
from_date: string (required) Example: 2026-01-01
Data ISO 8601
to_date: string (required) Example: 2026-01-24

Consulta de Saldo ¶

POST https://api.dictra.com.br/api/v1/balance/query

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "ispb": "12345678",
  "query_type": "CURRENT",
  "requested_msg": "camt.052",
  "balance_type": "CLBD",
  "reporting_from": "2026-01-24T00:00:00Z",
  "reporting_to": "2026-01-24T23:59:59Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "query_type": {
      "type": "string",
      "enum": [
        "CURRENT",
        "PROJECTED",
        "PREVIOUS_DAY",
        "HISTORY",
        "INTRADAY"
      ]
    },
    "requested_msg": {
      "type": "string",
      "enum": [
        "camt.052",
        "camt.053",
        "camt.054"
      ]
    },
    "balance_type": {
      "type": "string",
      "enum": [
        "CLBD",
        "XPCD",
        "OPBD",
        "ITAV"
      ]
    },
    "reporting_from": {
      "type": "string"
    },
    "reporting_to": {
      "type": "string"
    }
  },
  "required": [
    "ispb",
    "query_type",
    "requested_msg",
    "balance_type",
    "reporting_from"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "message_id": "M1234567820260124103012345abcde",
  "ispb": "12345678",
  "query_type": "CURRENT",
  "status": "PENDING",
  "created_at": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "ispb": {
      "type": "string"
    },
    "query_type": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "message_id",
    "ispb",
    "query_type",
    "status",
    "created_at"
  ]
}

Criar Consulta de Saldo
POST`/api/v1/balance/query`

Cria uma nova solicitação de consulta de saldo camt.060 para o BACEN.

Lista de Consultas de Saldo ¶

GET https://api.dictra.com.br/api/v1/balance/queries?ispb=12345678&status=COMPLETED

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "queries": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "message_id": "M1234567820260124103012345abcde",
      "ispb": "12345678",
      "query_type": "CURRENT",
      "status": "COMPLETED",
      "created_at": "2026-01-24T10:30:12Z",
      "updated_at": "2026-01-24T10:30:15Z"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "queries": {
      "type": "array"
    }
  },
  "required": [
    "queries"
  ]
}

Listar Consultas de Saldo
GET`/api/v1/balance/queries{?ispb,status}`

Lista solicitações de consulta de saldo.

URI Parameters

HideShow

ispb: string (optional) Example: 12345678
status: string (optional) Example: COMPLETED
Choices: PENDING PROCESSING COMPLETED FAILED

Detalhes da Consulta de Saldo ¶

GET https://api.dictra.com.br/api/v1/balance/queries/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

Operações de pagamento em lote usando mensagens ISO 20022 pain.001.

**Limites:**

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "ispb": {
      "type": "string"
    },
    "query_type": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "response_data": {
      "type": "object",
      "properties": {
        "message_id": {
          "type": "string"
        },
        "created_at": {
          "type": "string"
        },
        "account_ispb": {
          "type": "string"
        },
        "balances": {
          "type": "array"
        },
        "total_entries": {
          "type": "number"
        },
        "total_credit_sum": {
          "type": "string"
        },
        "total_debit_sum": {
          "type": "string"
        }
      },
      "required": [
        "message_id",
        "created_at",
        "account_ispb",
        "balances",
        "total_entries",
        "total_credit_sum",
        "total_debit_sum"
      ]
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "message_id",
    "ispb",
    "query_type",
    "status",
    "created_at",
    "updated_at"
  ]
}

Obter Consulta de Saldo
GET`/api/v1/balance/queries/{id}`

Recupera detalhes da consulta de saldo e resposta.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Consulta

Lotes ¶

POST https://api.dictra.com.br/api/v1/batches

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "batch_id": "BATCH001",
  "participant_ispb": "12345678",
  "requested_execution_date": "2026-01-24",
  "payments": [
    {
      "local_instrument": "MANU",
      "amount": 10000,
      "currency": "BRL",
      "debtor": {
        "ispb": "12345678",
        "account_no": "00001234567",
        "account_type": "CACC",
        "document": "12345678901"
      },
      "creditor": {
        "ispb": "87654321",
        "account_no": "00009876543",
        "account_type": "CACC",
        "document": "98765432100"
      }
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "batch_id": {
      "type": "string"
    },
    "participant_ispb": {
      "type": "string"
    },
    "requested_execution_date": {
      "type": "string"
    },
    "payments": {
      "type": "array",
      "description": "Máx 10 itens"
    }
  },
  "required": [
    "batch_id",
    "participant_ispb",
    "requested_execution_date",
    "payments"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": "BATCH001",
  "message_id": "M1234567820260124103012345abcde",
  "participant_ispb": "12345678",
  "status": "PENDING",
  "total_amount": 100000,
  "item_count": 10,
  "created_at": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "batch_id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "participant_ispb": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "total_amount": {
      "type": "number"
    },
    "item_count": {
      "type": "number"
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "batch_id",
    "message_id",
    "participant_ispb",
    "status",
    "total_amount",
    "item_count",
    "created_at"
  ]
}

Criar Lote
POST`/api/v1/batches`

Cria um novo pagamento em lote.

GET https://api.dictra.com.br/api/v1/batches?status=COMPLETED&limit=50&offset=0

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "batches": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "batch_id": "BATCH001",
      "message_id": "M1234567820260124103012345abcde",
      "status": "COMPLETED",
      "total_amount": 100000,
      "item_count": 10,
      "created_at": "2026-01-24T10:30:12Z"
    }
  ],
  "total": 45
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "batches": {
      "type": "array"
    },
    "total": {
      "type": "number"
    }
  },
  "required": [
    "batches",
    "total"
  ]
}

Listar Lotes
GET`/api/v1/batches{?status,limit,offset}`

Lista pagamentos em lote.

URI Parameters

HideShow

status: string (optional) Example: COMPLETED
Choices: PENDING PROCESSING COMPLETED FAILED
limit: number (optional) Example: 50
offset: number (optional) Example: 0

Detalhes do Lote ¶

GET https://api.dictra.com.br/api/v1/batches/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "batch_id": "BATCH001",
  "message_id": "M1234567820260124103012345abcde",
  "participant_ispb": "12345678",
  "status": "COMPLETED",
  "total_amount": 100000,
  "item_count": 10,
  "requested_execution_date": "2026-01-24",
  "created_at": "2026-01-24T10:30:12Z",
  "updated_at": "2026-01-24T10:30:20Z",
  "processed_at": "2026-01-24T10:30:20Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "batch_id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "participant_ispb": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "total_amount": {
      "type": "number"
    },
    "item_count": {
      "type": "number"
    },
    "requested_execution_date": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    },
    "processed_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "batch_id",
    "message_id",
    "participant_ispb",
    "status",
    "total_amount",
    "item_count",
    "requested_execution_date",
    "created_at",
    "updated_at"
  ]
}

Obter Lote
GET`/api/v1/batches/{id}`

Recupera detalhes do lote.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID do Lote

Itens do Lote ¶

GET https://api.dictra.com.br/api/v1/batches/550e8400-e29b-41d4-a716-446655440000/items

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

Operações de pagamento recorrente (PIX Automático) usando mensagens ISO 20022 pain.

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "batch_id": {
      "type": "string"
    },
    "items": {
      "type": "array"
    }
  },
  "required": [
    "batch_id",
    "items"
  ]
}

Obter Itens do Lote
GET`/api/v1/batches/{id}/items`

Recupera itens dentro de um lote.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID do Lote

Recorrências ¶

POST https://api.dictra.com.br/api/v1/recurrence

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "mandate_id": "MANDATE123456789012345678901234",
  "participant_ispb": "12345678",
  "debtor": {
    "ispb": "12345678",
    "account": "00001234567",
    "account_type": "CACC",
    "name": "João Silva",
    "document": "12345678901"
  },
  "creditor": {
    "ispb": "87654321",
    "account": "00009876543",
    "account_type": "CACC",
    "name": "Maria Oliveira",
    "document": "98765432100",
    "pix_key": "maria@example.com"
  },
  "amount": "100.00",
  "currency": "BRL",
  "frequency": "DAILY",
  "start_date": "2026-01-24T00:00:00Z",
  "end_date": "2027-01-24T00:00:00Z",
  "max_executions": 12,
  "description": "Assinatura mensal"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mandate_id": {
      "type": "string",
      "description": "26-35 caracteres"
    },
    "participant_ispb": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "account_type",
        "name",
        "document"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        },
        "pix_key": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "account_type",
        "name",
        "document"
      ]
    },
    "amount": {
      "type": "string",
      "description": "String decimal"
    },
    "currency": {
      "type": "string"
    },
    "frequency": {
      "type": "string",
      "enum": [
        "DAILY",
        "WEEKLY",
        "MONTHLY",
        "YEARLY"
      ]
    },
    "start_date": {
      "type": "string"
    },
    "end_date": {
      "type": "string"
    },
    "max_executions": {
      "type": "number"
    },
    "description": {
      "type": "string"
    }
  },
  "required": [
    "mandate_id",
    "participant_ispb",
    "debtor",
    "creditor",
    "amount",
    "currency",
    "frequency",
    "start_date"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mandate_id": "MANDATE123456789012345678901234",
  "participant_ispb": "12345678",
  "amount": "100.00",
  "frequency": "MONTHLY",
  "start_date": "2026-01-24T00:00:00Z",
  "end_date": "2027-01-24T00:00:00Z",
  "next_execution": "2026-01-24T00:00:00Z",
  "execution_count": 0,
  "max_executions": 12,
  "status": "PENDING_APPROVAL",
  "created_at": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "mandate_id": {
      "type": "string"
    },
    "participant_ispb": {
      "type": "string"
    },
    "amount": {
      "type": "string"
    },
    "frequency": {
      "type": "string"
    },
    "start_date": {
      "type": "string"
    },
    "end_date": {
      "type": "string"
    },
    "next_execution": {
      "type": "string"
    },
    "execution_count": {
      "type": "number"
    },
    "max_executions": {
      "type": "number"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "mandate_id",
    "participant_ispb",
    "amount",
    "frequency",
    "start_date",
    "next_execution",
    "execution_count",
    "status",
    "created_at"
  ]
}

Criar Recorrência
POST`/api/v1/recurrence`

Cria um novo pagamento recorrente (pain.009).

GET https://api.dictra.com.br/api/v1/recurrence?status=ACTIVE&limit=50&offset=0

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "recurrences": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "mandate_id": "MANDATE123456789012345678901234",
      "amount": "100.00",
      "frequency": "MONTHLY",
      "next_execution": "2026-02-24T00:00:00Z",
      "execution_count": 1,
      "status": "ACTIVE"
    }
  ],
  "total": 23
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recurrences": {
      "type": "array"
    },
    "total": {
      "type": "number"
    }
  },
  "required": [
    "recurrences",
    "total"
  ]
}

Listar Recorrências
GET`/api/v1/recurrence{?status,limit,offset}`

Lista pagamentos recorrentes.

URI Parameters

HideShow

status: string (optional) Example: ACTIVE
Choices: PENDING_APPROVAL ACTIVE PAUSED COMPLETED CANCELLED
limit: number (optional) Example: 50
offset: number (optional) Example: 0

Detalhes da Recorrência ¶

GET https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mandate_id": "MANDATE123456789012345678901234",
  "participant_ispb": "12345678",
  "debtor": {
    "ispb": "12345678",
    "account": "00001234567",
    "account_type": "CACC",
    "name": "João Silva",
    "document": "12345678901"
  },
  "creditor": {
    "ispb": "87654321",
    "account": "00009876543",
    "account_type": "CACC",
    "name": "Maria Oliveira",
    "document": "98765432100"
  },
  "amount": "100.00",
  "frequency": "MONTHLY",
  "start_date": "2026-01-24T00:00:00Z",
  "end_date": "2027-01-24T00:00:00Z",
  "next_execution": "2026-02-24T00:00:00Z",
  "execution_count": 1,
  "max_executions": 12,
  "status": "ACTIVE",
  "created_at": "2026-01-24T10:30:12Z",
  "updated_at": "2026-01-24T11:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "mandate_id": {
      "type": "string"
    },
    "participant_ispb": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "account_type",
        "name",
        "document"
      ]
    },
    "creditor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "account_type": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "account_type",
        "name",
        "document"
      ]
    },
    "amount": {
      "type": "string"
    },
    "frequency": {
      "type": "string"
    },
    "start_date": {
      "type": "string"
    },
    "end_date": {
      "type": "string"
    },
    "next_execution": {
      "type": "string"
    },
    "execution_count": {
      "type": "number"
    },
    "max_executions": {
      "type": "number"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "mandate_id",
    "participant_ispb",
    "debtor",
    "creditor",
    "amount",
    "frequency",
    "start_date",
    "next_execution",
    "execution_count",
    "status",
    "created_at",
    "updated_at"
  ]
}

Obter Recorrência
GET`/api/v1/recurrence/{id}`

Recupera detalhes da recorrência.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

PUT https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "amount": "150.00",
  "frequency": "WEEKLY",
  "end_date": "2027-06-24T00:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "string"
    },
    "frequency": {
      "type": "string"
    },
    "end_date": {
      "type": "string"
    }
  }
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "mandate_id": "MANDATE123456789012345678901234",
  "amount": "150.00",
  "frequency": "WEEKLY",
  "status": "ACTIVE",
  "updated_at": "2026-01-24T11:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "mandate_id": {
      "type": "string"
    },
    "amount": {
      "type": "string"
    },
    "frequency": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "mandate_id",
    "amount",
    "frequency",
    "status",
    "updated_at"
  ]
}

Atualizar Recorrência
PUT`/api/v1/recurrence/{id}`

Atualiza recorrência (pain.012 - MandateAmendment).

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

Pausar Recorrência ¶

POST https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000/pause

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "PAUSED",
  "paused_at": "2026-01-24T11:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "paused_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "paused_at"
  ]
}

Pausar Recorrência
POST`/api/v1/recurrence/{id}/pause`

Pausa uma recorrência ativa.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

Retomar Recorrência ¶

POST https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000/resume

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "ACTIVE",
  "resumed_at": "2026-01-24T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "resumed_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "resumed_at"
  ]
}

Retomar Recorrência
POST`/api/v1/recurrence/{id}/resume`

Retoma uma recorrência pausada.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

Cancelar Recorrência ¶

POST https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000/cancel

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "reason_code": "CUST",
  "reason_description": "Solicitação do cliente"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "reason_code": {
      "type": "string"
    },
    "reason_description": {
      "type": "string"
    }
  },
  "required": [
    "reason_code"
  ]
}

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "CANCELLED",
  "reason_code": "CUST",
  "cancelled_at": "2026-01-24T12:00:00Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "reason_code": {
      "type": "string"
    },
    "cancelled_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "status",
    "reason_code",
    "cancelled_at"
  ]
}

Cancelar Recorrência
POST`/api/v1/recurrence/{id}/cancel`

Cancela uma recorrência (pain.011 - MandateCancellation).

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

Execuções da Recorrência ¶

GET https://api.dictra.com.br/api/v1/recurrence/550e8400-e29b-41d4-a716-446655440000/executions

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

Operações de devolução de pagamento usando mensagens ISO 20022 pacs.004.

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "recurrence_id": {
      "type": "string"
    },
    "executions": {
      "type": "array"
    }
  },
  "required": [
    "recurrence_id",
    "executions"
  ]
}

Obter Histórico de Execução
GET`/api/v1/recurrence/{id}/executions`

Recupera histórico de execução de uma recorrência.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Recorrência

Devoluções ¶

GET https://api.dictra.com.br/api/v1/returns?status=SETTLED&limit=50&offset=0

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "returns": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "return_id": "D1234567820260124103012345abcde",
      "original_end_to_end_id": "E8765432120260123103012345abcde",
      "amount": "100.00",
      "reason_code": "FR01",
      "status": "SETTLED",
      "requested_at": "2026-01-24T10:30:12Z"
    }
  ],
  "total": 34
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "returns": {
      "type": "array"
    },
    "total": {
      "type": "number"
    }
  },
  "required": [
    "returns",
    "total"
  ]
}

Listar Devoluções
GET`/api/v1/returns{?status,limit,offset}`

Lista solicitações de devolução.

URI Parameters

HideShow

status: string (optional) Example: SETTLED
Choices: REQUESTED SENT ACCEPTED SETTLED REJECTED FAILED CANCELLED
limit: number (optional) Example: 50
offset: number (optional) Example: 0

Detalhes da Devolução ¶

GET https://api.dictra.com.br/api/v1/returns/550e8400-e29b-41d4-a716-446655440000

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "D1234567820260124103012345abcde",
  "message_id": "M1234567820260124103012345abcde",
  "original_payment_id": 123,
  "original_end_to_end_id": "E8765432120260123103012345abcde",
  "original_message_id": "M8765432120260123103012345abcde",
  "original_amount": 10000,
  "amount": "100.00",
  "currency": "BRL",
  "reason_code": "FR01",
  "reason_text": "Fraude detectada",
  "requestor": {
    "ispb": "12345678",
    "account": "00001234567",
    "name": "João Silva",
    "document": "12345678901"
  },
  "counterparty": {
    "ispb": "87654321",
    "account": "00009876543",
    "name": "Maria Oliveira",
    "document": "98765432100"
  },
  "status": "SETTLED",
  "requested_at": "2026-01-24T10:30:12Z",
  "settled_at": "2026-01-24T10:30:20Z",
  "created_at": "2026-01-24T10:30:12Z",
  "updated_at": "2026-01-24T10:30:20Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "return_id": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "original_payment_id": {
      "type": "number"
    },
    "original_end_to_end_id": {
      "type": "string"
    },
    "original_message_id": {
      "type": "string"
    },
    "original_amount": {
      "type": "number"
    },
    "amount": {
      "type": "string"
    },
    "currency": {
      "type": "string"
    },
    "reason_code": {
      "type": "string"
    },
    "reason_text": {
      "type": "string"
    },
    "requestor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "name",
        "document"
      ]
    },
    "counterparty": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string"
        },
        "account": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string"
        }
      },
      "required": [
        "ispb",
        "account",
        "name",
        "document"
      ]
    },
    "status": {
      "type": "string"
    },
    "requested_at": {
      "type": "string"
    },
    "settled_at": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "return_id",
    "message_id",
    "original_payment_id",
    "original_end_to_end_id",
    "original_message_id",
    "original_amount",
    "amount",
    "currency",
    "reason_code",
    "requestor",
    "counterparty",
    "status",
    "requested_at",
    "created_at",
    "updated_at"
  ]
}

Obter Devolução
GET`/api/v1/returns/{id}`

Recupera detalhes da devolução.

URI Parameters

HideShow

id: string (required) Example: 550e8400-e29b-41d4-a716-446655440000
ID da Devolução

Devolução de Pagamento ¶

POST https://api.dictra.com.br/api/v1/payments/123/return

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "amount": "100.00",
  "reason_code": "AC03",
  "reason_text": "Fraude detectada pelo MED 2.0"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Devolução total ou parcial"
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "AC03",
        "AC04",
        "AC06",
        "AM04",
        "AM09",
        "FR01",
        "MD06",
        "SL02",
        "RR04"
      ],
      "description": "Código de motivo BACEN"
    },
    "reason_text": {
      "type": "string"
    }
  },
  "required": [
    "amount",
    "reason_code"
  ]
}

Responses201

Headers

Content-Type: application/json

Body

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "return_id": "D1234567820260124103012345abcde",
  "original_payment_id": 123,
  "original_end_to_end_id": "E8765432120260123103012345abcde",
  "amount": "100.00",
  "reason_code": "FR01",
  "status": "REQUESTED",
  "created_at": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "id": {
      "type": "string"
    },
    "return_id": {
      "type": "string"
    },
    "original_payment_id": {
      "type": "number"
    },
    "original_end_to_end_id": {
      "type": "string"
    },
    "amount": {
      "type": "string"
    },
    "reason_code": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "created_at": {
      "type": "string"
    }
  },
  "required": [
    "id",
    "return_id",
    "original_payment_id",
    "original_end_to_end_id",
    "amount",
    "reason_code",
    "status",
    "created_at"
  ]
}

Criar Devolução
POST`/api/v1/payments/{id}/return`

Cria uma devolução para um pagamento.

URI Parameters

HideShow

id: string (required) Example: 123
ID do Pagamento Original ou EndToEndId

Lista de Devoluções de Pagamento ¶

GET https://api.dictra.com.br/api/v1/payments/123/returns

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "payment_id": 123,
  "original_end_to_end_id": "E8765432120260123103012345abcde",
  "returns": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "return_id": "D1234567820260124103012345abcde",
      "amount": "50.00",
      "reason_code": "AM09",
      "status": "SETTLED",
      "created_at": "2026-01-24T10:30:12Z"
    }
  ]
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payment_id": {
      "type": "number"
    },
    "original_end_to_end_id": {
      "type": "string"
    },
    "returns": {
      "type": "array"
    }
  },
  "required": [
    "payment_id",
    "original_end_to_end_id",
    "returns"
  ]
}

Listar Devoluções por Pagamento
GET`/api/v1/payments/{id}/returns`

Lista todas as devoluções de um pagamento específico.

URI Parameters

HideShow

id: string (required) Example: 123
ID do Pagamento ou EndToEndId

Resumo de Devolução de Pagamento ¶

GET https://api.dictra.com.br/api/v1/payments/123/return-summary

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

{
  "payment_id": 123,
  "original_amount": "100.00",
  "total_returned": "50.00",
  "remaining_amount": "50.00",
  "return_count": 1,
  "can_return": true,
  "last_return_at": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "payment_id": {
      "type": "number"
    },
    "original_amount": {
      "type": "string"
    },
    "total_returned": {
      "type": "string"
    },
    "remaining_amount": {
      "type": "string"
    },
    "return_count": {
      "type": "number"
    },
    "can_return": {
      "type": "boolean"
    },
    "last_return_at": {
      "type": "string"
    }
  },
  "required": [
    "payment_id",
    "original_amount",
    "total_returned",
    "remaining_amount",
    "return_count",
    "can_return"
  ]
}

Obter Resumo de Devolução
GET`/api/v1/payments/{id}/return-summary`

Obtém resumo de devolução de um pagamento.

URI Parameters

HideShow

id: string (required) Example: 123
ID do Pagamento ou EndToEndId

Conectividade ¶

Operações de teste de conectividade BACEN.

Teste de Echo ¶

POST https://api.dictra.com.br/api/v1/echo

Requestsexample 1

Headers

Content-Type: application/json
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Body

{
  "ispb": "12345678"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    }
  },
  "required": [
    "ispb"
  ]
}

Responses200503

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "status": "success",
  "message_id": "ECHO1234567820260124103012345",
  "resource_id": "R1234567820260124103015abcdefgh",
  "latency_ms": 85,
  "timestamp": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "message_id": {
      "type": "string"
    },
    "resource_id": {
      "type": "string"
    },
    "latency_ms": {
      "type": "number"
    },
    "timestamp": {
      "type": "string"
    }
  },
  "required": [
    "ispb",
    "status",
    "message_id",
    "resource_id",
    "latency_ms",
    "timestamp"
  ]
}

Headers

Content-Type: application/json

Body

{
  "ispb": "12345678",
  "status": "failed",
  "error": "Serviço BACEN indisponível",
  "timestamp": "2026-01-24T10:30:12Z"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "ispb": {
      "type": "string"
    },
    "status": {
      "type": "string"
    },
    "error": {
      "type": "string"
    },
    "timestamp": {
      "type": "string"
    }
  },
  "required": [
    "ispb",
    "status",
    "error",
    "timestamp"
  ]
}

Echo
POST`/api/v1/echo`

Envia teste de echo/conectividade pibr.001 para o BACEN.

Generated by aglio on 24 Jan 2026

API Endpoint

Autenticação ¶

Fluxo de Mensagens ISO 20022 ¶

Tipos de Iniciação de Pagamento (LocalInstrument) ¶

Verificações de Saúde ¶

Liveness ¶

Headers

Body

Schema

Verificar LivenessGET/health

Readiness ¶

Headers

Body

Schema

Headers

Body

Schema

Verificar ReadinessGET/ready

Pagamentos Principais ¶

Coleção de Pagamentos ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Criar PagamentoPOST/api/v1/payments

Headers

Headers

Body

Schema

Listar PagamentosGET/api/v1/payments{?status,limit,offset}

Pagamento ¶

Headers

Headers

Body

Schema

Headers

Body

Schema

Obter PagamentoGET/api/v1/payments/{id}

Histórico do Pagamento ¶

Headers

Headers

Body

Schema

Obter Histórico do PagamentoGET/api/v1/payments/{id}/history

Saldo Atual ¶

Headers

Headers

Body

Schema

Obter Saldo AtualGET/api/v1/balance{?ispb}

Saldo Projetado ¶

Headers

Headers

Body

Schema

Obter Saldo ProjetadoGET/api/v1/balance/projected{?ispb}

Saldo do Dia Anterior ¶

Headers

Headers

Body

Schema

Obter Saldo do Dia AnteriorGET/api/v1/balance/previous-day{?ispb}

Histórico de Saldo ¶

Headers

Headers

Body

Schema

Obter Histórico de SaldoGET/api/v1/balance/history{?ispb,from_date,to_date}

Consulta de Saldo ¶

Headers

Body

Schema

Headers

Body

Autenticação

Fluxo de Mensagens ISO 20022

Tipos de Iniciação de Pagamento (LocalInstrument)

Verificar Liveness
GET`/health`

Verificar Readiness
GET`/ready`

Criar Pagamento
POST`/api/v1/payments`

Listar Pagamentos
GET`/api/v1/payments{?status,limit,offset}`

Obter Pagamento
GET`/api/v1/payments/{id}`

Obter Histórico do Pagamento
GET`/api/v1/payments/{id}/history`

Obter Saldo Atual
GET`/api/v1/balance{?ispb}`

Obter Saldo Projetado
GET`/api/v1/balance/projected{?ispb}`

Obter Saldo do Dia Anterior
GET`/api/v1/balance/previous-day{?ispb}`

Obter Histórico de Saldo
GET`/api/v1/balance/history{?ispb,from_date,to_date}`

Criar Consulta de Saldo
POST`/api/v1/balance/query`

Listar Consultas de Saldo
GET`/api/v1/balance/queries{?ispb,status}`

Obter Consulta de Saldo
GET`/api/v1/balance/queries/{id}`

Criar Lote
POST`/api/v1/batches`

Listar Lotes
GET`/api/v1/batches{?status,limit,offset}`

Obter Lote
GET`/api/v1/batches/{id}`

Obter Itens do Lote
GET`/api/v1/batches/{id}/items`

Criar Recorrência
POST`/api/v1/recurrence`

Listar Recorrências
GET`/api/v1/recurrence{?status,limit,offset}`

Obter Recorrência
GET`/api/v1/recurrence/{id}`

Atualizar Recorrência
PUT`/api/v1/recurrence/{id}`