Create Cash-Out

ConnectPSP API (2.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

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:

Header	Description
`Authorization`	`Bearer <jwt_token>` — obtained from `POST /auth/token`
`ApplicationToken`	Fixed GUID token that identifies your integration

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

Header	Description
`DigitalSignature`	HMAC-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

Phase	What to confirm first
Setup	Credentials, environment, headers, and webhook readiness in Initial Setup
Authentication	JWT generation and `DigitalSignature` rules in the Authentication Guide
Transactions	Your 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

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

Create Cash-Out

Request

Submits a PIX payment to an external bank account or PIX key.

The request is validated and queued for settlement. The response is 202 Accepted — the payment is not yet settled at this point.

Processing is asynchronous

202 Accepted only means the request was accepted for processing. Balance, withdrawal limits, the PIX key lookup, security rules and the receiving institution are all checked after the 202, so an accepted Cash-Out can still end up CANCELLED — for example with failure.code INSUFFICIENT_FUNDS or DAILY_LIMIT_EXCEEDED. The outcome always arrives as a webhook:

Outcome	Event	`status`
Paid	`CASHOUT_COMPLETED`	`COMPLETED`
Money never left	`CASHOUT_FAILED`	`CANCELLED`, with `failure`
Paid, then returned by the payee's bank	`CASHOUT_REFUNDED`	`REFUNDED`, with `reason`

See GET /cash-out/{id} for the full list of failure.code values.

Two destination types are supported:

PIX — by PIX key (CPF, CNPJ, email, phone, or EVP random key)
BANK_ACCOUNT — by bank account details (ISPB + branch + account)

This endpoint requires the DigitalSignature header. X-Idempotency-Key is optional and recommended — see Idempotency.

externalReference must be unique per client: reusing one returns 409 DUPLICATED_EXTERNAL_REFERENCE, even when the earlier Cash-Out was cancelled. To try again after a cancellation, send a new externalReference.

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

X-Idempotency-Keystring<= 100 characters

Optional, recommended. A key you generate per operation (a UUID v4 is ideal), up to 100 characters. Accepted on POST /cash-in and POST /cash-out.

Without it, the request is processed normally, with no idempotency. externalReference still blocks duplicates with 409 DUPLICATED_EXTERNAL_REFERENCE.
Same key, same body, within 24 hours: returns the original response, creates nothing, and adds the Idempotent-Replayed: true header.
Same key, different body: 422 IDEMPOTENCY_KEY_REUSED.
Same key while the first request is still running: 409 IDEMPOTENCY_KEY_IN_PROGRESS.
More than 100 characters: 400 IDEMPOTENCY_KEY_INVALID.

Only successful responses are stored. After an error the key is released, and a retry with the same key is processed again.

Example: 550e8400-e29b-41d4-a716-446655440000

Bodyapplication/jsonrequired

amountnumber(decimal)>= 0.01required

Amount in BRL (Reais). Decimal format.

Example: 500

externalReferencestring<= 50 charactersrequired

Your unique transaction reference, per client. Reusing one returns 409 DUPLICATED_EXTERNAL_REFERENCE, even when the earlier Cash-Out was cancelled. Also accepted as {id} on GET /cash-out/{id}.

Example: "withdraw_xyz789"

descriptionstring<= 140 characters

Optional description that may appear on the payee's bank statement.

Example: "Player withdrawal"

webhookUrlstring(uri)

URL to receive settlement events (CASHOUT_COMPLETED, CASHOUT_FAILED, CASHOUT_REFUNDED).

Example: "https://api.yourdomain.com/webhooks/connectpsp"

payeeobject(CashOutPayee)required

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.

curl -i -X POST \
  https://api.homologacao.connectpsp.com/cash-out \
  -H 'ApplicationToken: {{ApplicationToken}}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'DigitalSignature: {{DigitalSignature}}' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "amount": 500,
    "externalReference": "withdraw_xyz789",
    "description": "Player withdrawal",
    "webhookUrl": "https://api.yourdomain.com/webhooks/connectpsp",
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      }
    }
  }'

Responses

Cash-Out accepted for processing. The outcome — COMPLETED, or CANCELLED with failure — arrives later by webhook.

Headers

Idempotent-Replayedstring

true when this response is a replay of an earlier request sent with the same X-Idempotency-Key and the same body. Nothing new was created. Absent on a first execution.

Value"true"

Example: "true"

Bodyapplication/json

transactionIdstring

Internal UUID for this transaction.

Example: "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9"

internalCodestring

ConnectPSP alphanumeric code. Use for polling.

Example: "IVKPRMOCDY"

externalReferencestring

Example: "withdraw_xyz789"

statusstring

Value"PROCESSING"

Example: "PROCESSING"

requestedAtstring(date-time)

Example: "2026-03-10T14:00:00-03:00"

Response

application/json

{
  "transactionId": "dd30446e-6cc5-4664-bf3f-6b7f5e55a1a9",
  "internalCode": "IVKPRMOCDY",
  "externalReference": "withdraw_xyz789",
  "status": "PROCESSING",
  "requestedAt": "2026-03-10T14:00:00-03:00"
}

List Cash-Outs

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

Summarize Cash-Outs

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.

Key	Status	Meaning
`processing`	`PROCESSING`	Being executed at the financial institution
`pending`	`PENDING`	Held on the ConnectPSP side (approval, analysis or reconciliation)
`completed`	`COMPLETED`	Settled
`cancelled`	`CANCELLED`	The money never left your account
`refunded`	`REFUNDED`	Settled, 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": [
    { … },
    { … }
  ]
}

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:

Endpoint	Use it for
`GET /health/pix`	The picture of the moment: status per block plus the incidents open right now
`GET /health/pix/incidents`	History 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

ConnectPSP API (2.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Authentication

Idempotency

Recommended integration order

Authentication

Cash-In

Cash-Out

Create Cash-Out

Request

Processing is asynchronous

Responses

Was this helpful?

List Cash-Outs

Request

Responses

Was this helpful?

Summarize Cash-Outs

Request

Status buckets

Settlement breakdown

Responses

Was this helpful?

Account

Health

ConnectPSP API (2.2.0)CopyCopy for LLMCopy page as Markdown for LLMsView as MarkdownOpen this page as MarkdownOpen in ChatGPTGet insights from ChatGPTOpen in ClaudeGet insights from Claude

Authentication

Idempotency

Recommended integration order

Authentication

Cash-In

Cash-Out

Create Cash-Out

RequestExpand all

Processing is asynchronous

Responses

Was this helpful?

List Cash-Outs

Request

Cursor pagination

Responses

Was this helpful?

Summarize Cash-Outs

Request

Status buckets

Settlement breakdown

Responses

Was this helpful?

Account

Health

ConnectPSP API (2.2.0)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Request