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/api/withdrawals

Request Withdrawal

Creates a Pix withdrawal request and returns identifiers you can track. Send Content-Type: application/json, x-api-key, and x-token on every request.

Authorizations

  • Name
    x-api-key
    Type
    string (header)
    Description

    Required Project API key sent in x-api-key header.

  • Name
    x-token
    Type
    string (header)
    Description

    Required Session token sent in x-token header.

Headers

  • Name
    idempotency-key
    Type
    string (header)
    Description

    Required Unique key that makes POST requests idempotent.

Body

  • Name
    amount
    Type
    number
    Description

    Required Amount in BRL (two decimal places).

  • Name
    key
    Type
    string
    Description

    Required Pix key that will receive the value.

  • Name
    key_type
    Type
    enum
    Description

    Required Pix key type. Available options: cpf, cnpj, email, phone, evp.

  • Name
    transfer_method
    Type
    enum
    Description

    Required Transfer method. Available options: Pix.

  • Name
    description
    Type
    string
    Description

    Description of the withdrawal.

  • Name
    external_ref
    Type
    string
    Description

    External reference.

Request

POST
/api/withdrawals
curl --request POST \
  --url https://my.domain.io/api/withdrawals \
  --header 'Content-Type: application/json' \
  --header 'idempotency-key: <idempotency-key>' \
  --header 'x-api-key: <api-key>' \
  --header 'x-token: <api-key>' \
  --data '
{
  "amount": 3.00,
  "key": "95876150096",
  "key_type": "cpf",
  "transfer_method": "Pix",
  "description": "Withdrawing",
  "external_ref": "Zc1ULDLzSYjMpolha11g3"
}
'

Properties Response

  • Name
    code
    Type
    integer
    Description

    Status code of the response. Example: 200.

  • Name
    content
    Type
    object
    Description

    Withdrawal details.

  • Name
    content.magic_id
    Type
    string
    Description

    Unique identifier for the withdrawal.

  • Name
    content.fee
    Type
    number
    Description

    Fee charged for the withdrawal.

  • Name
    content.amount
    Type
    number
    Description

    Amount in BRL.

  • Name
    content.currency
    Type
    string
    Description

    The currency of the withdrawal (e.g.: "BRL").

  • Name
    content.status
    Type
    string
    Description

    The current status of the withdrawal.

  • Name
    content.transfer_method
    Type
    string
    Description

    Transfer method (e.g.: "Pix").

  • Name
    content.external_ref
    Type
    string
    Description

    External reference.

  • Name
    content.created_at
    Type
    string (date-time)
    Description

    The date and time when the withdrawal was created.

  • Name
    content.updated_at
    Type
    string (date-time)
    Description

    The date and time when the withdrawal was last updated.

  • Name
    message
    Type
    string
    Description

    Response message.

  • Name
    timestamp
    Type
    string (date-time)
    Description

    Response timestamp.

Response

{
  "code": 200,
  "content": {
    "magic_id": "wth_03UdoKvLNLHg",
    "fee": 0.15,
    "amount": 3.00,
    "currency": "BRL",
    "status": "PENDING",
    "transfer_method": "Pix",
    "external_ref": "Zc1ULDLzSYjMpolha11g3",
    "created_at": "2025-02-19T17:15:25.688Z",
    "updated_at": "2025-02-19T17:15:26.703Z"
  },
  "message": "Withdrawal created",
  "timestamp": "2025-02-19T17:15:26.703Z"
}
GET/api/withdrawals

Query Cashout

List Pix withdrawals using filters like magic_id, status, external_ref, end_to_end, and limit. Send Content-Type: application/json, x-api-key, and x-token on every request.

Authorizations

  • Name
    x-api-key
    Type
    string (header)
    Description

    Required Project API key sent in x-api-key header.

  • Name
    x-token
    Type
    string (header)
    Description

    Required Session token sent in x-token header.

Query Parameters

  • Name
    magic_id
    Type
    string
    Description

    Withdrawal magic identifier.

  • Name
    status
    Type
    string
    Description

    Withdrawal status.

  • Name
    external_ref
    Type
    string
    Description

    External reference from creation.

  • Name
    end_to_end
    Type
    string
    Description

    End-to-end Pix identifier.

  • Name
    limit
    Type
    integer
    Description

    Max results to return. Default: 20.

  • Name
    resend
    Type
    boolean
    Description

    When true, resend webhook notifications for matching withdrawals. Default: false.

