# Corporate Withdrawal

The Corporate Withdrawal resource is used to return cash from your Corporate balance to your Banking balance.

Each Corporate Withdrawal debits your Corporate balance right away, creating a Corporate Transaction, and then credits the same amount to your Banking balance, creating a Transaction.

**NOTE:**You choose the externalId of every Corporate Withdrawal, and it must be unique within your Workspace, so a retried request never withdraws the same cash twice.

### The Corporate Withdrawal object

**Attributes**

| Name | Type | Description |
| --- | --- | --- |
| `amount` | INTEGER | Corporate Withdrawal value in cents. Example: 1234 (R$12.34). |
| `corporateTransactionId` | STRING | Id of the Corporate Transaction that debited this amount from your Corporate balance. |
| `created` | STRING | Creation datetime. Example: "2023-05-10T17:10:57.261868+00:00". |
| `externalId` | STRING | Unique id you chose for the Corporate Withdrawal. Example: "my-external-id". |
| `id` | STRING | Unique id for the Corporate Withdrawal. |
| `tags` | LIST OF STRINGS | Tags associated with the Corporate Withdrawal. All tags are returned in lowercase. |
| `transactionId` | STRING | Id of the Transaction created when the cash lands in your Banking balance. Empty while the Corporate Withdrawal has not been processed. |
| `updated` | STRING | Last update datetime. Example: "2023-05-10T17:10:57.261877+00:00". |

### Create a Corporate Withdrawal

`POST /v2/corporate-withdrawal`

Use this route to create a new Corporate Withdrawal and return cash from your Corporate balance to your Banking balance.

**NOTE:**The Corporate Transaction that debits your Corporate balance is created within the same request, so corporateTransactionId comes back filled. The cash is credited to your Banking balance right after, so transactionId comes back empty and is filled in a few moments later.

**NOTE:**The request is refused when your Corporate balance does not cover the amount.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `amount` | REQUIRED | A positive integer that represents the amount in cents to be returned to your Banking balance. Example: 10000 (R$100.00) |
| `externalId` | REQUIRED | Unique id chosen by you to identify the Corporate Withdrawal. An externalId already used in your Workspace is rejected instead of creating a second Corporate Withdrawal. Example: "my-external-id" |
| `tags` | OPTIONAL | Array of up to 100 strings to tag the entity for future queries. Each tag can have up to 100 characters and all tags will be converted to lowercase. Example: ["tony", "stark"] |

**Request**

```python
import starkbank

withdrawal = starkbank.corporatewithdrawal.create(
    withdrawal=starkbank.CorporateWithdrawal(
        amount=10000,
        external_id="my-external-id",
        tags=["tony", "stark"]
    )
)

print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5656565656565656,
    tags=['tony', 'stark'],
    transaction_id=,
    updated=2023-05-10 17:10:57.261877+00:00
)
```

### List Corporate Withdrawals

`GET /v2/corporate-withdrawal`

Get a list of Corporate Withdrawals in chunks of at most 100. If you need smaller chunks, use the limit parameter.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `after` | OPTIONAL | Filter entities created after this date. |
| `before` | OPTIONAL | Filter entities created before this date. |
| `cursor` | OPTIONAL | String used to get the next batch of results. Our SDKs handle this for you. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |
| `limit` | OPTIONAL | Number of results per cursor. Max = 100. Default value = 100. |
| `tags` | OPTIONAL | Filter entities that contain the specified tags. |

**Request**

```python
import starkbank

withdrawals = starkbank.corporatewithdrawal.query(
    after="2023-05-01",
    before="2023-05-30",
    limit=10
)

for withdrawal in withdrawals:
    print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5656565656565656,
    tags=['tony', 'stark'],
    transaction_id=6307474720260096,
    updated=2023-05-10 17:11:31.884502+00:00
)
```

### Get a Corporate Withdrawal

`GET /v2/corporate-withdrawal/:id`

Get a single Corporate Withdrawal by its id.

**Parameters**

| Name | Required | Description |
| --- | --- | --- |
| `id` | REQUIRED | Id of the Corporate Withdrawal entity. |
| `fields` | OPTIONAL | List of strings to filter response JSON keys. Not available in the SDKs. |

**Request**

```python
import starkbank

withdrawal = starkbank.corporatewithdrawal.get("5155165527080960")

print(withdrawal)
```

**Response**

```python
CorporateWithdrawal(
    amount=10000,
    corporate_transaction_id=6341320293482496,
    created=2023-05-10 17:10:57.261868+00:00,
    external_id=my-external-id,
    id=5155165527080960,
    tags=['tony', 'stark'],
    transaction_id=6307474720260096,
    updated=2023-05-10 17:11:31.884502+00:00
)
```

## Available Languages

Code samples on this page are in Python. The same content is available with samples in:

- [Python](https://docs.starkbank.com/api/v2/corporate-withdrawal-python.md)
- [Node.js](https://docs.starkbank.com/api/v2/corporate-withdrawal-node.md)
- [PHP](https://docs.starkbank.com/api/v2/corporate-withdrawal-php.md)
- [Java](https://docs.starkbank.com/api/v2/corporate-withdrawal-java.md)
- [Ruby](https://docs.starkbank.com/api/v2/corporate-withdrawal-ruby.md)
- [Elixir](https://docs.starkbank.com/api/v2/corporate-withdrawal-elixir.md)
- [.NET](https://docs.starkbank.com/api/v2/corporate-withdrawal-dotnet.md)
- [Go](https://docs.starkbank.com/api/v2/corporate-withdrawal-go.md)
- [Clojure](https://docs.starkbank.com/api/v2/corporate-withdrawal-clojure.md)
- [cURL](https://docs.starkbank.com/api/v2/corporate-withdrawal-curl.md)