Skip to content
Last updated

Your First Cash-In

This tutorial walks you through the complete Cash-In flow — from generating a PIX QR Code to confirming the payment via webhook.

Estimated time: ~10 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 from the response. It expires in 1 hour.

Step 2 — Create a Cash-In

curl -X POST https://api.homologacao.connectpsp.com/cash-in \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "ApplicationToken: YOUR_APP_TOKEN" \
  -H "X-Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 10.00,
    "externalReference": "test-order-001",
    "expirationInMinutes": 30,
    "webhookUrl": "https://YOUR_DOMAIN/webhooks/connectpsp",
    "payer": {
      "name": "Test User",
      "document": "12345678909"
    }
  }'

Response 201 Created:

{
  "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
  "internalCode": "US7B1JQ",
  "externalReference": "test-order-001",
  "status": "AWAITING_PAYMENT",
  "amount": 10.00,
  "payer": { "name": "Test User", "document": "12345678909" },
  "pixData": {
    "copyAndPaste": "00020101021226...",
    "qrCodeImageBase64": "iVBORw0KGgoAAAANSU..."
  },
  "requestedAt": "2026-03-10T11:20:00-03:00"
}

The pixData.copyAndPaste string can be presented to your user for payment. The QR Code can be rendered from the Base64 image directly in a browser <img> tag.

Step 3 — Display the QR Code to Your User

<img src="data:image/png;base64,iVBORw0KGgoAAAANSU..." alt="PIX QR Code" />
<p>Or copy and paste: <code>00020101021226...</code></p>

Step 4 — Receive the Webhook

Once the user pays, ConnectPSP POSTs to your webhookUrl:

{
  "eventType": "CASHIN_PAID",
  "eventAt": "2026-03-10T11:22:18Z",
  "data": {
    "transactionId": "kk6g232xel65a0daee4dd13kk2912714964",
    "internalCode": "US7B1JQ",
    "externalReference": "test-order-001",
    "endToEndId": "E00416968202603101827cemeFscF6AG",
    "status": "PAID",
    "amount": 10.00,
    "payer": {
      "name": "Test User",
      "document": "12345678909",
      "bankData": {
        "ispb": "00000000",
        "bank": "Banco do Brasil S.A.",
        "branch": "0001",
        "account": "123456"
      }
    },
    "requestedAt": "2026-03-10T11:20:00-03:00",
    "paidAt": "2026-03-10T11:22:15-03:00"
  }
}

Respond with 200 OK immediately. Credit the user's balance using data.externalReference to identify the order.

Step 5 — (Optional) Confirm via Polling

If you missed the webhook or want to double-check, poll the transaction status:

curl https://api.homologacao.connectpsp.com/cash-in/US7B1JQ \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "ApplicationToken: YOUR_APP_TOKEN"

What's Next?

Previous page
Next page