Skip to content

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
Overview
ConnectPSP Support
Languages
Servers
Staging Environment (Testing)
https://api.homologacao.connectpsp.com

Obtain JWT tokens to authenticate all other requests.

Operations

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

Operations

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

Operations

Request

Returns Cash-Out 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.

Each item carries the same fields as GET /cash-out/{id}, with the same status, failure and reason values.

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

Responses

A page of Cash-Out transactions.

Bodyapplication/json
itemsArray of objects(CashOutDetailedResponse)
items[].​transactionIdstring
Example: "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9"
items[].​internalCodestring
Example: "IVKPRMOCDY"
items[].​externalReferencestring
Example: "withdraw_xyz789"
items[].​endToEndIdstring

BACEN/SPI settlement proof.

  • COMPLETED: starts with E
  • REFUNDED: starts with D (the devolution); the payment E2E is in originalEndToEndId
  • CANCELLED: absent when the transfer never reached the PIX network
Example: "E00416968202603101827cemeFscF6AG"
items[].​originalEndToEndIdstring

Original E2E ID when endToEndId represents an async refund.

items[].​statusstring
  • PROCESSING — being executed at the financial institution
  • PENDING — held on the ConnectPSP side (approval, analysis or reconciliation)
  • COMPLETED — paid to the payee
  • CANCELLED — the money never left your account; see failure
  • REFUNDED — the money left and came back to your account; see reason
Enum"PROCESSING""PENDING""COMPLETED""CANCELLED""REFUNDED"
Example: "COMPLETED"
items[].​amountnumber(decimal)
Example: 500
items[].​failureobject(CashOutFailure)

Why the Cash-Out was cancelled. Present only when status is CANCELLED. The full table of codes, messages and whether to retry is in GET /cash-out/{id}.

items[].​failure.​codestring

Machine-readable failure code. Key your handling on this. New codes may be added — treat an unknown code as PROCESSING_ERROR.

Enum"PROVIDER_UNAVAILABLE""PIX_KEY_NOT_FOUND""PIX_KEY_INVALID""PAYEE_DOCUMENT_MISMATCH""PAYEE_ACCOUNT_INVALID""PAYEE_ACCOUNT_UNAVAILABLE""PAYEE_BANK_UNAVAILABLE""PAYEE_BANK_REJECTED""FRAUD_SUSPECTED""INSUFFICIENT_FUNDS"
Example: "PIX_KEY_NOT_FOUND"
items[].​failure.​messagestring

Fixed English text for the code, safe to show to your operators. Do not parse it.

Example: "The provided PIX key did not resolve to a valid account."
items[].​reasonstring(CashOutRefundReason)

Why a completed Cash-Out came back. Present only when status is REFUNDED.

  • PAYEE_REQUESTED — the payee asked their bank to return the transfer
  • FRAUD — returned because of fraud, including a MED (Special Return Mechanism) claim
  • OPERATIONAL_ERROR — returned because of an operational error at a bank
  • REVERSED_BY_INSTITUTION — reversed by the financial institution
  • OTHER — any other reason
Enum"PAYEE_REQUESTED""FRAUD""OPERATIONAL_ERROR""REVERSED_BY_INSTITUTION""OTHER"
items[].​payeeobject(CashOutPayeeDetailed)
items[].​payee.​namestringrequired

Full name of the payee.

Example: "Maria Silva"
items[].​payee.​documentstringrequired

CPF or CNPJ of the payee (numbers only).

Example: "12345678909"
items[].​payee.​destinationobject(CashOutDestination)required
items[].​payee.​bankDataobject(BankData)

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

items[].​settlementobject(Settlement)
  • COMPLETED / REFUNDED — the ConnectPSP account that settled the Cash-Out.
  • CANCELLED — the ConnectPSP account the Cash-Out would have been paid from. Present only when a bank had already been assigned; no money left your account.
  • PROCESSING / PENDING — absent.
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 Cash-Out was requested. Always present.

Example: "2026-03-10T14:00:00-03:00"
items[].​completedAtstring(date-time)

When the payment was completed. Present on COMPLETED, and kept on REFUNDED.

Example: "2026-03-10T14:02:30-03:00"
items[].​cancelledAtstring(date-time)

When the Cash-Out was cancelled. Present only on CANCELLED.

items[].​refundedAtstring(date-time)

When the money came back. Present only on REFUNDED.

nextCursorstring

Opaque cursor for the next page. Absent when there are no more pages.

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

Request

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

Status buckets

The keys are the Cash-Out status values returned by GET /cash-out/{id}, the listing and the webhooks, in lowercase.

KeyStatusMeaning
processingPROCESSINGBeing executed at the financial institution
pendingPENDINGHeld on the ConnectPSP side (approval, analysis or reconciliation)
completedCOMPLETEDSettled
cancelledCANCELLEDThe money never left your account
refundedREFUNDEDSettled, then returned to your account

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

