Skip to content
/
Get PIX Incident

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

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

List PIX Incidents

Request

Confirmed PIX incidents in your scope, most recent first, paginated. An incident is confirmed when the engine saw the same pattern in two consecutive 5-minute windows; a one-window blip never appears here. Defaults to the last 7 days; the window between from and to cannot exceed 92 days.

Each incident tells you who (origin), how bad (severity), how sure we are about the culprit (confidence) and how we know (originClass: OBSERVED = we saw the error, INFERRED = deduced from the absence of what should have happened). summary is a diagnosis in Portuguese written for you — never internal counts of other clients.

One flat list

Unlike GET /health/pix, which splits the open incidents into incidents and externalIncidents, this list is flat. Use origin.type to tell the two apart: CONNECTPSP and BANKING_PARTNER are ours to fix, PAYER_INSTITUTION / PAYER_COHORT / PIX_SYSTEMIC are outside our control, and MERCHANT is your own operation.

status is matched case-insensitively, so active,worsening works too. The response echoes back the from and to actually applied, so you can log the window you really got.

This endpoint does not require DigitalSignature or X-Idempotency-Key.

Security
bearerAuth
Query
fromstring(date-time)

Start of the window (ISO 8601, UTC). Default is to minus 7 days.

tostring(date-time)

End of the window (ISO 8601, UTC). Default is now.

statusstring

Comma-separated list. Accepted values: ACTIVE, WORSENING, RECOVERING, RESOLVED.

Example: status=ACTIVE,WORSENING
pageinteger>= 1
Default 1
pageSizeinteger[ 1 .. 200 ]
Default 50
Headers
ApplicationTokenstringrequired

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

Example: {{ApplicationToken}}
curl "https://api.homologacao.connectpsp.com/health/pix/incidents?status=ACTIVE,WORSENING&pageSize=20" \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

Page of incidents. items is an empty array when nothing matched — that is a normal, healthy answer, not an error.

Bodyapplication/json
itemsArray of objects(PixHealthIncident)
items[].​incidentIdstring

Stable id. Use it to correlate the webhooks and the detail endpoint.

Example: "LIVE-202609081530-PAYER_INSTITUTION-00360305"
items[].​originobject(PixHealthOrigin)

Who the incident is attributed to.

items[].​origin.​typestring(PixHealthEntityType)
  • CONNECTPSP — the platform as a whole.
  • BANKING_PARTNER — a settlement partner you route through (id = ISPB).
  • PAYER_INSTITUTION — a bank your payers pay from / your payees receive at (id = ISPB).
  • PAYER_COHORT — a group of payer banks with the same behaviour.
  • MERCHANT — your own operation (id = your customer id).
  • PIX_SYSTEMIC — the PIX system itself (DICT, SPI).
Enum"CONNECTPSP""BANKING_PARTNER""PAYER_INSTITUTION""PAYER_COHORT""MERCHANT""PIX_SYSTEMIC"
items[].​origin.​idstring
Example: "00360305"
items[].​origin.​displayNamestring
Example: "CAIXA ECONOMICA FEDERAL"
items[].​operationstring(PixHealthOperation)

CASH_IN = payments you receive; CASH_OUT = withdrawals you send.

Enum"CASH_IN""CASH_OUT"
items[].​statusstring

ACTIVE = confirmed and ongoing. WORSENING = severity went up. RECOVERING = metrics back to normal, waiting 3 windows to close. RESOLVED = closed.

Enum"ACTIVE""WORSENING""RECOVERING""RESOLVED"
Example: "ACTIVE"
items[].​severitystring

How bad it is (never HEALTHY on an incident).

Enum"DEGRADED""SEVERELY_DEGRADED""UNAVAILABLE"
Example: "DEGRADED"
items[].​confidencestring

How sure the engine is about who is at fault — not about how bad it is.

Enum"LOW""MEDIUM""HIGH"
Example: "MEDIUM"
items[].​originClassstring

How the engine knows. OBSERVED = it saw the error itself. INFERRED = deduced from the absence of what should have happened. CORROBORATED / CONFIRMED = backed by a second independent signal.

Enum"OBSERVED""INFERRED""CORROBORATED""CONFIRMED""UNKNOWN"
Example: "INFERRED"
items[].​startedAtstring(date-time)

