Skip to content
Last updated

Your First Cash-Out

This tutorial walks you through sending a PIX payment — from authentication to receiving the settlement confirmation webhook.

Estimated time: ~15 minutes

Step 1 — Authenticate

curl -X POST https://api.homologacao.connectpsp.com/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

Save the accessToken — you'll use it both in the Authorization header and to compute the DigitalSignature.

Step 2 — Compute the Digital Signature

Cash-Out requires a DigitalSignature header. It's an HMAC-SHA256 hash of your JWT token:

SIGNATURE=$(echo -n "$ACCESS_TOKEN" | openssl dgst -sha256 -hmac "$CRYPTO_TOKEN" | awk '{print $2}')

See the Authentication Guide for examples in Node.js and Python.

Step 3 — Send the Cash-Out

Option A — Via PIX Key:

curl -X POST https://api.homologacao.connectpsp.com/cash-out \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "ApplicationToken: YOUR_APP_TOKEN" \
  -H "DigitalSignature: $SIGNATURE" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "externalReference": "withdrawal-user-42-001",
    "description": "User withdrawal",
    "webhookUrl": "https://YOUR_DOMAIN/webhooks/connectpsp",
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "PIX",
        "pixKeyType": "CPF",
        "pixKey": "12345678909"
      }
    }
  }'

Option B — Via Bank Account Data:

curl -X POST https://api.homologacao.connectpsp.com/cash-out \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "ApplicationToken: YOUR_APP_TOKEN" \
  -H "DigitalSignature: $SIGNATURE" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50.00,
    "externalReference": "withdrawal-user-42-001",
    "description": "User withdrawal",
    "webhookUrl": "https://YOUR_DOMAIN/webhooks/connectpsp",
    "payee": {
      "name": "Maria Silva",
      "document": "12345678909",
      "destination": {
        "type": "BANK_ACCOUNT",
        "bankAccount": {
          "ispb": "18236120",
          "branch": "0001",
          "account": "947710840",
          "accountType": "PAYMENT"
        }
      }
    }
  }'

Response 202 Accepted:

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

202 Accepted means the request was accepted for processing — nothing more. Balance, withdrawal limits, the PIX key and the receiving institution are checked after this response, so the Cash-Out can still be cancelled (for example with INSUFFICIENT_FUNDS or DAILY_LIMIT_EXCEEDED). The payment is not yet deposited in the payee's account; the outcome arrives by webhook.

X-Idempotency-Key is optional but recommended: if the request times out and you retry it with the same key and body, you get the original response instead of a second Cash-Out. See Idempotency.

Step 4 — Wait for the Settlement Webhook

Within seconds to a few minutes (depending on banking network), ConnectPSP posts to your webhookUrl:

Success (CASHOUT_COMPLETED):

{
  "eventType": "CASHOUT_COMPLETED",
  "eventAt": "2026-03-10T14:02:35Z",
  "data": {
    "internalCode": "IVKPRMOCDY",
    "externalReference": "withdrawal-user-42-001",
    "endToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "COMPLETED",
    "amount": 50.00,
    "payee": { "name": "Maria Silva", "document": "12345678909", ... },
    "requestedAt": "2026-03-10T14:00:00-03:00",
    "completedAt": "2026-03-10T14:02:30-03:00"
  }
}

Cancelled (CASHOUT_FAILED):

{
  "eventType": "CASHOUT_FAILED",
  "eventAt": "2026-03-10T14:00:20Z",
  "data": {
    "internalCode": "IVKPRMOCDY",
    "status": "CANCELLED",
    "failure": {
      "code": "PIX_KEY_NOT_FOUND",
      "message": "The provided PIX key did not resolve to a valid account."
    },
    "cancelledAt": "2026-03-10T14:00:15-03:00",
    ...
  }
}

CANCELLED means the money never left your account — it stays in your transactional balance, no action needed. failure.code tells you why and whether to try again; see the failure.code table. To try again, send a new Cash-Out with a new externalReference.

Step 5 — (Optional) Poll for Status

curl https://api.homologacao.connectpsp.com/cash-out/IVKPRMOCDY \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "ApplicationToken: YOUR_APP_TOKEN"

The {id} also accepts your own externalReference (here, withdrawal-user-42-001), the transactionId and the endToEndId. The response body is the same object you receive in the webhook data, with status one of PROCESSING, PENDING, COMPLETED, CANCELLED or REFUNDED.

What's Next?

Previous page