# Create a batch of transactions

This endpoint allows you to create a batch ("payout") with one or multiple money-out transactions from a Mercado Pago account to one or multiple Mercado Pago accounts. The source account must have sufficient funds. A payout can contain up to 1000 transactions, which are created and submitted for processing in a single request. On success, the request returns status 202.

**POST** `/v1/payouts`

## Request parameters

### Header

- `X-Idempotency-Key` (string, required)
  This feature allows you to safely retry requests without the risk of accidentally performing the same action more than once. This is useful for avoiding errors, such as creating two identical transactions, for example. To ensure that each request is unique, it's important to use an exclusive value in the header of your request. We suggest using a UUID V4 or random strings. It is important to note that, starting from 2024/01/01, sending this parameter will become mandatory in all requests.

- `X-signature` (string, optional)
  Request signature with the encrypted `body` in base 64 with the public and private keys of the integrator. It is required only in a productive environment.

- `X-enforce-signature` (boolean, optional)
  Value of type `boolean` indicating whether the integrator will send the signature. It must be `false` for test environments, and `true` for production environments, when the signature is mandatory.

- `X-test-token` (boolean, optional)
  Value of type `boolean` indicating whether the request is a test (`true`) or not (`false`). Always required as `true` when it's a test request. When using this header, it's possible to use `X-enforce-signature` as `true` and use `X-signature` to test the encrypted body validation.

- `external_reference` (string, optional)
  Reference to identify the payout. Accepts up to 50 characters, using only letters, numbers, hyphens (-), and underscores (_). The API may return `202` when it accepts the batch before validation of the format and length of `transactions.external_reference` is complete. If this field is invalid, the transaction will be marked with an error during processing. Check the transaction status to identify the error.

- `description` (string, optional)
  Short text describing the complete payout operation, with all sent transfers. Use only letters, numbers, hyphens (`-`), underscores (`_`), and spaces; do not use punctuation.

- `schedule_date` (string, optional)
  Scheduled date for the payout execution. The value must be in the future and in the standard ISO 8601 UTC-0 format with the date and time of the event (`YYYY-MM-DDTHH:MM:SS`), without timezone. The timezone is automatically inferred based on the country of the request.

- `config` (object, optional)
  An `object` containing payout settings, such as the URL that receives transaction status notifications.

  - `config.notification_url` (string, optional)
  URL available to receive notifications of events related to the transaction, such as changes in its status.

- `transactions` (array, optional)
  List of transactions to be processed in this payout, can contain up to 1000 transactions.

  - `transactions[].external_reference` (string, optional)
  Reference to identify the transaction. Accepts up to 50 characters, using only letters, numbers, hyphens (-), and underscores (_).

  - `transactions[].type` (string, optional)
  Transaction type. The only accepted value is `account`.
Possible enum values:

  - `account`
  Transfer to an account.

  - `transactions[].account` (object, optional)
  Destination Mercado Pago account details. Provide the recipient account email in `email`.

  - `transactions[].account.email` (string, optional)
  Email address of the destination Mercado Pago account. Required for transfers between Mercado Pago accounts.

  - `transactions[].amount` (object, optional)

  - `transactions[].amount.currency` (string, optional)
  Currency used in the transaction. The accepted value is `COP`.

  - `transactions[].amount.value` (number, optional)
  Amount to be debited from the source Mercado Pago account. The minimum value is 1 and the maximum value is 10000000000.

  - `transactions[].description` (string, optional)
  Short text describing this transaction. Use only letters, numbers, hyphens (`-`), underscores (`_`), and spaces; do not use punctuation.

## Response parameters

This endpoint has no response body.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | invalid_payout_id | Invalid data was sent in the request body. The payout was not found. Try sending the request again, validating all fields. |
| 400 | invalid_transaction_id | Invalid data was sent in the request body. The transaction was not found. Try sending the request again, validating all fields. |
| 400 | invalid_signature | Invalid data was sent in the request body. Check if the secret was generated correctly and is registered with Mercado Pago. Also check if the body you are sending is the one that was encrypted. |
| 400 | idempotency_key_required | Invalid data was sent in the request body. The idempotency key (`idempotency_key`) is missing. Try sending the request again, validating all fields. |
| 400 | invalid_account | The `account` object was sent without the email required to identify the destination Mercado Pago account. Provide the recipient account email in `email`. |
| 401 | invalid_token | The value sent as Access Token is incorrect. Please check and try again with the correct value. |
| 403 | forbidden | No permission to access the resource. |
| 404 | not_found | Payout not found. Please check if you provided the correct payout ID. |
| 500 | internal_server_error | An unexpected error occurred on the server. Try the request again. |
| 502 | bad_gateway | An error occurred in the integration with an external service. Try the request again. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/payouts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "external_reference": "MP0197",
  "description": "Payout for seller commissions",
  "schedule_date": "2026-12-31T10:00:00",
  "config": {
  "notification_url": "https://link-your-webhook-notification.com"
  },
  "transactions": [
  {
  "external_reference": "MP0197",
  "type": "account",
  "account": {
  "email": "test@testuser.com"
  },
  "amount": {
  "currency": "COP",
  "value": "50.0"
  },
  "description": "Payment to seller Beltrano"
  }
  ]
  }'
```

## Use cases

### Transfers between Mercado Pago accounts

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/payouts' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "external_reference": "MP0197",
  "description": "Payout for seller commissions",
  "schedule_date": "2026-12-31T10:00:00",
  "config": {
  "notification_url": "https://link-your-webhook-notification.com"
  },
  "transactions": [
  {
  "external_reference": "MP0197",
  "type": "account",
  "account": {
  "email": "test@testuser.com"
  },
  "amount": {
  "currency": "COP",
  "value": "50.0"
  },
  "description": "Payment to seller Beltrano"
  }
  ]
  }'
```