Skip to content
/
Get Account Statement

ConnectPSP API (2.2.0)

ConnectPSP is a PIX payment gateway designed for high-throughput platforms such as digital wallets, betting companies, and fintechs.

This API allows you to:

  • 💸 Receive payments via PIX (Cash-In) — standard QR Code or OpenFinance
  • 🏦 Send payments via PIX key or bank account data (Cash-Out)
  • 📊 Manage your wallet — check consolidated balances and rebalance between transactional and proprietary accounts
  • 🪝 Receive real-time events via Webhooks as transactions progress

Authentication

All endpoints (except POST /auth/token) require two headers:

HeaderDescription
AuthorizationBearer <jwt_token> — obtained from POST /auth/token
ApplicationTokenFixed GUID token that identifies your integration

For financial operations (Cash-Out, Rebalance), an additional header is required:

HeaderDescription
DigitalSignatureHMAC-SHA256 hash of your JWT + CryptoToken. See Authentication Guide

Idempotency

X-Idempotency-Key is optional on POST /cash-in and POST /cash-out, and recommended (a UUID v4 per operation). With it, a network retry returns the original response instead of creating a second transaction. Without it, the request is processed normally and externalReference still blocks duplicates with 409 DUPLICATED_EXTERNAL_REFERENCE. See the Authentication Guide for the full rules.

Recommended integration order

PhaseWhat to confirm first
SetupCredentials, environment, headers, and webhook readiness in Initial Setup
AuthenticationJWT generation and DigitalSignature rules in the Authentication Guide
TransactionsYour first Cash-In or Cash-Out flow with idempotency and webhook validation
Download OpenAPI description
index.json
index.yaml
Overview
ConnectPSP Support
suporte@connectpsp.com
Languages
Servers
Staging Environment (Testing)
https://api.homologacao.connectpsp.com

Authentication

Obtain JWT tokens to authenticate all other requests.

Operations

Cash-In

Generate and manage inbound PIX payments. Supports standard QR Code and OpenFinance flows.

Operations

Cash-Out

Request and track outbound PIX payments to any Brazilian bank account.

Operations

Account

View consolidated wallet balances across all settlement partners and manage rebalancing between transactional and proprietary accounts.

Operations

Rebalance Wallet

Request

Synchronizes your Transactional account to match the total exposure you report.

How it works:

  • If targetAmount is greater than the current transactional balance → funds are pulled from the Proprietary account (Top-up)
  • If targetAmount is less than the current transactional balance → excess funds are swept back to the Proprietary account

The targetAmount represents the total exposure of your platform (sum of all user wallet balances + in-flight bets).

This endpoint requires the DigitalSignature header.

Security
bearerAuth
Headers
ApplicationTokenstringrequired

Fixed GUID that uniquely identifies your integration. Provided during ConnectPSP onboarding.

Example: {{ApplicationToken}}
DigitalSignaturestringrequired

HMAC-SHA256 hash of the JWT token + your CryptoToken. Required for sensitive operations. See the Authentication Guide for the exact computation steps.

Example: {{DigitalSignature}}
Bodyapplication/jsonrequired
targetAmountnumber(decimal)>= 0.01required

The target transactional balance (in BRL) representing your total current user exposure (sum of all user wallet balances + in-flight operations). ConnectPSP will automatically calculate the direction (Top-up or Sweep).

Example: 1000000
curl -X POST https://api.homologacao.connectpsp.com/account/rebalance \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>" \
  -H "DigitalSignature: <computed-signature>" \
  -H "Content-Type: application/json" \
  -d '{ "targetAmount": 1000000.00 }'

Responses

Rebalancing completed successfully.

Bodyapplication/json
successboolean
Example: true
messagestring
Example: "Rebalancing completed successfully."
Response
application/json
{
  "success": true,
  "message": "Rebalancing completed successfully."
}

Get Account Statement

Request

Returns the bank statement of one of your accounts for a period, oldest first by default. Pass order=desc for newest first.

This is the raw banking ledger — every credit and debit that hit the account at the settlement partner, including entries that did not originate from a Cash-In or Cash-Out you created (fees, internal transfers, refunds).

Account ownership