Request

GET
/api/withdrawals
curl --request GET \
  --url 'https://my.domain.io/api/withdrawals?limit=20' \
  --header 'x-api-key: <api-key>' \
  --header 'x-token: <api-key>'

Webhook Resend

You can request a webhook resend by adding the resend=true query parameter. This is useful when you need to receive the webhook notification again for a specific withdrawal.

The webhook will be resent with the current withdrawal status and data.

Properties Response

Withdrawals listed.

  • Name
    code
    Type
    integer
    Description

    Status code of the response. Example: 200.

  • Name
    content
    Type
    object[]
    Description

    List of withdrawals.

  • Name
    content.magic_id
    Type
    string
    Description

    Withdrawal magic identifier.

  • Name
    content.fee
    Type
    number
    Description

    Fee charged for the withdrawal.

  • Name
    content.amount
    Type
    number
    Description

    Amount in BRL.

  • Name
    content.currency
    Type
    string
    Description

    The currency of the withdrawal (e.g.: "BRL").

  • Name
    content.status
    Type
    string
    Description

    The current status of the withdrawal.

  • Name
    content.end_to_end
    Type
    string
    Description

    End-to-end Pix identifier.

  • Name
    content.transfer_method
    Type
    string
    Description

    Transfer method (e.g.: "Pix").

  • Name
    content.external_ref
    Type
    string
    Description

    External reference.

  • Name
    content.movement
    Type
    object
    Description

    Movement details for the withdrawal.

  • Name
    content.movement.payer
    Type
    object
    Description

    Payer details.

  • Name
    content.movement.payer.name
    Type
    string
    Description

    Payer name.

  • Name
    content.movement.payer.document
    Type
    string
    Description

    Payer document.

  • Name
    content.movement.payer.bank
    Type
    string
    Description

    Payer bank.

  • Name
    content.movement.payer.agency
    Type
    string
    Description

    Payer agency.

  • Name
    content.movement.payer.account
    Type
    string
    Description

    Payer account.

  • Name
    content.movement.payee
    Type
    object
    Description

    Payee details.

  • Name
    content.movement.payee.name
    Type
    string
    Description

    Payee name.

  • Name
    content.movement.payee.document
    Type
    string
    Description

    Payee document.

  • Name
    content.movement.payee.bank
    Type
    string
    Description

    Payee bank.

  • Name
    content.movement.payee.agency
    Type
    string
    Description

    Payee agency.

  • Name
    content.movement.payee.account
    Type
    string
    Description

    Payee account.

  • Name
    content.created_at
    Type
    string (date-time)
    Description

    The date and time when the withdrawal was created.

  • Name
    content.updated_at
    Type
    string (date-time)
    Description

    The date and time when the withdrawal was last updated.

  • Name
    message
    Type
    string
    Description

    Response message.

  • Name
    timestamp
    Type
    string (date-time)
    Description

    Response timestamp.

200

{
  "code": 200,
  "content": [
    {
      "magic_id": "9Wlp_2kGy4t9",
      "fee": 0.15,
      "amount": 3.00,
      "currency": "BRL",
      "status": "PENDING",
      "end_to_end": "E607894312025071873189DAHJSKH12",
      "transfer_method": "Pix",
      "external_ref": "Zc1ULDLzSYjMpolha11g3",
      "movement": {
        "payer": {
          "name": "John Doe",
          "document": "124.682.390-08",
          "bank": "BANCO INTER S.A.",
          "agency": "0001",
          "account": "123456-7"
        },
        "payee": {
          "name": "SYFRA LTDA",
          "document": "12.345.678/0001-90",
          "bank": "BANCO INTER S.A.",
          "agency": "0001",
          "account": "765432-1"
        }
      },
      "created_at": "2025-02-19T17:15:25.688Z",
      "updated_at": "2025-02-19T17:15:26.703Z"
    }
  ],
  "message": "Withdrawals listed",
  "timestamp": "2025-02-19T17:15:26.703Z"
}

Was this page helpful?