SPI Service API

API Endpoint

https://api.dictra.com.br

The SPI (Sistema de Pagamentos Instantâneos) Service handles Brazilian instant payment processing via BACEN (Brazilian Central Bank). This API provides endpoints for creating PIX payments, querying balances, managing batch payments, recurring payments, and return operations.

Version: 1.0.0 Protocol: ISO 20022 (pacs.008, pacs.002, pacs.004, camt.060, pain.009, pain.011, pain.012) TPS Target: 1,500 transactions per second BACEN Reference: SPI Manual v5.11.1

Authentication

All API endpoints (except /health and /ready) require JWT authentication.

Authorization: Bearer <jwt_token>

ISO 20022 Message Flow

Payment Creation
    ↓
pacs.008 (Credit Transfer) → BACEN
    ↓
pacs.002 (Status Report) ← BACEN
    ↓
Payment Settled/Rejected

Payment Initiation Types (LocalInstrument)

Code	Name	PIX Key	TxId	EndToEndId Source	Token Correlation
MANU	Manual Entry	No	No	SPI-generated	No
DICT	PIX Key Lookup	Required	No	DICT-generated	Yes
QRES	QR Code Static	Required	≤25 chars	SPI-generated	No
QRDN	QR Code Dynamic	Required	26-35 chars	SPI-generated	No
INIC	Payment Initiator	Required	≤25 chars	SPI-generated	No
AUTO	PIX Automático	Optional	26-35 chars	SPI-generated	No
APDN	PIX Automático Dynamic	Optional	26-35 chars	SPI-generated	No
APES	PIX Automático Static	Optional	≤25 chars	SPI-generated	No

Important: Only DICT-initiated payments trigger token refund correlation with dict-service.

Health Checks ¶

Health and readiness probe endpoints.

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"
  ]
}

Check Liveness
GET`/health`

Returns service liveness status.

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"
  ]
}

Check Readiness
GET`/ready`

Returns service readiness status with dependency checks.

Core Payments ¶

PIX payment operations using ISO 20022 pacs.008 messages.

Payments Collection ¶

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": "Payment for services",
  "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": "Initiation type"
    },
    "priority_type": {
      "type": "string",
      "enum": [
        "PAGPRI",
        "PAGFRD",
        "PAGAGD"
      ],
      "description": "Payment priority"
    },
    "priority_id": {
      "type": "number",
      "description": "Priority ID (1=HIGH, 2=NORMAL)"
    },
    "purpose": {
      "type": "string",
      "enum": [
        "IPAY",
        "GSCB",
        "OTHR",
        "REFU"
      ],
      "description": "Transaction purpose"
    },
    "amount": {
      "type": "number",
      "description": "Amount in cents (R$ 100.00)"
    },
    "currency": {
      "type": "string"
    },
    "debtor": {
      "type": "object",
      "properties": {
        "ispb": {
          "type": "string",
          "description": "8-digit ISPB"
        },
        "name": {
          "type": "string"
        },
        "document": {
          "type": "string",
          "description": "CPF or 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": "PIX key (required for DICT, QRDN, QRES, INIC)"
        }
      },
      "required": [
        "ispb",
        "document",
        "account_no",
        "account_type"
      ]
    },
    "tx_id": {
      "type": "string",
      "description": "Transaction ID (required for QR/INIC)"
    },
    "initiating_party": {
      "type": "string",
      "description": "Required for INIC"
    },
    "description": {
      "type": "string",
      "description": "Max 140 chars"
    },
    "dict_end_to_end_id": {
      "type": "string",
      "description": "For DICT payments only"
    },
    "dict_correlation_id": {
      "type": "string",
      "description": "For token refund tracking"
    },
    "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 chars"
    },
    "message_id": {
      "type": "string",
      "description": "32 chars"
    },
    "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": "DICT payments require PIX key (CreditorProxy)"
}

Schema

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

Create Payment
POST`/api/v1/payments`

Creates a new PIX payment. Validation rules apply based on LocalInstrument type.

DICT Payments: EndToEndId must be provided from dict-service (token correlation). Other Types: EndToEndId is auto-generated by 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"
  ]
}

List Payments
GET`/api/v1/payments{?status,limit,offset}`

Lists payments with optional status filter.

URI Parameters

HideShow

status

string (optional) Example: ACSP

Filter by status

Choices: ENTRY_RECEIVED VALIDATED PENDING_BACEN SENT_TO_BACEN ACSP ACCC RJCT PDNG CANC

limit

number (optional) Example: 50

Max results (default: 50)

offset

number (optional) Example: 0

Pagination offset

Payment ¶

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": "Payment not found"
}

