Skip to content
/
Summarize Cash-Ins

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

List Cash-Ins

Request

Returns Cash-In transactions created within a period, oldest first by default. Pass order=desc for newest first.

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. 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.

Each item carries the same fields as GET /cash-in/{id}, minus pixData and openFinanceData — those only make sense at creation time.

Security
bearerAuth
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 transaction was created, not when it was paid.

Example: from=2026-08-01
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-08-01
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/cash-in?from=2026-08-01&to=2026-08-01&limit=50" \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

A page of Cash-In transactions.

Bodyapplication/json
itemsArray of objects(CashInDetailedResponse)
items[].​transactionIdstring
Example: "kk6g232xel65a0daee4dd13kk2912714964"
items[].​internalCodestring
Example: "US7B1JQ"
items[].​externalReferencestring
Example: "order_abc123"
items[].​endToEndIdstring

End-to-end ID issued by BACEN/SPI upon settlement.

  • For paid transactions: starts with E (e.g. E00416968...)
  • For refunded transactions: starts with D (Devolution)
Example: "E00416968202603101827cemeFscF6AG"
items[].​originalEndToEndIdstring

The original E2E ID when endToEndId represents a refund.

Example: "E00416968202603101827cemeFscF6AG"
items[].​statusstring
  • AWAITING_PAYMENT — created, not paid yet
  • PAID — payment confirmed
  • EXPIRED — expired without payment; see expiredAt
  • REFUNDED — paid, then returned to the payer; see reason and refundedAt
  • CANCELLED — cancelled before being paid; see cancelledAt
Enum"AWAITING_PAYMENT""PAID""EXPIRED""REFUNDED""CANCELLED"
Example: "PAID"
items[].​reasonstring(CashInRefundReason)

Why a paid Cash-In went back to the payer. Present only when status is REFUNDED.

  • FRAUD, DUPLICATED_PAYMENT, CUSTOMER_REQUEST, MERCHANT_ERROR — the reason you sent on POST /cash-in/{id}/refund. FRAUD also covers a MED (Special Return Mechanism) claim, and CUSTOMER_REQUEST a devolution the bank flagged as requested by the customer
  • PAYER_NOT_ALLOWED — refunded automatically because the payer is not allowed to pay you
  • OTHER — any other reason
Enum"FRAUD""DUPLICATED_PAYMENT""CUSTOMER_REQUEST""MERCHANT_ERROR""PAYER_NOT_ALLOWED""OTHER"
items[].​amountnumber(decimal)
Example: 150.5
items[].​payerobject(CashInResponsePayer)
items[].​payer.​namestring
Example: "João Silva"
items[].​payer.​documentstring
Example: "12345678909"
items[].​payer.​bankDataobject(BankData)

Banking details returned after settlement. May be null before settlement.

items[].​settlementobject(Settlement)

Present only when money actually moved: PAID and REFUNDED. Absent in AWAITING_PAYMENT, EXPIRED and CANCELLED — no ConnectPSP account received anything.

items[].​settlement.​ispbstring

ISPB of the settling institution. Key on this, not on bank.

Example: "12345678"
items[].​settlement.​bankstring
Example: "SETTLEMENT PARTNER A"
items[].​settlement.​branchstring
Example: "0001"
items[].​settlement.​accountstring
Example: "123456"
items[].​requestedAtstring(date-time)

When the charge was created. Always present, in every status.

Example: "2026-03-10T11:20:00-03:00"
items[].​paidAtstring(date-time)
Example: "2026-03-10T11:22:15-03:00"
items[].​refundedAtstring(date-time)
Example: "2026-03-11T09:00:00-03:00"
items[].​cancelledAtstring(date-time)

When the charge was cancelled. Present only on CANCELLED.

items[].​expiredAtstring(date-time)

The charge's expiration date and time (the end of the payment window). Same value on GET by id, on the list and on the CASHIN_EXPIRED webhook. CASHIN_EXPIRED is sent 5 to 7 minutes after the expiration; the envelope eventAt is the send time, not the expiration.

nextCursorstring

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

Example: "MTM4OTU0NzI4MDAwMDAwMDB8YXxufFVTN0IxSlE"
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: "MTM4OTU0NzI4MDAwMDAwMDB8YXxwfFVTN0IxSlE"
Response
application/json
{
  "items": [
    { … }
  ],
  "nextCursor": "MTM4OTU0NzI4MDAwMDAwMDB8YXxufFVTN0IxSlE"
}