Start of the first anomalous window (UTC).

Example: "2026-09-08T15:30:00Z"
items[].​detectedAtstring(date-time)

When the engine confirmed it (UTC).

Example: "2026-09-08T15:37:59Z"
items[].​recoveredAtstring or null(date-time)

When metrics returned to normal; null while ongoing.

Example: null
items[].​resolvedAtstring or null(date-time)

When the incident was closed; null while open.

Example: null
items[].​updatedAtstring or null(date-time)
Example: "2026-09-08T16:52:00Z"
items[].​affectedPartnersinteger

How many settlement partners the incident reached.

Example: 2
items[].​summarystring

Diagnosis in Portuguese, written for you. Never contains other clients' data.

Example: "Forte evidência de degradação em cobranças pagas por clientes da CAIXA ECONOMICA FEDERAL: a conversão desses pagadores ficou em 78,5%, contra 93,0% esperados, enquanto 9 instituições de controle seguem normais."
totalinteger(int64)

Total incidents matching the filter (all pages).

Example: 3
pageinteger
Example: 1
pageSizeinteger
Example: 50
fromstring(date-time)

Effective start of the window (UTC).

Example: "2026-09-01T16:53:00Z"
tostring(date-time)

Effective end of the window (UTC).

Example: "2026-09-08T16:53:00Z"
Response
application/json
{
  "items": [
    { … },
    { … }
  ],
  "total": 2,
  "page": 1,
  "pageSize": 50,
  "from": "2026-09-01T16:53:00Z",
  "to": "2026-09-08T16:53:00Z"
}

Get PIX Incident

Request

One incident with the evidence behind the verdict. Each piece of evidence names the metric, the entity, the relative deviation from expected and the Z-score — never raw platform volumes.

Returns 404 when the incident does not exist or is outside your scope; the two cases are deliberately indistinguishable.

This endpoint does not require DigitalSignature or X-Idempotency-Key.

Security
bearerAuth
Path
idstringrequired

The incidentId from the picture or from the list.

Example: LIVE-202609081530-PAYER_INSTITUTION-00360305
Headers
ApplicationTokenstringrequired

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

Example: {{ApplicationToken}}
curl https://api.homologacao.connectpsp.com/health/pix/incidents/LIVE-202609081530-PAYER_INSTITUTION-00360305 \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>"

Responses

Incident and evidence.

Bodyapplication/json
incidentobject(PixHealthIncident)
incident.​incidentIdstring

Stable id. Use it to correlate the webhooks and the detail endpoint.

Example: "LIVE-202609081530-PAYER_INSTITUTION-00360305"
incident.​originobject(PixHealthOrigin)

Who the incident is attributed to.

incident.​origin.​typestring(PixHealthEntityType)
  • CONNECTPSP — the platform as a whole.
  • BANKING_PARTNER — a settlement partner you route through (id = ISPB).
  • PAYER_INSTITUTION — a bank your payers pay from / your payees receive at (id = ISPB).
  • PAYER_COHORT — a group of payer banks with the same behaviour.
  • MERCHANT — your own operation (id = your customer id).
  • PIX_SYSTEMIC — the PIX system itself (DICT, SPI).
Enum"CONNECTPSP""BANKING_PARTNER""PAYER_INSTITUTION""PAYER_COHORT""MERCHANT""PIX_SYSTEMIC"
incident.​origin.​idstring
Example: "00360305"
incident.​origin.​displayNamestring
Example: "CAIXA ECONOMICA FEDERAL"
incident.​operationstring(PixHealthOperation)

CASH_IN = payments you receive; CASH_OUT = withdrawals you send.

Enum"CASH_IN""CASH_OUT"
incident.​statusstring

ACTIVE = confirmed and ongoing. WORSENING = severity went up. RECOVERING = metrics back to normal, waiting 3 windows to close. RESOLVED = closed.

Enum"ACTIVE""WORSENING""RECOVERING""RESOLVED"
Example: "ACTIVE"
incident.​severitystring

How bad it is (never HEALTHY on an incident).

Enum"DEGRADED""SEVERELY_DEGRADED""UNAVAILABLE"
Example: "DEGRADED"
incident.​confidencestring

