Request Withdrawal

Use this route to request a withdrawal from the available balance of your account or a specific partner. The withdrawal is processed asynchronously, so the synchronous response returns the status processing.

Important

This route requires prior enablement by Marlim. Contact our support team for more information.

POSTv3/financial/withdrawal

Request Body Params

Attribute	Type	Description
amount	int32	Amount in cents to be withdrawn. Required field, must be an integer greater than or equal to 1000 (R$ 10.00).
sub_seller_id	string	Partner ID for which the withdrawal will be requested. When omitted, the withdrawal is made from your account (seller).

Example Request Body (account withdrawal)

{
  "amount": 10000
}

Example Request Body (partner withdrawal)

{
  "amount": 5000,
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe"
}

Tip

Before requesting a withdrawal, check the available balance using the Get Balance route. The value provided in amount cannot be greater than balance.available.amount.

Withdrawal rules

When requesting a withdrawal, the API validates the following conditions:

Rule	Description
Withdrawal in progress	It is not allowed to start a new withdrawal while another withdrawal is already in progress.
Sufficient balance	The requested amount must be less than or equal to the available balance in cents.
Minimum amount	The minimum withdrawal amount is 1000 cents (R$ 10.00).

Partner withdrawal (sub_seller)

When sub_seller_id is provided, additional rules apply:

Rule	Description
Automatic withdrawal	Partners with automatic_withdrawal equal to true cannot request a manual withdrawal through this route.

Caution

Withdrawal processing with the acquirer happens asynchronously. An HTTP response with status 200 and status: "processing" indicates that the withdrawal was accepted for processing, not that the amount has already been credited to the bank account.

Response Object

Attribute	Type	Description
status	string	Withdrawal status. Returned value: processing.
amount	int32	Amount in cents effectively requested for withdrawal.
withdrawal_id	string	Withdrawal ID.

Example Response

{
  "status": "processing",
  "amount": 10000,
  "withdrawal_id": "withdrawal_1234567890"
}

Error Object

Attribute	Type	Description
errors	array	Array with all errors found while processing the request.
errors[][type]	string	Type of error that occurred.
errors[][message]	string	Detailed message of the error that occurred.

Example error

{
  "errors": [
    {
      "type": "withdrawal",
      "message": "Insufficient balance to withdraw"
    }
  ]
}

Examples

ATTENTION

The values used in the examples below are for illustration only and must not be used to make requests to Marlim APIs.

Account withdrawal

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 10000
}'

Response200

{
  "status": "processing",
  "amount": 10000,
  "withdrawal_id": "withdrawal_1234567890"
}

Partner withdrawal

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 5000,
  "sub_seller_id": "sub_k4m6Rw5rlQszEY7fiuRe"
}'

Response200

{
  "status": "processing",
  "amount": 5000,
  "withdrawal_id": "withdrawal_1234567890"
}

Insufficient balance

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 999999
}'

Response400

{
  "errors": [
    {
      "type": "withdrawal",
      "message": "Insufficient balance to withdraw"
    }
  ]
}

Withdrawal in progress

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000
}'

Response400

{
  "errors": [
    {
      "type": "withdrawal",
      "message": "Already a withdrawal in progress"
    }
  ]
}

Amount below minimum

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 500
}'

Response400

{
  "errors": [
    {
      "type": "amount",
      "message": "The parameter [ amount ] must be at least 1000."
    }
  ]
}

Partner not found

Request

curl -X POST "https://api.marlim.co/v3/financial/withdrawal" \
-H "Content-Type: application/json" \
-H "api_key: api_key_value" \
-d '{
  "amount": 1000,
  "sub_seller_id": "sub_123456789"
}'

Response404

{
  "errors": [
    {
      "type": "not_found",
      "message": "Sub Seller with id [sub_123456789] was not found"
    }
  ]
}