Summarize Cash-Ins

Request

Aggregated Cash-In figures for a period: totals per status, and the same figures broken down by settlement bank.

Use this instead of walking the whole list when you only need the numbers.

Status buckets

KeyMeaning
pendingNot paid — covers both awaiting payment and expired
paidSettled
refundedReturned to the payer

⚠️ There is no expired bucket. Expiry depends on the charge's due date, which the aggregate does not read, so expired charges are counted under pending. The listing endpoint does distinguish them per item.

A bucket only appears when it has at least one transaction.

Settlement breakdown

settlement counts and sums paid transactions only. Money that has not settled is not attributed to any bank — this is what makes the figures reconcile against GET /account/balance.

Security
bearerAuth
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 transaction was created, not when it was paid.

Example: from=2026-08-01
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-08-01
Headers
ApplicationTokenstringrequired

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

Example: {{ApplicationToken}}
curl "https://api.homologacao.connectpsp.com/cash-in/summary?from=2026-08-01&to=2026-08-01" \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

Aggregated figures for the period.

Bodyapplication/json
fromstring(date-time)

Start of the period, echoed back in America/Sao_Paulo.

Example: "2026-08-01T00:00:00-03:00"
tostring(date-time)
Example: "2026-08-01T23:59:59-03:00"
currencystring
Example: "BRL"
totalsobject

Status key → {count, amount}. Only statuses with at least one transaction appear.

Cash-In keys: pending, paid, refunded. Cash-Out keys: the Cash-Out statuses in lowercase — processing, pending, completed, cancelled, refunded.

totals.​property name*object(SummaryBucket)additional property
totals.​property name*.​countinteger(int64)
Example: 1284
totals.​property name*.​amountnumber(decimal)
Example: 192450.75
settlementArray of objects(SummaryByBank)

Breakdown by settlement bank, paid transactions only (paid on Cash-In, completed on Cash-Out), ordered by amount descending.

settlement[].​ispbstring
Example: "12345678"
settlement[].​bankstring
Example: "SETTLEMENT PARTNER A"
settlement[].​countinteger(int64)
Example: 1103
settlement[].​amountnumber(decimal)
Example: 165230.75
Response
application/json
{
  "from": "2026-08-01T00:00:00-03:00",
  "to": "2026-08-01T23:59:59-03:00",
  "currency": "BRL",
  "totals": {
    "paid": { … },
    "pending": { … },
    "refunded": { … }
  },
  "settlement": [
    { … },
    { … }
  ]
}

Get Cash-In

Request

Returns the current status and details of a Cash-In transaction.

The body is the same object delivered in the data of the CASHIN_* webhooks — see the Webhooks guide for the single documented difference on refunds.

Which identifier to use

The {id} parameter accepts any of the identifiers below. When a value matches more than one transaction, the result is deterministic: the first level in this order wins, and within the same level the most recent transaction wins.

OrderIdentifier
1internalCode (e.g. US7B1JQ)
2transactionId (TxId)
3endToEndId of the payment (starts with E)
4endToEndId of the refund (starts with D)
5externalReference (your own reference)

Prefer internalCode: it is the only identifier that can never collide with another level.

Refunded Cash-Ins

When status is REFUNDED, reason tells you why the money went back to the payer:

reasonMeaning
FRAUDRefunded because of fraud, including a MED (Special Return Mechanism) claim
DUPLICATED_PAYMENTYou requested the refund with this reason
CUSTOMER_REQUESTRefund at the customer's request — the reason you sent, or a devolution the bank flagged as requested by the customer
MERCHANT_ERRORYou requested the refund with this reason
PAYER_NOT_ALLOWEDRefunded automatically because the payer is not allowed to pay you
OTHERAny other reason
Security
bearerAuth
Path
idstringrequired

internalCode, transactionId, payment endToEndId, refund endToEndId or externalReference. See "Which identifier to use" above for the precedence.

Example: US7B1JQ
Headers
ApplicationTokenstringrequired

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

Example: {{ApplicationToken}}
curl https://api.homologacao.connectpsp.com/cash-in/US7B1JQ \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