Settlement breakdown

settlement counts and sums completed transactions only.

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-out/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": { "completed": { … }, "processing": { … }, "pending": { … }, "cancelled": { … } }, "settlement": [ { … }, { … } ] }

Request

Returns the current status and details of a Cash-Out transaction, including settlement proof from BACEN/SPI when available.

The body is the same object delivered in the data of the CASHOUT_* webhooks.

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. IVKPRMOCDY)
2transactionId (UUID)
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.

Status

statusMeaningExtra fields
PROCESSINGBeing executed at the financial institution—
PENDINGHeld on the ConnectPSP side (approval, analysis or reconciliation)—
COMPLETEDPaid to the payeecompletedAt
CANCELLEDThe money never left your accountfailure, cancelledAt
REFUNDEDThe money left and came back to your accountreason, refundedAt

COMPLETED, CANCELLED and REFUNDED are final, except that a COMPLETED Cash-Out can later become REFUNDED when the payee's bank returns it.

Why a Cash-Out was cancelled — failure

failure is present only when status is CANCELLED. failure.message is fixed per code.

failure.codefailure.messageWhen it happensRetry?
PROVIDER_UNAVAILABLEThe withdrawal could not be completed due to a temporary instability. The amount remains available in your account.Temporary instability at ConnectPSP or at the settlement partnerYes
PIX_KEY_NOT_FOUNDThe provided PIX key did not resolve to a valid account.The PIX key is not registered in the PIX directory (DICT)No — ask the payee for another key
PIX_KEY_INVALIDThe provided PIX key has an invalid format.The key does not match the format of its pixKeyTypeNo — fix the key
PAYEE_DOCUMENT_MISMATCHThe PIX key or account does not belong to the informed payee document.The owner of the key or account is not payee.documentNo
PAYEE_ACCOUNT_INVALIDThe destination account data is invalid.Bank account data (ISPB, branch, account, type) does not identify an accountNo — fix the account data
PAYEE_ACCOUNT_UNAVAILABLEThe destination account is blocked, closed or cannot receive this transfer.The destination account is blocked, closed or does not accept this transferNo
PAYEE_BANK_UNAVAILABLEThe receiving institution did not respond in time. The amount remains available in your account.The payee's bank did not answer in timeYes
PAYEE_BANK_REJECTEDThe receiving institution rejected the transfer.The payee's bank refused the transferOnly after checking with the payee
FRAUD_SUSPECTEDThe transfer was blocked by a security restriction on the payee.A security or anti-fraud restriction on the payeeNo
INSUFFICIENT_FUNDSInsufficient balance to complete the withdrawal.Your transactional balance did not cover the amountYes, after funding the account (see POST /account/rebalance)
AMOUNT_ABOVE_MAXIMUMThe amount exceeds the maximum allowed for this transfer.Above the maximum per transferOnly with a lower amount
DAILY_LIMIT_EXCEEDEDThe daily withdrawal limit has been reached.Your daily withdrawal limit was reachedYes, on the next day
PERIOD_LIMIT_EXCEEDEDThe withdrawal limit for the current period has been reached.The limit for the current period (daytime or nighttime) was reachedYes, in the next period
PAYEE_LIMIT_EXCEEDEDThe withdrawal limit for this payee has been reached.The limit per payee was reachedYes, when the payee's limit resets
PAYEE_NOT_ALLOWEDTransfers to this payee are not allowed.The payee, or the payee's institution, is not allowed to receiveNo
DUPLICATED_TRANSFERA duplicated transfer was detected and rejected.The same transfer was already sentNo — check the original Cash-Out first
APPROVAL_REJECTEDThe withdrawal was rejected during approval.Rejected during manual approvalOnly with a new approval
PROCESSING_ERRORThe withdrawal could not be completed. The amount remains available in your account.Any other failureYes — contact support if it repeats

A retry is always a new POST /cash-out with a new externalReference: the cancelled one keeps its reference. New codes may be added over time — treat a code you do not know as PROCESSING_ERROR.

Why a Cash-Out was refunded — reason

reason is present only when status is REFUNDED.

reasonMeaning
PAYEE_REQUESTEDThe payee asked their bank to return the transfer
FRAUDReturned because of fraud, including a MED (Special Return Mechanism) claim
OPERATIONAL_ERRORReturned because of an operational error at a bank
REVERSED_BY_INSTITUTIONReversed by the financial institution
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: IVKPRMOCDY
Headers
ApplicationTokenstringrequired

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

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

Responses

Cash-Out details returned.

Bodyapplication/json
transactionIdstring
Example: "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9"
internalCodestring
Example: "IVKPRMOCDY"
externalReferencestring
Example: "withdraw_xyz789"
endToEndIdstring

BACEN/SPI settlement proof.

  • COMPLETED: starts with E
  • REFUNDED: starts with D (the devolution); the payment E2E is in originalEndToEndId
  • CANCELLED: absent when the transfer never reached the PIX network
