# Create a batch of transactions for bank accounts

This endpoint allows creating a batch with one or multiple money out transactions from a Mercado Pago account to other accounts (internal or external), as long as the withdrawal account has funds. The payout can contain up to 1000 transactions that are created and processed in a single request. In case of success, the request will return a response with 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, required)
  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)
  Boolean to indicate whether the integrator will or will not 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)
  Boolean to indicate if the request will be 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. It is generated by the integrator and can be any value that allows transaction tracking, as long as it does not contain special characters (“”, [ ], (), @), does not exceed 64 characters, and is not duplicated. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed.

- `description` (string, optional)
  Short text describing the complete payout operation, with all sent transfers. Limit of 100 characters counting the space between words.

- `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)
  Object containing settings of the user performing the transaction.

  - `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. It is generated by the integrator and can be any value that allows transaction tracking, as long as it does not contain special characters (“”, [ ], (), @), does not exceed 64 characters, and is not duplicated. Numbers (1234), letters (abcde), hyphens (-), and underscores (_) are allowed.

  - `transactions[].type` (string, optional)
  Destination account type. The only possible value is "account" (checking account).

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

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

  - `transactions[].account.number` (string, optional)
  Unique number that represents a bank account. In this case, you must send the unique number that identifies the destination account.

  - `transactions[].account.owner_type` (string, optional)
  Payer's identification document type.

  - `transactions[].account.owner_value` (string, optional)
  Identification number of the destination current account holder. Required for transfers to accounts outside Mercado Pago.

  - `transactions[].account.bank_id` (string, optional)
  Identification number of the bank to which the destination current account belongs. The default value is 3 digits.

  - `transactions[].account.branch` (string, optional)
  Bank branch number of the bank to which the destination account belongs.

  - `transactions[].account.holder` (string, optional)
  First and last name of the destination account holder. Required for transfers to accounts outside Mercado Pago.

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

  - `transactions[].amount.currency` (string, optional)
  Identifier of the currency used in the payout.

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

  - `transactions[].description` (string, optional)
  Short description text of the complete payout operation, with all transfers sent. Limit of 100 characters counting the space between words.

## 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. |
| 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",
  "number": "0000001234567876543210",
  "owner_type": "DNI",
  "owner_value": "12345678",
  "bank_id": "015",
  "branch": "0001",
  "holder": "María González"
  },
  "amount": {
  "currency": "ARS",
  "value": "50.0"
  },
  "description": "Payment to seller Beltrano"
  }
  ]
  }'
```

## Use cases

### Transactions 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": "ARS",
  "value": "50.0"
  },
  "description": "Payment to seller Beltrano"
  }
  ]
  }'
```

### Transactions to other banks from Mercado Pago

```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": {
  "number": "0000001234567876543210",
  "owner_type": "DNI",
  "owner_value": "12345678",
  "bank_id": "015",
  "branch": "0001",
  "holder": "María González"
  },
  "amount": {
  "currency": "ARS",
  "value": "50.0"
  },
  "description": "Payment to seller Beltrano"
  }
  ]
  }'
```