# ConnectPSP API

**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](../guides/authentication.md) |

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

| Phase | What to confirm first |
|---|---|
| **Setup** | Credentials, environment, headers, and webhook readiness in [Initial Setup](../tutorials/initial-setup.md) |
| **Authentication** | JWT generation and `DigitalSignature` rules in the [Authentication Guide](../guides/authentication.md) |
| **Transactions** | Your first Cash-In or Cash-Out flow with idempotency and webhook validation |


Version: 2.0.0

## Servers

Staging Environment (Testing)
```
https://api.homologacao.connectpsp.com
```

## Security

### bearerAuth

JWT token obtained from `POST /auth/token`. Expires in 1 hour.

Type: http
Scheme: bearer
Bearer Format: JWT

### applicationToken

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

Type: apiKey
In: header
Name: ApplicationToken

## Download OpenAPI description

[ConnectPSP API](https://docs.connectpsp.com/_bundle/apis/index.yaml)

## Authentication

Obtain JWT tokens to authenticate all other requests.

### Obtain JWT Token

 - [POST /auth/token](https://docs.connectpsp.com/apis/authentication/authtoken.md): 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

## Cash-In

Generate and manage inbound PIX payments. Supports standard QR Code and OpenFinance flows.


### Create Cash-In

 - [POST /cash-in](https://docs.connectpsp.com/apis/cash-in/createcashin.md): 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.

### Get Cash-In

 - [GET /cash-in/{id}](https://docs.connectpsp.com/apis/cash-in/getcashin.md): Returns the current status and details of a Cash-In transaction.

### Request Refund

 - [POST /cash-in/{id}/refund](https://docs.connectpsp.com/apis/cash-in/refundcashin.md): 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.

## Cash-Out

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


### Create Cash-Out

 - [POST /cash-out](https://docs.connectpsp.com/apis/cash-out/createcashout.md): 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.

### Get Cash-Out

 - [GET /cash-out/{id}](https://docs.connectpsp.com/apis/cash-out/getcashout.md): 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)

## Account

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


### Get Balance

 - [GET /account/balance](https://docs.connectpsp.com/apis/account/getbalance.md): Returns the consolidated and detailed wallet snapshot across all banking partners (Delbank, Celcoin, StarkBank).

Two account types are tracked per bank:
- Transactional — funds available to cover Cash-Out requests (mirrors your users' exposure)
- Proprietary — reserve/buffer account (your operational capital)

> ℹ️ Note: Historical balance lookup (?date=) is currently in development. Only the current balance is available.

### Rebalance Wallet

 - [POST /account/rebalance](https://docs.connectpsp.com/apis/account/rebalanceaccount.md): Synchronizes your Transactional account to match the total exposure you report.

How it works:
- If targetAmount is greater than the current transactional balance → funds are pulled from the Proprietary account (Top-up)
- If targetAmount is less than the current transactional balance → excess funds are swept back to the Proprietary account

The targetAmount represents the total exposure of your platform (sum of all user wallet balances + in-flight bets).

This endpoint requires the DigitalSignature header.