Schema

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

Get Payment
GET`/api/v1/payments/{id}`

Retrieves payment details by ID or EndToEndId.

URI Parameters

HideShow

id: string (required) Example: 1
Payment ID or EndToEndId

Payment History ¶

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

Requestsexample 1

Headers

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Responses200

Headers

Content-Type: application/json

Body

BACEN balance query operations using ISO 20022 camt.060 messages.

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"
  ]
}

Get Payment History
GET`/api/v1/payments/{id}/history`

Retrieves payment status history.

URI Parameters

HideShow

id: string (required) Example: 1
Payment ID or EndToEndId

Current Balance ¶

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": "Decimal string"
    },
    "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"
  ]
}

Get Current Balance
GET`/api/v1/balance{?ispb}`

Retrieves current available balance for a participant.

URI Parameters

HideShow

ispb: string (required) Example: 12345678
8-digit participant ISPB

Projected Balance ¶

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"
  ]
}

Get Projected Balance
GET`/api/v1/balance/projected{?ispb}`

Retrieves projected balance with pending transactions.

URI Parameters

HideShow

ispb: string (required) Example: 12345678

Previous Day Balance ¶

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"
  ]
}

Get Previous Day Balance
GET`/api/v1/balance/previous-day{?ispb}`

Retrieves previous day’s closing balance.

URI Parameters

HideShow

ispb: string (required) Example: 12345678

Balance History ¶

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"
  ]
}

Get Balance History
GET`/api/v1/balance/history{?ispb,from_date,to_date}`

Retrieves historical balance data.

URI Parameters

HideShow

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

Balance Query ¶

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"
  ]
}

Create Balance Query
POST`/api/v1/balance/query`

Creates a new camt.060 balance query request to BACEN.

Balance Queries List ¶

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"
  ]
}

List Balance Queries
GET`/api/v1/balance/queries{?ispb,status}`

Lists balance query requests.

URI Parameters

HideShow

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

Balance Query Details ¶

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

Batch payment operations using ISO 20022 pain.001 messages.

**Limits:**

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"
  ]
}

Get Balance Query
GET`/api/v1/balance/queries/{id}`

Retrieves balance query details and response.

URI Parameters

HideShow

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

Batches ¶

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": "Max 10 items"
    }
  },
  "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"
  ]
}

Create Batch
POST`/api/v1/batches`

Creates a new batch payment.

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"
  ]
}

List Batches
GET`/api/v1/batches{?status,limit,offset}`

Lists batch payments.

URI Parameters

HideShow

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

Batch Details ¶

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"
  ]
}

Get Batch
GET`/api/v1/batches/{id}`

Retrieves batch details.

URI Parameters

HideShow

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

Batch Items ¶

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

Recurring payment operations (PIX Automático) using ISO 20022 pain messages.

Schema

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

Get Batch Items
GET`/api/v1/batches/{id}/items`

Retrieves items within a batch.

URI Parameters

HideShow

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

Recurrences ¶

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": "Monthly subscription"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "mandate_id": {
      "type": "string",
      "description": "26-35 chars"
    },
    "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": "Decimal string"
    },
    "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"
  ]
}

Create Recurrence
POST`/api/v1/recurrence`

Creates a new recurring payment (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"
  ]
}

List Recurrences
GET`/api/v1/recurrence{?status,limit,offset}`

Lists recurring payments.

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

Recurrence Details ¶

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"
  ]
}

Get Recurrence
GET`/api/v1/recurrence/{id}`

Retrieves recurrence details.

URI Parameters

HideShow

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

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"
  ]
}

Update Recurrence
PUT`/api/v1/recurrence/{id}`

Updates recurrence (pain.012 - MandateAmendment).

URI Parameters

HideShow

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

Recurrence Pause ¶

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"
  ]
}

Pause Recurrence
POST`/api/v1/recurrence/{id}/pause`

Pauses an active recurrence.

URI Parameters

HideShow

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

Recurrence Resume ¶

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"
  ]
}

Resume Recurrence
POST`/api/v1/recurrence/{id}/resume`

Resumes a paused recurrence.

URI Parameters

HideShow

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

Recurrence Cancel ¶

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": "Customer request"
}

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"
  ]
}

Cancel Recurrence
POST`/api/v1/recurrence/{id}/cancel`

Cancels a recurrence (pain.011 - MandateCancellation).

URI Parameters

HideShow

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

Recurrence Executions ¶

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

Payment return operations using ISO 20022 pacs.004 messages.

Schema

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

Get Execution History
GET`/api/v1/recurrence/{id}/executions`

Retrieves execution history for a recurrence.

