Cashout

Pix withdrawals allow users to transfer funds from their balance to a bank account using the Pix system. On this page, we’ll dive into the different endpoints available to initiate, retrieve, and manage Pix withdrawal requests.

The Cashout Pix model

The Pix withdrawal model contains all the necessary details about a Pix transaction. Each withdrawal includes information about the recipient, destination bank account, amount, and transaction status.

POST/withdraw/pix

Request Withdrawal

This endpoint allows you to create a new transaction for a customer.

Required attributes

Name
amount
Type
integer
Description
Required The amount of the transaction in cents.
Name
key
Type
string
Description
Required Key that will receive the value.
Name
key_type
Type
enum
Description
Required Pix key type (e.g.: "EVP", "EMAIL", "PHONE", "CPF", "CNPJ").
Name
description
Type
string
Description
Description of request.
Name
details
Type
object
Description
Required Details including name and document of recipient.
Name
postback
Type
string
Description
URL to receive transaction updates.
Name
external_ref
Type
string
Description
External reference.

Request

POST

/withdraw/pix

curl -X POST https://api.domain.com/withdraw/pix \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 200,
    "key": "17ce9060-b29d-4ab5-89cd-20550ce6e7ac",
    "key_type": "EVP",
    "description": "Deposit",
    "details": {
      "name": "John doe",
      "document": "124.682.390-08"
    },
    "postback": "https://webhook.site/a37bd3bc-9f9a-468e-8b33-cd69c56afff2"
    "external_ref": "external_ref_withdraw",
  }'

Properties Response

Name
statusCode
Type
number
Description
Status code of request.
Name
message
Type
enum
Description
Status of the transaction (e.g.: "WITHDRAW_REQUEST", "WITHDRAW_FAIL").
Name
data
Type
array
Description
An array of withdrawal batches automatically created to fulfill the requested amount.
Name
timestamp
Type
string (ISO 8601)
Description
The date and time when the transaction was created.

Response

{
  "statusCode": 201,
  "message": "WITHDRAW_REQUEST",
  "data": [
    {
      "amount": 200,
      "event": "WITHDRAWAL",
      "identifier": "38508223304568832",
      "status": "PENDING"
    }
  ],
  "timestamp": "2025-04-10T06:17:56.816Z"
}

GET/withdraw

Query Withdrawal

This endpoint allows you to query a withdraw.

Required params

Name
identifier
Type
string
Description
Param The withdrawal identifier.
Name
external_ref
Type
string
Description
Param The withdrawal external reference.

Request

GET

/withdraw

curl -X GET https://api.domain.com/withdraw \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  --get \
  --data "identifier=<identifier>" \
  --data "external_ref=<external_ref>" \

Properties Response

Name
id
Type
string
Description
Unique identifier for the withdraw.
Name
status
Type
enum
Description
The current status of the withdraw (e.g.: "PAID", "ERROR", "REQUESTED", "PARTIALLY_PAID").
Name
amount
Type
integer
Description
The total amount of the withdraw in cents.
Name
operation
Type
object
Description
Data used to request the withdrawal.
Name
receipt
Type
array
Description
An array of withdrawal batches automatically created to fulfill the requested amount.

Response

{
  "id": "38508223304568832",
  "status": "PAID",
  "amount": 200,
  "operation": {
    "amount": 200,
    "key": "17ce9060-b29d-4ab5-89cd-20550ce6e7ac",
    "key_type": "EVP",
    "description": "Deposit",
    "details": {
      "name": "John doe",
      "document": "124.682.390-08"
    },
    "postback": "https://webhook.site/a37bd3bc-9f9a-468e-8b33-cd69c56afff2",
    "external_ref": "some_ref"
  },
  "receipt": [
    {
      "status": "PAID",
      "endtoend": "E3038525920250417164723123b9c2d",
      "identifier": "f49b3c1a-29d7-4c9e-8fa3-3e4c2f21e9a4",
      "receiver_name": "John doe",
      "receiver_bank": "BANCO INTER S.A.",
      "receiver_bank_ispb": "00416968"
    }
  ]
}