Withdrawals

Use the withdrawals API to withdraw funds from the Raims account through Pix and track the transfer to the company account. Queries help you plan the withdrawal and check the amount received at the destination.

Check conditions and limits

Use Check withdrawal conditions, with GET /v1/withdrawals/limits, before requesting a withdrawal.

The response shows the available balance, minimum amount per withdrawal and fee for amounts below the stated threshold. The fee is deducted from the requested amount. Monetary values use Brazilian real cents.

In Production, destination_configured indicates whether a destination is registered. The limits object shows the daily and nighttime limits, the current period limit, how much has been used and how much remains. The stated cap for a request considers withdrawal limits; the requested amount must also fit within the available balance and account for the fee.

The daily period starts at 06:00 and ends at 06:00 the next day, in São Paulo time. From 20:00 to 06:00, the withdrawal must also fit within the nighttime limit, which is part of the daily limit. period identifies the current period and period_ends_at gives its end in Unix seconds in UTC. Processing withdrawals use up the limit; a confirmed failure releases the amount.

This query does not reserve money or limits, or guarantee that a request will be accepted. Other withdrawals can change the conditions between the query and the request. Limits consider withdrawals recorded by Raims; transfers made through another channel on the same account can also affect the accepted amount.

In Sandbox, the response shows the simulated balance and minimum and fee rules. destination_configured returns false, and limits returns null. These fields do not show the Production account destination or limits. In Production, limits can also return null when no limits are available to query. This does not mean the account can withdraw without limits.

View withdrawal destinations

Use List withdrawal destinations to check the company own verified Pix keys. Each destination shows the holder name, institution ISPB, key type and masked key. is_default identifies the current default destination; verified_at gives the verification date in Unix seconds in UTC.

The list requires a Production API key. Sandbox returns 403 DATA_ENVIRONMENT_NOT_SUPPORTED because it has no banking destinations. This documentation console accepts only Sandbox keys; query from your integration server without entering a Production key in the browser.

Start without a cursor, process list and copy page.next_after to after while page.has_next is true. A page may have fewer items than page_size or be empty and still indicate another page. Continue using the cursor until has_next is false; do not use the size of list to end navigation. To go back, copy page.previous_before to before, without sending both cursors together. See Listing and pagination.

To check a specific destination, use Retrieve a withdrawal destination and the complete returned id, with the wdst_ prefix. This identifier belongs to the destination, whereas wd_ identifies a withdrawal request. A removed destination or one no longer available to the company returns the same resource not found response.

Querying a destination does not select it or request a transfer. To register a key, remove it or change the default, use

Account, Settings, Withdrawal Pix key.

The API request uses the default available at that time, rather than an ID sent by the requester. Also check the conditions and limits before requesting the withdrawal. The destination can change after the query, and its presence in the list does not guarantee that the withdrawal will be accepted.

Request a Pix withdrawal

Use Request a withdrawal, with POST /v1/withdrawals, and provide amount_cents with the total amount you want to withdraw, including the fee. The request requires a Production API key.

The destination is the default Pix key registered in

Account, Settings, Withdrawal Pix key. The key must belong to the same CNPJ as the company. Raims checks ownership when registering the destination and requesting a withdrawal. The API does not accept or change the destination Pix key. To register or change this key, use the Dashboard before requesting.

The request depends on account withdrawal availability, available balance, the minimum amount and applicable limits. Having a valid API key does not remove these conditions.

A 202 response means the withdrawal still needs to be tracked. Keep the returned id and query GET /v1/withdrawals/{id}. While the withdrawal is pending, processing or has an unknown result, track that same identifier before requesting another withdrawal. A 200 response can show the final result of a repeated request.

If the response reports PIX_WITHDRAWAL_RESULT_UNKNOWN, use the path returned in the Location header to query the withdrawal before requesting another. For insufficient balance or limits, check conditions again. When the error indicates a missing or changed destination, check the default Pix key in the Dashboard.

For the Dashboard flow, see Pix withdrawals.

Automatic withdrawals