URI Parameters

HideShow

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

Returns ¶

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"
  ]
}

List Returns
GET`/api/v1/returns{?status,limit,offset}`

Lists return requests.

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

Return Details ¶

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": "Fraud detected",
  "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"
  ]
}

Get Return
GET`/api/v1/returns/{id}`

Retrieves return details.

URI Parameters

HideShow

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

Payment Return ¶

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": "Fraud detected by MED 2.0"
}

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "amount": {
      "type": "string",
      "description": "Full or partial return"
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "AC03",
        "AC04",
        "AC06",
        "AM04",
        "AM09",
        "FR01",
        "MD06",
        "SL02",
        "RR04"
      ],
      "description": "BACEN return reason code"
    },
    "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"
  ]
}

Create Return
POST`/api/v1/payments/{id}/return`

Creates a return for a payment.

URI Parameters

HideShow

id: string (required) Example: 123
Original payment ID or EndToEndId

Payment Returns List ¶

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"
  ]
}

List Returns by Payment
GET`/api/v1/payments/{id}/returns`

Lists all returns for a specific payment.

URI Parameters

HideShow

id: string (required) Example: 123
Payment ID or EndToEndId

Payment Return Summary ¶

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"
  ]
}

Get Return Summary
GET`/api/v1/payments/{id}/return-summary`

Gets return summary for a payment.

URI Parameters

HideShow

id: string (required) Example: 123
Payment ID or EndToEndId

Connectivity ¶

BACEN connectivity test operations.

Echo Test ¶

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": "BACEN service unavailable",
  "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`

Sends pibr.001 echo/connectivity test to BACEN.

Generated by aglio on 24 Jan 2026

API Endpoint

Authentication ¶

ISO 20022 Message Flow ¶

Payment Initiation Types (LocalInstrument) ¶

Health Checks ¶

Liveness ¶

Headers

Body

Schema

Check LivenessGET/health

Readiness ¶

Headers

Body

Schema

Headers

Body

Schema

Check ReadinessGET/ready

Core Payments ¶

Payments Collection ¶

Headers

Body

Schema

Headers

Body

Schema

Headers

Body

Schema

Create PaymentPOST/api/v1/payments

Headers

Headers

Body

Schema

List PaymentsGET/api/v1/payments{?status,limit,offset}

Payment ¶

Headers

Headers

Body

Schema

Headers

Body

Schema

Get PaymentGET/api/v1/payments/{id}

Payment History ¶

Headers

Headers

Body

Schema

Get Payment HistoryGET/api/v1/payments/{id}/history

Current Balance ¶

Headers

Headers

Body

Schema

Get Current BalanceGET/api/v1/balance{?ispb}

Projected Balance ¶

Headers

Headers

Body

Schema

Get Projected BalanceGET/api/v1/balance/projected{?ispb}

Previous Day Balance ¶

Headers

Headers

Body

Schema

Get Previous Day BalanceGET/api/v1/balance/previous-day{?ispb}

Balance History ¶

Headers

Headers

Body

Schema

Get Balance HistoryGET/api/v1/balance/history{?ispb,from_date,to_date}

Balance Query ¶

Headers

Body

Schema

Headers

Body

Authentication

ISO 20022 Message Flow

Payment Initiation Types (LocalInstrument)

Check Liveness
GET`/health`

Check Readiness
GET`/ready`

Create Payment
POST`/api/v1/payments`

List Payments
GET`/api/v1/payments{?status,limit,offset}`

Get Payment
GET`/api/v1/payments/{id}`

Get Payment History
GET`/api/v1/payments/{id}/history`

Get Current Balance
GET`/api/v1/balance{?ispb}`

Get Projected Balance
GET`/api/v1/balance/projected{?ispb}`

Get Previous Day Balance
GET`/api/v1/balance/previous-day{?ispb}`

Get Balance History
GET`/api/v1/balance/history{?ispb,from_date,to_date}`

Create Balance Query
POST`/api/v1/balance/query`

List Balance Queries
GET`/api/v1/balance/queries{?ispb,status}`

Get Balance Query
GET`/api/v1/balance/queries/{id}`

Create Batch
POST`/api/v1/batches`

List Batches
GET`/api/v1/batches{?status,limit,offset}`

Get Batch
GET`/api/v1/batches/{id}`

Get Batch Items
GET`/api/v1/batches/{id}/items`

Create Recurrence
POST`/api/v1/recurrence`

List Recurrences
GET`/api/v1/recurrence{?status,limit,offset}`

Get Recurrence
GET`/api/v1/recurrence/{id}`

Update Recurrence
PUT`/api/v1/recurrence/{id}`