> For the complete documentation index, see [llms.txt](https://docs.lime-pay.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lime-pay.com/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint.md).

# Cashout Creation Endpoint

## Cashout Request

<mark style="color:green;">`POST`</mark> `https://api-stg.lime-pay.com/v3/cashout`

This endpoint allows you to generate cashout requests

#### Headers

| Name                                                | Type   | Description        |
| --------------------------------------------------- | ------ | ------------------ |
| Content-Type<mark style="color:red;">\*</mark>      | string | `application/json` |
| Payload-Signature<mark style="color:red;">\*</mark> | string | Control signature  |

#### Request Body

| Name                                                | Type    | Description                                                                                   |
| --------------------------------------------------- | ------- | --------------------------------------------------------------------------------------------- |
| login<mark style="color:red;">\*</mark>             | string  | Your Lime-Pay CASHOUTS API login key                                                          |
| pass<mark style="color:red;">\*</mark>              | string  | Your Lime-Pay CASHOUTS API pass key                                                           |
| external\_id<mark style="color:red;">\*</mark>      | string  | Unique cashout ID on the merchant end                                                         |
| country<mark style="color:red;">\*</mark>           | string  | Country of the cashout                                                                        |
| amount<mark style="color:red;">\*</mark>            | number  | Amount of the cashout                                                                         |
| currency                                            | string  | Currency in which the amount was specified                                                    |
| document\_id<mark style="color:red;">\*</mark>      | string  | Document ID of the beneficiary                                                                |
| document\_type                                      | string  | Document type of the ID specified                                                             |
| beneficiary\_name<mark style="color:red;">\*</mark> | string  | Beneficiary's name                                                                            |
| beneficiary\_lastname                               | string  | Beneficiary's last name                                                                       |
| email                                               | string  | Beneficiary's email address                                                                   |
| phone                                               | string  | Beneficiary's phone number                                                                    |
| bank\_code                                          | number  | Beneficiary's bank code                                                                       |
| bank\_account                                       | string  | Beneficiary's bank account                                                                    |
| bank\_branch                                        | string  | Beneficiary's branch of their bank account                                                    |
| account\_type                                       | string  | Beneficiary's account type                                                                    |
| address                                             | string  | Beneficiary's address                                                                         |
| city                                                | string  | Beneficiary's city                                                                            |
| postal\_code                                        | string  | Beneficiary's postal code                                                                     |
| beneficiary\_birthdate                              | string  | Beneficiary's birthdate                                                                       |
| notification\_url<mark style="color:red;">\*</mark> | string  | URL where the notifications will be sent                                                      |
| comments                                            | string  | Commentaries about the cashout                                                                |
| on\_hold                                            | boolean | Used to mark a cashout as on hold and not process it until manually changed to pending by you |

{% tabs %}
{% tab title="200 Cashout request successfully created." %}

```bash
{
    "cashout_id": "8405147"
}
```

{% endtab %}

{% tab title="401 The credentials specified are incorrect." %}

```bash
{
    "code": 401,
    "message": "Invalid credentials."
}
```

{% endtab %}

{% tab title="412 Error in the data validation." %}

```bash
{
    "code": 303,
    "message": "Invalid bank code"
}

{
    "code": 300,
    "message": "bank_account: must not be null; Invalid Bank account"
}
```

{% endtab %}
{% endtabs %}

## Request Fields Description

| Field                  | Format                         | Description                                                                                                                                        |                                               Validations                                              |
| ---------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------: |
| login                  | string (max length: 32)        | Your Lime-Pay **CASHOUTS** API Key, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials |                                                                                                        |
| pass                   | string (max length: 32)        | Your Lime-Pay  API Passphrase, found on the Merchant Panel by going to: Settings -> API Access. Notice there are specific Cashout credentials      |                                                                                                        |
| external\_id           | string (max length: 100)       | Unique cashout ID on the merchant end                                                                                                              |                                                                                                        |
| country                | string (length: 2)             | Country code for the cashout in *ISO 3166-1 alpha-2 code* format                                                                                   |               [See country codes](/knowledge-base/countries-specifications.md#currencies)              |
| amount                 | Big Decimal (up to 2 decimals) | Cashout amount on the currency specified                                                                                                           |                                              Valid number                                              |
| currency               | string (length: 3)             | Currency code of the amount in *ISO 4217* format                                                                                                   |             [See valid currencies](/knowledge-base/countries-specifications.md#currencies)             |
| document\_id           | string (max length: 40)        | Beneficiary’s personal identification number                                                                                                       |            [See document validations](/knowledge-base/countries-specifications.md#documents)           |
| document\_type         | string (maxLength: 15)         | Beneficiary’s personal identification number type                                                                                                  |         [See document types validations](/knowledge-base/countries-specifications.md#documents)        |
| beneficiary\_name      | string (max length: 100)       | Beneficiary's name                                                                                                                                 |                                     String of up to 100 characters                                     |
| beneficiary\_lastname  | string (max length: 100)       | Beneficiary's last name                                                                                                                            |                                     String of up to 100 characters                                     |
| email                  | string (maxLength: 100)        | Beneficiary's valid email address                                                                                                                  |          [Valid email address](/knowledge-base/countries-specifications.md#emails-validations)         |
| phone                  | string (maxLength: 20)         | Beneficiary's phone number                                                                                                                         | [See phone number validations](/knowledge-base/countries-specifications.md#mobile-numbers-validations) |
| bank\_code             | Integer (max length: 6)        | Beneficiary's bank code                                                                                                                            |          [See bank codes API](/api-documentation/cashouts-api/endpoints/cashout-bank-codes.md)         |
| bank\_account          | string (max length: 30)        | Beneficiary's bank account number                                                                                                                  | [See bank\_account validations](/api-documentation/cashouts-api/countries-validations.md#bank-account) |
| bank\_branch           | string (max length: 15)        | Beneficiary's bank branch number                                                                                                                   |  [See bank\_branch validations](/api-documentation/cashouts-api/countries-validations.md#bank-branch)  |
| account\_type          | string (max length: 1)         | Type of account                                                                                                                                    |    [See bank\_account types](/api-documentation/cashouts-api/countries-validations.md#account-types)   |
| address                | string (max length: 255)       | Beneficiary's address                                                                                                                              |                                     String of up to 200 characters                                     |
| city                   | string (max length: 100)       | Beneficiary's city                                                                                                                                 |                                     String of up to 100 characters                                     |
| postal\_code           | string (max length: 20)        | Beneficiary's postal code                                                                                                                          |   [See postal\_code validations](/knowledge-base/countries-specifications.md#postal-code-validations)  |
| beneficiary\_birthdate | string (pattern: 'YYYYMMDD')   | Beneficiary's birthdate                                                                                                                            |                                                                                                        |
| notification\_url      | string (max length: 300)       | To be provided if the notification URL is different from the notification URL defined on the Merchant Panel                                        |                                          Valid URL over HTTPS                                          |
| comments               | string (max length: 200)       | A commentary for this cashout                                                                                                                      |                                     String of up to 200 characters                                     |
| on\_hold               | boolean                        | If the merchant wants to hold the cashout and set it to process later through the merchants panel. Default: false                                  |                                             `[true, false]`                                            |

## Fields required

Each country has different requirements and therefore we ask for different fields you need to send on the requests.&#x20;

Go to the[ Countries Validations ](/api-documentation/cashouts-api/countries-validations.md)page to check each country requirements and validations.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.lime-pay.com/api-documentation/cashouts-api/endpoints/cashout-creation-endpoint.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.