The account must belong to the client behind your credentials. An account owned by someone else returns exactly the same 404 as an account that does not exist — we never confirm the existence of an account that is not yours.

Available period

Statement data is available from a start date set for each client. A from earlier than that date returns 422 LIST_FROM_BEFORE_CUTOFF, and the detail states the first available date. It is the same for every account of the client, and a from on that date is accepted.

Cursor pagination

Send nextCursor from the previous response to fetch the next page. When the response comes back without nextCursor, you have reached the end of the period.

To walk backwards, send previousCursor in the very same cursor parameter — a cursor knows which way it goes. It is absent on the first page, so its absence is how you know you are at the start.

Keep from, to, limit and order identical across every page — only cursor changes. Both directions return the page in the order you asked for.

ℹ️ There is no total field. Counting the whole window would require a full scan, which is exactly what cursor pagination avoids. Every page costs the same, whether it is the first or the nine-hundredth — forwards or backwards.

Two things worth knowing

id is the entry identifier at the settlement partner and is stable over time. Store it if you need to match an entry later.

Dates carry milliseconds. Several entries can land in the same second on a busy account, and the millisecond is what lets you line an entry up with the cursor.

ℹ️ Null fields are omitted, not sent as null. This holds across the whole API. An entry with no counterparty document simply has no document key — read every optional field as "absent or present", never as "null or a value".

Security
bearerAuth
Path
numberstringrequired

Account number exactly as it appears in your onboarding data — letters, digits and hyphen, up to 32 characters.

Example: 123456789
Query
fromstringrequired

Start of the period, inclusive. Accepts a plain date (YYYY-MM-DD) or a full ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss).

Times without an explicit offset are read as America/Sao_Paulo (UTC-3). A plain date becomes 00:00:00.000 of that day in that timezone.

The period filters on when the entry hit the account at the settlement partner.

Example: from=2026-09-21
tostringrequired

End of the period, inclusive. Same format rules as from. A plain date becomes 23:59:59.999 of that day in America/Sao_Paulo.

Example: to=2026-09-21
limitinteger[ 1 .. 1000 ]

Maximum number of items per page. Defaults to 50, maximum 1000.

Default 50
Example: limit=50
cursorstring

Opaque cursor pointing at another page. Copy nextCursor (to go forward) or previousCursor (to go back) from the previous response verbatim. Do not build or parse it yourself, its format may change — a cursor already knows which way it goes.

Keep from, to, limit and order identical across every page of the same walk.

Example: cursor=MTM4OTU0NzI4MDAwMDAwMDB8YXxufFBIUVlST0I
orderstring

Sort direction by date. asc (default) returns the oldest first, desc the newest first.

⚠️ order cannot change mid-walk. The direction is baked into the cursor. Sending a different order alongside a cursor returns 422 LIST_ORDER_MISMATCH, because the next page would otherwise walk backwards — repeating rows you already had and skipping rows you never got. To change direction, start a new walk without cursor.

Default "asc"
Enum"asc""desc"
Example: order=asc
Headers
ApplicationTokenstringrequired

Fixed GUID that uniquely identifies your integration. Provided during ConnectPSP onboarding.

Example: {{ApplicationToken}}
curl "https://api.homologacao.connectpsp.com/account/123456789/statement?from=2026-08-01&to=2026-08-01&limit=3&order=desc" \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

A page of statement entries.

Bodyapplication/json
accountobject(StatementAccount)

The account the entries belong to, echoed back so you can confirm which account you read.

account.​numberstring
Example: "123456789"
account.​branchstring or null
Example: "0001"
account.​typestring

TRANSACTIONAL covers your users' exposure; PROPRIETARY is your reserve account.

Enum"TRANSACTIONAL""PROPRIETARY"
Example: "TRANSACTIONAL"
account.​bankobject
account.​bank.​ispbstring

ISPB of the settlement partner holding the account.

Example: "12345678"
account.​bank.​namestring or null
Example: "SETTLEMENT PARTNER A"
periodobject(StatementPeriod)

The period and direction actually applied, echoed back.

period.​fromstring
Example: "2026-08-01T00:00:00-03:00"
period.​tostring
Example: "2026-08-01T23:59:59-03:00"
period.​orderstring
Enum"asc""desc"
Example: "desc"
itemsArray of objects(StatementEntry)
items[].​idstring

