Skip to content
/
Create Cash-In

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

Create Cash-In

Request

Generates a PIX payment intent.

Standard PIX flow: Returns a Copia e Cola string and a QR Code image (Base64) that your user can scan to complete the payment.

OpenFinance flow: Include the openFinance object to generate an OpenFinance payment link instead. The user is redirected to their bank's app to authorize the payment.

Once payment is confirmed by the banking network, ConnectPSP will POST a CASHIN_PAID event to your webhookUrl.

Security
bearerAuth
Headers
ApplicationTokenstringrequired

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

Example: {{ApplicationToken}}
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

Payment amount in BRL (Brazilian Reais). Decimal format (e.g. 150.50).

Example: 150.5
externalReferencestring<= 100 charactersrequired

Your internal order or transaction ID. Must be unique per application.

Example: "order_abc123"
expirationInMinutesinteger[ 1 .. 43200 ]

QR Code validity in minutes. Defaults to 1440 (24h) if omitted.

Example: 60
webhookUrlstring(uri)

URL to receive asynchronous payment events (CASHIN_PAID, CASHIN_REFUNDED).

Example: "https://api.yourdomain.com/webhooks/connectpsp"
payerobject(CashInPayer)required
payer.​namestringrequired

Full name of the payer.

Example: "João Silva"
payer.​documentstringrequired

CPF (11 digits) or CNPJ (14 digits) — numbers only.

Example: "12345678909"
openFinanceobject(CashInOpenFinance)

When present, triggers the OpenFinance flow instead of a standard QR Code. The response will include a paymentUrl to redirect the user to their bank's authorization screen.

openFinance.​redirectUrlstring(uri)required

URL to redirect the user after completing payment in their banking app.

Example: "https://yourdomain.com/payment/success"
includeQrCodeImageboolean

If true, the response includes QR Code as Base64. Defaults to true.

Default true
curl -X POST https://api.homologacao.connectpsp.com/cash-in \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.50,
    "externalReference": "order_abc123",
    "expirationInMinutes": 60,
    "webhookUrl": "https://api.yourdomain.com/webhooks/connectpsp",
    "payer": {
      "name": "João Silva",
      "document": "12345678909"
    }
  }'

Responses

Cash-In created successfully.

Bodyapplication/json
transactionIdstring

PIX network TxId (alphanumeric).

Example: "kk6g232xel65a0daee4dd13kk2912714964"
internalCodestring

ConnectPSP short code (7 characters). Use this to poll status.

Example: "US7B1JQ"
externalReferencestring

Your original order reference echoed back.

Example: "order_abc123"
statusstring

Always AWAITING_PAYMENT at creation.

Value"AWAITING_PAYMENT"
Example: "AWAITING_PAYMENT"
amountnumber(decimal)
Example: 150.5
payerobject(CashInResponsePayer)
payer.​namestring
Example: "João Silva"
payer.​documentstring
Example: "12345678909"
payer.​bankDataobject(BankData)

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

payer.​bankData.​ispbstring

Bank ISPB code (8 digits).

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

Bank name.

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

Branch number.

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

Account number.

Example: "123456"
pixDataobject(CashInPixData)
pixData.​copyAndPastestring

Full PIX Copia e Cola string (EMV QR Code payload).

Example: "00020101021226..."
pixData.​qrCodeImageBase64string

QR Code image encoded as Base64. Present only when includeQrCodeImage is true.

Example: "iVBORw0KGgoAAAANSU..."
openFinanceDataobject(CashInOpenFinanceData)
openFinanceData.​paymentUrlstring(uri)

Redirect URL to the user's OpenFinance payment authorization screen.

Example: "https://app.linaopenx.com.br/payments?paymentLinkId=b7116f6a..."
requestedAtstring(date-time)

Transaction creation timestamp (ISO 8601, UTC-3).

Example: "2026-03-10T11:20:00-03:00"
Response
application/json
{
  "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
  "internalCode": "US7B1JQ",
  "externalReference": "order_abc123",
  "status": "AWAITING_PAYMENT",
  "amount": 150.5,
  "payer": {
    "name": "João Silva",
    "document": "12345678909"
  },
  "pixData": {
    "copyAndPaste": "00020101021226...",
    "qrCodeImageBase64": "iVBORw0KGgoAAAANSU..."
  },
  "requestedAt": "2026-03-10T11:20:00-03:00"
}

Get Cash-In

Request

Returns the current status and details of a Cash-In transaction.

Security
bearerAuth
Path
idstringrequired

