Skip to main content

Withdrawals (Pix-Out)

Withdrawals are the most critical flow in an iGaming integration. A deposit that fails inconveniences a player; a withdrawal that is mishandled sends real money out of your account — sometimes twice.

API: POST /v1/pix/withdraw/pix-key, POST /v1/pix/withdraw/manual, GET /v1/pix/withdraw/{externalId}

The flow, and when balance moves​

The debit happens before the API call and is only reversed on a confirmed failure. That ordering is what prevents a player from spending balance that is already in flight.

Both withdrawal endpoints answer 202 Accepted, not 200. The request was accepted for processing — the money has not moved yet.

Never cancel a withdrawal without querying it first

A cancellation is a decision about an outcome you have not confirmed. Always run GET /v1/pix/withdraw/{externalId} and act on the status it returns — if it is still transitional, the answer is to wait, not to cancel.

INITIATED is not a failure

While the status is INITIATED, CONFIRMED or PROCESSING, the outcome is unknown. Do not cancel the withdrawal, and do not return the balance to the player's wallet.

Return balance only after pixWithdrawFailed, or after a GET returns a terminal failure status.

Two withdrawal methods​

By PIX key — recommended​

curl --request POST \
  --url "https://api.sdb.lbpay.com.br/v1/pix/withdraw/pix-key" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data '{
    "externalId": "8c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
    "amount": 10000,
    "pixKey": "12345678909",
    "expectedCreditor": {
      "name": "Player Full Name",
      "taxId": "12345678909"
    }
  }'

Accepts CPF, e-mail, phone and random keys. LB Pay resolves the key through DICT, so the destination is validated before the transfer is attempted.

expectedCreditor is required, and it is what enforces the ownership rule: LB Pay compares the CPF you declare against the CPF that actually holds the key, and rejects the mismatch instead of paying the wrong person.

By bank details — manual​

curl --request POST \
  --url "https://api.sdb.lbpay.com.br/v1/pix/withdraw/manual" \
  --header "Authorization: Bearer $TOKEN" \
  --header 'content-type: application/json' \
  --data '{
    "externalId": "9d2e3f4a-5b6c-7d8e-9f0a-1b2c3d4e5f6a",
    "amount": 10000,
    "creditor": {
      "name": "Player Full Name",
      "taxId": "12345678909",
      "personType": "NATURAL_PERSON",
      "bankCode": "12345678",
      "branchCode": "0001",
      "accountNumber": "1234567",
      "accountType": "CACC"
    }
  }'

Use this when the player has no PIX key registered. bankCode is the ISPB of the destination institution. This path is more error-prone precisely because nothing resolves the destination for you — every digit comes from your side.

Idempotency is not optional here​

Each withdrawal carries an externalId that you generate, persist before sending, and reuse on every retry of that same withdrawal. This is what stops a network timeout from becoming a second payment.

Read Idempotency before implementing this endpoint, and Retries and timeouts for the procedure after a failed request.

Ownership rejection​

If the destination CPF does not match the player's registered CPF, the request is rejected with 422 and IGAMING_CPF_MISMATCH. This is definitive — do not retry it. Ask the player for a PIX key registered to their own CPF. See Ownership rules.