Use View automatic withdrawals to read the settings and Update automatic withdrawals to enable, disable or adjust the daily attempt. Both endpoints require a Production API key. The integration uses normal key authentication, without a confirmation code (OTP) or Dashboard session.

Automatic withdrawals use the company destination selected in the Dashboard. Register and verify the company Pix key before enabling the setting. The API does not accept another Pix key or change the withdrawal destination.

Send enabled: true to enable and enabled: false to disable. minimum_amount_cents is the minimum balance that allows an attempt, in Brazilian real cents. This field does not set a fixed amount for each withdrawal: the attempt considers available balance and the remaining Pix limit. If the limit allows only part of the balance to be withdrawn, the remainder stays in the account.

time sets the daily time in HH:mm, in the São Paulo time zone. For example, 18:30 means 18:30 in São Paulo. Omitting a field preserves its current value; null is not accepted. Sending the same values again keeps the settings and the next scheduled attempt.

Saving the settings does not request an immediate withdrawal. next_execution_at gives the next scheduled attempt in Unix seconds in UTC, or null when none is scheduled. That time does not confirm a withdrawal. Disabling automatic withdrawals prevents new attempts; track withdrawals already requested in the history.

The attempt depends on the account being eligible to withdraw and the destination remaining valid. The available balance must reach the configured minimum, and the remaining limit must allow at least the minimum withdrawal amount. If any condition is unmet, no withdrawal occurs in that attempt. The same fee and limit rules as manual withdrawals apply.

Track generated requests in List withdrawals and check their status. Enabled settings or a scheduled next attempt do not prove a completed transfer. For Dashboard steps, see Automatic withdrawals.

View the withdrawal history

Use List withdrawals, with GET /v1/withdrawals. You can filter by status and request date range. requested_gte and requested_lte use Unix seconds in UTC and include the specified instants. By default, newest withdrawals appear first.

The response uses list and page. Start without a cursor, process list and copy page.next_after to after while page.has_next is true. Keep the filters, sorting and same key throughout navigation. To change the query, start again without a cursor.

To go back, use page.previous_before in before. Copy the entire cursor without interpreting or changing its contents, and do not send both cursors together. See Listing and pagination.

Retrieve a withdrawal by ID

Use Retrieve a withdrawal, with GET /v1/withdrawals/{id}. Provide the complete id, with the wd_ prefix, returned in the list.

In the Account statement, an entry with reference_type: 3 can provide that identifier in reference_id. Use it to query the related withdrawal and check its result. The withdrawal ID differs from the entry ID, which uses the st_ prefix.

Amounts and destination

Amounts use Brazilian real cents:

For example, a withdrawal with amount_cents: 10000 and fee_amount_cents: 100 has net_amount_cents: 9900, equivalent to R$99.00 for the destination. These amounts do not confirm the transfer. Consider the withdrawal complete only when status is COMPLETED; failure or cancellation does not prove receipt or collection of the fee.

pix_destination identifies the available Pix destination, with a masked key. bank_account shows available details of a bank account used in the withdrawal, also with a masked account number. These fields are null when details of that destination type are unavailable. Querying the history does not let you change the registered destination.

Track the withdrawal status

Check status before considering the withdrawal complete:

requested_at shows when the withdrawal was requested. Completion, failure and cancellation dates are null until the corresponding result is recorded. All use Unix seconds in UTC.

When a failure occurs, failure_reason gives a public code and a message in English. Use the code in integration handling. The message is for diagnostics; you do not need to compare its literal wording. See Withdrawal failure reasons to understand each code and the checks indicated before another request.

Repeated queries do not start or speed up a withdrawal. A pending or processing record does not prove that money reached the destination account.

Company and environment

Requests require an API key and use the company and environment linked to it. A Sandbox key does not access Production withdrawals. If there are no withdrawals in the queried environment, the list returns an empty list. Withdrawal requests are available only in Production; a Sandbox key lets you query simulated history and test conditions, but does not request a transfer.

This documentation console accepts only Sandbox keys. The individual query returns the same resource not found response when the ID does not exist or does not belong to the company and environment of the key.