Skip to content
/
Create Cash-Out

ConnectPSP API (2.0.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

For POST /cash-in and POST /cash-out, we strongly recommend sending the X-Idempotency-Key header (UUID v4). This guarantees that network retries do not result in duplicate transactions.

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

Create Cash-Out

Request

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

The request is validated against available balance and fraud rules, then queued for settlement. The response is 202 Accepted — the payment is not yet settled at this point.

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 DigitalSignature and X-Idempotency-Key headers.

Once the payment is settled (or fails), ConnectPSP will POST either a CASHOUT_COMPLETED or CASHOUT_FAILED event to your webhookUrl.

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(uuid)

A client-generated UUID v4 to guarantee idempotency. If the same key is sent twice, the second request returns the original response without creating a duplicate transaction. Strongly recommended for all POST operations.

Example: 550e8400-e29b-41d4-a716-446655440000
Bodyapplication/jsonrequired
amountnumber(decimal)>= 0.01required

Amount in BRL (Reais). Decimal format.

Example: 500
externalReferencestring<= 100 charactersrequired

Your unique transaction reference. Duplicate references return 409 Conflict.

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.

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 settlement. Awaiting banking network confirmation.

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

Get Cash-Out

Request

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

The {id} parameter accepts:

  • internalCode (ConnectPSP's code, e.g. IVKPRMOCDY)
  • transactionId (UUID)
  • endToEndId (E2E ID from BACEN/SPI)
Security
bearerAuth
Path
idstringrequired

Transaction identifier.

Example: IVKPRMOCDY
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
  • FAILED: null (never settled)
Example: "E00416968202603101827cemeFscF6AG"
originalEndToEndIdstring

Original E2E ID when endToEndId represents an async refund.

statusstring
Enum"PROCESSING""COMPLETED""FAILED""REFUNDED""CANCELLED"
Example: "COMPLETED"
amountnumber(decimal)
Example: 500
failureobject(CashOutFailure)

Present only when status is FAILED.

failure.​codestring

Machine-readable failure code.

Example: "PIX_KEY_NOT_FOUND"
failure.​messagestring

Human-readable failure reason.

Example: "The provided PIX key did not resolve to a valid account."
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.

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"
requestedAtstring(date-time)
Example: "2026-03-10T14:00:00-03:00"
paidAtstring(date-time)
Example: "2026-03-10T14:02:30-03:00"
failedAtstring(date-time)
refundedAtstring(date-time)
canceledAtstring(date-time)
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": { … }
  },
  "requestedAt": "2026-03-10T14:00:00-03:00",
  "paidAt": "2026-03-10T14:02:30-03:00"
}

Account

View consolidated wallet balances across all banking partners (Delbank, Celcoin, StarkBank) and manage rebalancing between transactional and proprietary accounts.

Operations