How sure the engine is about who is at fault — not about how bad it is.

Enum"LOW""MEDIUM""HIGH"
Example: "MEDIUM"
incident.​originClassstring

How the engine knows. OBSERVED = it saw the error itself. INFERRED = deduced from the absence of what should have happened. CORROBORATED / CONFIRMED = backed by a second independent signal.

Enum"OBSERVED""INFERRED""CORROBORATED""CONFIRMED""UNKNOWN"
Example: "INFERRED"
incident.​startedAtstring(date-time)

Start of the first anomalous window (UTC).

Example: "2026-09-08T15:30:00Z"
incident.​detectedAtstring(date-time)

When the engine confirmed it (UTC).

Example: "2026-09-08T15:37:59Z"
incident.​recoveredAtstring or null(date-time)

When metrics returned to normal; null while ongoing.

Example: null
incident.​resolvedAtstring or null(date-time)

When the incident was closed; null while open.

Example: null
incident.​updatedAtstring or null(date-time)
Example: "2026-09-08T16:52:00Z"
incident.​affectedPartnersinteger

How many settlement partners the incident reached.

Example: 2
incident.​summarystring

Diagnosis in Portuguese, written for you. Never contains other clients' data.

Example: "Forte evidência de degradação em cobranças pagas por clientes da CAIXA ECONOMICA FEDERAL: a conversão desses pagadores ficou em 78,5%, contra 93,0% esperados, enquanto 9 instituições de controle seguem normais."
evidenceArray of objects(PixHealthEvidence)

The anomalous points behind the verdict, newest first.

evidence[].​observedAtstring(date-time)

Start of the 5-minute window (UTC).

Example: "2026-09-08T15:35:00Z"
evidence[].​metricstring
Example: "CONVERSION_MATURED"
evidence[].​operationstring(PixHealthOperation)

CASH_IN = payments you receive; CASH_OUT = withdrawals you send.

Enum"CASH_IN""CASH_OUT"
evidence[].​entityobject(PixHealthOrigin)

Who the incident is attributed to.

evidence[].​entity.​typestring(PixHealthEntityType)
  • CONNECTPSP — the platform as a whole.
  • BANKING_PARTNER — a settlement partner you route through (id = ISPB).
  • PAYER_INSTITUTION — a bank your payers pay from / your payees receive at (id = ISPB).
  • PAYER_COHORT — a group of payer banks with the same behaviour.
  • MERCHANT — your own operation (id = your customer id).
  • PIX_SYSTEMIC — the PIX system itself (DICT, SPI).
Enum"CONNECTPSP""BANKING_PARTNER""PAYER_INSTITUTION""PAYER_COHORT""MERCHANT""PIX_SYSTEMIC"
evidence[].​entity.​idstring
Example: "00360305"
evidence[].​entity.​displayNamestring
Example: "CAIXA ECONOMICA FEDERAL"
evidence[].​deviationPercentnumber or null(double)

(observed − expected) ÷ expected. -0.16 means 16 % below expected. null when there is no expectation.

Example: -0.16
evidence[].​znumber(double)

Robust Z-score of the deviation. |Z| ≥ 3 is an anomaly; the farther from 0, the clearer.

Example: -4.2
Response
application/json
{
  "incident": {
    "incidentId": "LIVE-202609081530-PAYER_INSTITUTION-00360305",
    "origin": { … },
    "operation": "CASH_IN",
    "status": "ACTIVE",
    "severity": "DEGRADED",
    "confidence": "MEDIUM",
    "originClass": "INFERRED",
    "startedAt": "2026-09-08T15:30:00Z",
    "detectedAt": "2026-09-08T15:37:59Z",
    "recoveredAt": null,
    "resolvedAt": null,
    "updatedAt": "2026-09-08T16:52:00Z",
    "affectedPartners": 2,
    "summary": "Forte evidência de degradação em cobranças pagas por clientes da CAIXA ECONOMICA FEDERAL: a conversão desses pagadores ficou em 78,5%, contra 93,0% esperados, enquanto 9 instituições de controle seguem normais."
  },
  "evidence": [
    { … },
    { … }
  ]
}