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 passed all balance and fraud checks and was queued for settlement. The payment is not yet deposited in the payee's account.

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",
    "paidAt": "2026-03-10T14:02:30-03:00"
  }
}

Failure (CASHOUT_FAILED):

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

On failure, the funds are returned to your transactional balance automatically — no action needed.

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"

What's Next?

Previous page