Cash-In details returned successfully.

Bodyapplication/json
transactionIdstring
Example: "kk6g232xel65a0daee4dd13kk2912714964"
internalCodestring
Example: "US7B1JQ"
externalReferencestring
Example: "order_abc123"
endToEndIdstring

End-to-end ID issued by BACEN/SPI upon settlement.

  • For paid transactions: starts with E (e.g. E00416968...)
  • For refunded transactions: starts with D (Devolution)
Example: "E00416968202603101827cemeFscF6AG"
originalEndToEndIdstring

The original E2E ID when endToEndId represents a refund.

Example: "E00416968202603101827cemeFscF6AG"
statusstring
  • AWAITING_PAYMENT — created, not paid yet
  • PAID — payment confirmed
  • EXPIRED — expired without payment; see expiredAt
  • REFUNDED — paid, then returned to the payer; see reason and refundedAt
  • CANCELLED — cancelled before being paid; see cancelledAt
Enum"AWAITING_PAYMENT""PAID""EXPIRED""REFUNDED""CANCELLED"
Example: "PAID"
reasonstring(CashInRefundReason)

Why a paid Cash-In went back to the payer. Present only when status is REFUNDED.

  • FRAUD, DUPLICATED_PAYMENT, CUSTOMER_REQUEST, MERCHANT_ERROR — the reason you sent on POST /cash-in/{id}/refund. FRAUD also covers a MED (Special Return Mechanism) claim, and CUSTOMER_REQUEST a devolution the bank flagged as requested by the customer
  • PAYER_NOT_ALLOWED — refunded automatically because the payer is not allowed to pay you
  • OTHER — any other reason
Enum"FRAUD""DUPLICATED_PAYMENT""CUSTOMER_REQUEST""MERCHANT_ERROR""PAYER_NOT_ALLOWED""OTHER"
amountnumber(decimal)
Example: 150.5
payerobject(CashInResponsePayer)
payer.​namestring
Example: "João Silva"
payer.​documentstring
Example: "12345678909"
payer.​bankDataobject(BankData)

Banking details returned after settlement. May be null before settlement.

payer.​bankData.​ispbstring

Bank ISPB code (8 digits).

Example: "00000000"
payer.​bankData.​bankstring

Bank name.

Example: "Banco do Brasil S.A."
payer.​bankData.​branchstring

Branch number.

Example: "0001"
payer.​bankData.​accountstring

Account number.

Example: "123456"
settlementobject(Settlement)

Present only when money actually moved: PAID and REFUNDED. Absent in AWAITING_PAYMENT, EXPIRED and CANCELLED — no ConnectPSP account received anything.

settlement.​ispbstring

ISPB of the settling institution. Key on this, not on bank.

Example: "12345678"
settlement.​bankstring
Example: "SETTLEMENT PARTNER A"
settlement.​branchstring
Example: "0001"
settlement.​accountstring
Example: "123456"
requestedAtstring(date-time)

When the charge was created. Always present, in every status.

Example: "2026-03-10T11:20:00-03:00"
paidAtstring(date-time)
Example: "2026-03-10T11:22:15-03:00"
refundedAtstring(date-time)
Example: "2026-03-11T09:00:00-03:00"
cancelledAtstring(date-time)

When the charge was cancelled. Present only on CANCELLED.

expiredAtstring(date-time)

The charge's expiration date and time (the end of the payment window). Same value on GET by id, on the list and on the CASHIN_EXPIRED webhook. CASHIN_EXPIRED is sent 5 to 7 minutes after the expiration; the envelope eventAt is the send time, not the expiration.

Response
application/json
{
  "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
  "internalCode": "US7B1JQ",
  "externalReference": "order_abc123",
  "endToEndId": "E00416968202603101827cemeFscF6AG",
  "status": "PAID",
  "amount": 150.5,
  "payer": {
    "name": "João Silva",
    "document": "12345678909",
    "bankData": { … }
  },
  "settlement": {
    "ispb": "12345678",
    "bank": "SETTLEMENT PARTNER A",
    "branch": "0001",
    "account": "123456"
  },
  "requestedAt": "2026-03-10T11:20:00-03:00",
  "paidAt": "2026-03-10T11:22:15-03:00"
}

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

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