Pix Withdraw

The Cash Out endpoint facilitates secure and efficient PIX-based transfers, empowering businesses with seamless payment solutions for commissions, refunds, or other disbursements. This service offers flexibility and reliability by supporting the following methods:

📘

This guide outlines the integration process for three cash-out solutions:

1. Withdraw via PIX Key: Use a recipient's PIX key for straightforward and direct payments.
2. Withdraw via PIX Key and Bank Account Details: Combine a PIX key with recipient bank account details for enhanced precision.
3. Withdraw via Bank Account Details: Use only detailed bank account information to execute the transfer.

Request Endpoint

All methods use the same endpoint, differing only in their request payload structure

POST /partners-int/accounts/pix/cashout/

Regardless of the withdrawal method, the endpoint remains the same. However, the body structure varies as detailed below.

⚠️

Attention:

• Recipient's Name [ WILL BE REQUIRED SOON. If not informed, will assume value "*" ]

1. Create a Withdrawal Using Only a Bank Account

Request Body

❗️

Account digit in Cash out's

The conversion of cashout requests exclusively via bank account details mandatorily requires the account digit. If the digit field is not provided, the operation will fail.

On the other hand, for cashout requests made using a PIX key, the digit field is not necessary, as the transaction is directly linked to the key registered in the banking system.

Use this case when the only information available about the recipient is their bank account. In the PIX system, any bank account can receive a withdrawal through the payment system. Example:

{
  "payment": {
    "value": "<string>",
    "recipient": {
      "name": "<string>",
      "cpf": "<string>",
      "account": {
        	"ispb": "<string>",
        	"branch": "<string>",
        	"number": "<string>",
        	"digit": "<string>",
          "type": "<string>"
      }
    }
  },
  "transaction": {
    "orderId": "<string>",
    "orderDescription": "<string>"
  },
  "webhook": {
    "url": "<string>",
    "customHeaderName": "<string>",
    "customHeaderValue": "<string>"
  }
}

2. Create a Withdrawal Using Only a PIX Key

Request body

You can use this to request payments using a PIX key. Here's an example request body:

{
  "payment": {
    "key": {
      "value": "string",
      "type": "<string>"
    },
    "value": "<string>",
    "recipient": {
      "name": "<string>",
      "cpf": "<string>",
    }
  },
  "transaction": {
    "orderId": "<string>",
    "orderDescription": "<string>"
  },
  "webhook": {
    "url": "<string>",
    "customHeaderName": "<string>",
    "customHeaderValue": "<string>"
  }
}

3. Create a Withdrawal Using a PIX Key and Bank Account

Request body

Use this in cases where the owner of the PIX key needs to be validated. For instance, when the PIX key must be linked to a specific bank account for regulatory purposes. Example:

{
  "payment": {
    "key": {
      "value": "string",
      "type": "<string>"
    },
    "value": "<string>",
    "recipient": {
      "name": "<string>",
      "cpf": "<string>",
      "account": {
        "ispb": "<string>",
        "branch": "<string>",
        "number": "<string>",
        "digit": "<string>",
        "type": "<string>"
      }
    }
  },
  "transaction": {
    "orderId": "<string>",
    "orderDescription": "<string>"
  },
  "webhook": {
    "url": "<string>",
    "customHeaderName": "<string>",
    "customHeaderValue": "<string>"
  }
}

❗️

Attention:

For scenarios involving the Regulated Market based on recent legislation, it is recommended to include the payment.payer.account details.

Please check https://dev.paybrokers.com/docs/bank-details for more details

⚠️

Attention

You will need to save our Transaction ID in your database, because after the end user made the PIX payment through the QRCode, we will send you a webhook callback notification to your URL address (webhook_url), with our Transaction ID and status PAID in the content.

Success Response Fields

Webhook Return

After the user receives the funds via PIX, the system sends a webhook notification to the specified URL (provided as webhook_url during the transaction setup). This notification includes detailed information about the transaction status, enabling the client system to monitor and update the payment status efficiently and in real time.

📘

Note:

Learn more about webhook parameters in the Webhook Event Verification guide.

The webhook returned from the status change will follow this format.

{
  "id": "<string>",
  "transactionState": "Completed",
  "transactionDate": "<date>",
  "transactionAmount": "<value>",
  "transactionType": "<string>",
  "transactionPaymentType": "<string>",
  "transactionOrderId": "",
  "transactionOrderDescription": "<string>",
  "transactionCharges": "<value>",
  "webhookUrl": "<string>",
  "transactionReceipt": "<string>",
  "transactionReceiptDate": "<date>",
  "transactionReceiptVoucher": "<string>",
  "stateRegisteredDate": "<date>",
  "stateCompletedDate": "<date>",
  "recipient": {
    "name": "<string>",
    "taxNumber": "<string>",
    "bankCode": "<string>",
    "accountAgency": "<string>",
    "accountNumber": "<string>",
    "accountDigit": "<string>"
  }
}