Example: "E00416968202603101827cemeFscF6AG"
originalEndToEndIdstring

Original E2E ID when endToEndId represents an async refund.

statusstring
  • PROCESSING — being executed at the financial institution
  • PENDING — held on the ConnectPSP side (approval, analysis or reconciliation)
  • COMPLETED — paid to the payee
  • CANCELLED — the money never left your account; see failure
  • REFUNDED — the money left and came back to your account; see reason
Enum"PROCESSING""PENDING""COMPLETED""CANCELLED""REFUNDED"
Example: "COMPLETED"
amountnumber(decimal)
Example: 500
failureobject(CashOutFailure)

Why the Cash-Out was cancelled. Present only when status is CANCELLED. The full table of codes, messages and whether to retry is in GET /cash-out/{id}.

failure.​codestring

Machine-readable failure code. Key your handling on this. New codes may be added — treat an unknown code as PROCESSING_ERROR.

Enum"PROVIDER_UNAVAILABLE""PIX_KEY_NOT_FOUND""PIX_KEY_INVALID""PAYEE_DOCUMENT_MISMATCH""PAYEE_ACCOUNT_INVALID""PAYEE_ACCOUNT_UNAVAILABLE""PAYEE_BANK_UNAVAILABLE""PAYEE_BANK_REJECTED""FRAUD_SUSPECTED""INSUFFICIENT_FUNDS"
Example: "PIX_KEY_NOT_FOUND"
failure.​messagestring

Fixed English text for the code, safe to show to your operators. Do not parse it.

Example: "The provided PIX key did not resolve to a valid account."
reasonstring(CashOutRefundReason)

Why a completed Cash-Out came back. Present only when status is REFUNDED.

  • PAYEE_REQUESTED — the payee asked their bank to return the transfer
  • FRAUD — returned because of fraud, including a MED (Special Return Mechanism) claim
  • OPERATIONAL_ERROR — returned because of an operational error at a bank
  • REVERSED_BY_INSTITUTION — reversed by the financial institution
  • OTHER — any other reason
Enum"PAYEE_REQUESTED""FRAUD""OPERATIONAL_ERROR""REVERSED_BY_INSTITUTION""OTHER"
payeeobject(CashOutPayeeDetailed)
payee.​namestringrequired

Full name of the payee.

Example: "Maria Silva"
payee.​documentstringrequired

CPF or CNPJ of the payee (numbers only).

Example: "12345678909"
payee.​destinationobject(CashOutDestination)required
payee.​destination.​typestringrequired
  • PIX — payment via PIX key. Provide pixKeyType and pixKey.
  • BANK_ACCOUNT — payment via bank account data. Provide bankAccount.
Enum"PIX""BANK_ACCOUNT"
Example: "PIX"
payee.​destination.​pixKeyTypestring

Type of PIX key. Required when type is PIX. Responses and webhooks always return one of these same five values: CPF, CNPJ, EMAIL, PHONE or EVP (random key).

Enum"CPF""CNPJ""EMAIL""PHONE""EVP"
Example: "CPF"
payee.​destination.​pixKeystring

The PIX key value. Required when type is PIX.

Example: "12345678909"
payee.​destination.​bankAccountobject(CashOutBankAccountInput)

Bank account details. Required when destination.type is BANK_ACCOUNT.

payee.​bankDataobject(BankData)

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

payee.​bankData.​ispbstring

Bank ISPB code (8 digits).

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

Bank name.

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

Branch number.

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

Account number.

Example: "123456"
settlementobject(Settlement)
  • COMPLETED / REFUNDED — the ConnectPSP account that settled the Cash-Out.
  • CANCELLED — the ConnectPSP account the Cash-Out would have been paid from. Present only when a bank had already been assigned; no money left your account.
  • PROCESSING / PENDING — absent.
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 Cash-Out was requested. Always present.

Example: "2026-03-10T14:00:00-03:00"
completedAtstring(date-time)

When the payment was completed. Present on COMPLETED, and kept on REFUNDED.

Example: "2026-03-10T14:02:30-03:00"
cancelledAtstring(date-time)

When the Cash-Out was cancelled. Present only on CANCELLED.

refundedAtstring(date-time)

When the money came back. Present only on REFUNDED.

Response
application/json
{ "transactionId": "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9", "internalCode": "IVKPRMOCDY", "externalReference": "withdraw_xyz789", "endToEndId": "E00416968202603101827cemeFscF6AG", "status": "COMPLETED", "amount": 500, "payee": { "name": "Maria Silva", "document": "12345678909", "destination": { … }, "bankData": { … } }, "settlement": { "ispb": "87654321", "bank": "SETTLEMENT PARTNER B", "branch": "0001", "account": "654987" }, "requestedAt": "2026-03-10T14:00:00-03:00", "completedAt": "2026-03-10T14:02:30-03:00" }

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

Operations

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