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

Obtain JWT Token

Request

Authenticates your application and returns a short-lived JWT token.

Provide the clientId and clientSecret credentials issued by ConnectPSP during onboarding. The returned accessToken must be sent in all subsequent requests as:

Authorization: Bearer <accessToken>
Bodyapplication/jsonrequired
clientIdstringrequired

Your numeric client ID provided by ConnectPSP during onboarding.

Example: "YOUR_CLIENT_ID"
clientSecretstring(uuid)required

Your secret GUID credential provided by ConnectPSP during onboarding.

Example: "YOUR_CLIENT_SECRET"
curl -X POST https://api.homologacao.connectpsp.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

Responses

Token generated successfully.

Bodyapplication/json
accessTokenstring

JWT token to use in all subsequent requests.

Example: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
tokenTypestring

Always Bearer.

Example: "Bearer"
expiresIninteger

Token lifetime in seconds.

Example: 3600
issuedAtstring(date-time)

Token issuance timestamp (ISO 8601).

Example: "2026-03-10T14:00:00Z"
Response
application/json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "tokenType": "Bearer",
  "expiresIn": 3600,
  "issuedAt": "2026-03-10T14:00:00Z"
}

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

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