Transaction identifier — TxId, InternalCode, or EndToEndId.

Example: US7B1JQ
Headers
ApplicationTokenstringrequired

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

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

Responses

Cash-In details returned successfully.

Bodyapplication/json
transactionIdstring
Example: "kk6g232xel65a0daee4dd13kk2912714964"
internalCodestring
Example: "US7B1JQ"
externalReferencestring
Example: "order_abc123"
endToEndIdstring

End-to-end ID issued by BACEN/SPI upon settlement.

  • For paid transactions: starts with E (e.g. E00416968...)
  • For refunded transactions: starts with D (Devolution)
Example: "E00416968202603101827cemeFscF6AG"
originalEndToEndIdstring

The original E2E ID when endToEndId represents a refund.

Example: "E00416968202603101827cemeFscF6AG"
statusstring
Enum"AWAITING_PAYMENT""PAID""EXPIRED""REFUNDED""CANCELLED"
Example: "PAID"
amountnumber(decimal)
Example: 150.5
payerobject(CashInResponsePayer)
payer.​namestring
Example: "João Silva"
payer.​documentstring
Example: "12345678909"
payer.​bankDataobject(BankData)

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

payer.​bankData.​ispbstring

Bank ISPB code (8 digits).

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

Bank name.

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

Branch number.

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

Account number.

Example: "123456"
requestedAtstring(date-time)
Example: "2026-03-10T11:20:00-03:00"
paidAtstring(date-time)
Example: "2026-03-10T11:22:15-03:00"
refundedAtstring(date-time)
Example: "2026-03-11T09:00:00-03:00"
expiredAtstring(date-time)
Response
application/json
{
  "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
  "internalCode": "US7B1JQ",
  "externalReference": "order_abc123",
  "endToEndId": "E00416968202603101827cemeFscF6AG",
  "status": "PAID",
  "amount": 150.5,
  "payer": {
    "name": "João Silva",
    "document": "12345678909",
    "bankData": { … }
  },
  "requestedAt": "2026-03-10T11:20:00-03:00",
  "paidAt": "2026-03-10T11:22:15-03:00"
}

Request Refund

Request

Requests a full refund of a paid Cash-In transaction (PIX Devolution via BACEN/SPI).

⚠️ Important: Only transactions with status PAID can be refunded. Partial refunds are not supported — the full original amount will be returned to the payer.

The refund is sent to the banking network synchronously. The 202 Accepted response includes the new endToEndId generated for the devolution (prefixed with D).

This endpoint requires the DigitalSignature header. See the Authentication Guide for details on how to compute it.

Security
bearerAuth
Path
idstringrequired

Transaction identifier — TxId, InternalCode, or EndToEndId.

Example: US7B1JQ
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
reasonstringrequired

Reason for the refund.

Enum"FRAUD""DUPLICATED_PAYMENT""CUSTOMER_REQUEST""MERCHANT_ERROR"
Example: "CUSTOMER_REQUEST"
descriptionstring

Optional internal note for audit purposes (not sent to payer).

Example: "Customer requested refund via support ticket #1234."
curl -X POST https://api.homologacao.connectpsp.com/cash-in/US7B1JQ/refund \
  -H "Authorization: Bearer <token>" \
  -H "ApplicationToken: <app-token>" \
  -H "DigitalSignature: <computed-signature>" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "CUSTOMER_REQUEST",
    "description": "Customer requested refund via support ticket #1234."
  }'

Responses

Refund accepted and submitted to the banking network.

Bodyapplication/json
transactionIdstring
Example: "kk6g232xel65a0daee4dd13kk2912714964"
internalCodestring
Example: "US7B1JQ"
externalReferencestring
Example: "order_abc123"
endToEndIdstring

New E2E ID for this devolution (starts with D).

Example: "D00416968202603101827cemeFscF6AG"
statusstring
Value"PROCESSING"
Example: "PROCESSING"
amountnumber(decimal)
Example: 150.5
requestedAtstring(date-time)
Example: "2026-03-10T13:30:00-03:00"
messagestring
Example: "The refund for cash-in US7B1JQ has been successfully initiated."
Response
application/json
{
  "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
  "internalCode": "US7B1JQ",
  "externalReference": "order_abc123",
  "endToEndId": "D00416968202603101827cemeFscF6AG",
  "status": "PROCESSING",
  "amount": 150.5,
  "requestedAt": "2026-03-10T13:30:00-03:00",
  "message": "The refund for cash-in US7B1JQ has been successfully initiated."
}

Cash-Out

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

Operations

Account

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

Operations