Identifier of the entry at the settlement partner. Stable over time — safe to store and match against later.

Example: "3f9a1c7e5b2d4086a1c3e5f70928b4d6"
items[].​datestring

When the entry hit the account, in America/Sao_Paulo (UTC-3), with milliseconds. Several entries can share the same second on a busy account.

Example: "2026-08-01T14:32:10.445-03:00"
items[].​directionstring
Enum"CREDIT""DEBIT"
Example: "DEBIT"
items[].​typestring

Entry type, normalized across settlement partners so you only need one parser.

typeMeaning
PIX_INPIX received
PIX_OUTPIX sent
PIX_REFUND_INPIX refund received
PIX_REFUND_OUTPIX refund sent
TRANSFER_INNon-PIX transfer received
TRANSFER_OUTNon-PIX transfer sent
BILL_PAYMENTBill (boleto) payment
OTHERAnything else

ℹ️ Treat unknown values as OTHER. New settlement partners bring new labels; we map what we know and fall back to OTHER rather than failing the response. Your parser should never break on a value it has not seen.

Enum"PIX_IN""PIX_OUT""PIX_REFUND_IN""PIX_REFUND_OUT""TRANSFER_IN""TRANSFER_OUT""BILL_PAYMENT""OTHER"
Example: "PIX_OUT"
items[].​typeRawstring or null

The settlement partner's own label, untranslated — useful when you need the detail behind the normalized type.

Example: "PIX-TRANSFER"
items[].​amountnumber(double)

Always positive. Use direction for the sign.

Example: 50
items[].​balanceAfternumber or null(double)

Account balance right after this entry.

Example: 152340.75
items[].​descriptionstring or null
Example: "PIX withdrawal"
items[].​endToEndIdstring or null

PIX EndToEndId. Absent on entries that are not PIX.

Example: "E12345678202608011432s0a1b2c3d4e"
items[].​originalEndToEndIdstring or null

EndToEndId of the original transaction. Present only on PIX refunds.

Example: null
nextCursorstring

Opaque cursor for the next page. Absent when there are no more pages — that is how you know the walk is finished.

Example: "MTM4OTU0NzI4MDAwMDAwMDB8ZHxufDhjNGUyYTZkMGYxYjM5NTc"
previousCursorstring

Opaque cursor for the page before this one. Send it in the same cursor parameter. Absent on the first page — that is how you know you are at the start.

Example: "MTM4OTU0NzI4MDAwMDAwMDB8ZHxwfDNmOWExYzdlNWIyZDQwODY"
Response
application/json
{
  "account": {
    "number": "123456789",
    "branch": "0001",
    "type": "TRANSACTIONAL",
    "bank": { … }
  },
  "period": {
    "from": "2026-08-01T00:00:00-03:00",
    "to": "2026-08-01T23:59:59-03:00",
    "order": "desc"
  },
  "items": [
    { … },
    { … }
  ],
  "nextCursor": "MTM4OTU0NzI4MDAwMDAwMDB8ZHxufDhjNGUyYTZkMGYxYjM5NTc",
  "previousCursor": "MTM4OTU0NzI4MDAwMDAwMDB8ZHxwfDNmOWExYzdlNWIyZDQwODY"
}

Health

PIX Health tells you whether PIX is working for you right now, and who is at fault when it is not.

A statistical engine compares every 5-minute window of your PIX traffic with what is normal for that weekday and time over the last four weeks, and attributes any clear deviation to the platform, to a settlement partner, to a payer bank or to your own operation — always scoped to what you actually use.

Three endpoints, all read-only and all safe to poll once a minute:

EndpointUse it for
GET /health/pixThe picture of the moment: status per block plus the incidents open right now
GET /health/pix/incidentsHistory of confirmed incidents, paginated
GET /health/pix/incidents/{id}One incident with the evidence behind the verdict

None of them require DigitalSignature or X-Idempotency-Key — only Authorization and ApplicationToken.

Confirmed incidents are also pushed as webhooks (PIX_INCIDENT_DETECTED / UPDATED / RESOLVED), so you do not have to poll to be warned; see the Webhooks guide.

Operations