# Create payment

This endpoint creates an advanced payment for Wallet Connect. During the agreement process, the integrator receives a payer token from the buyer. This token allows the integrator to execute the payment directly from the buyer's wallet. To apply discounts, create a discount promise before using this endpoint. In case of success, the request will return a response with status 201.

**POST** `/v1/advanced_payments`

## 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 payments, 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.

- `X-Meli-Session-Id` (string, optional)
  Device identifier used to improve security and increase the payment approval rate. It represents a unique identifier for the buyer's device at the time of purchase.

- `wallet_payment` (object, optional)
  Payment data from a seller with a prior Wallet Connect agreement.

  - `wallet_payment.transaction_amount` (number, optional)
  Payment amount.

  - `wallet_payment.description` (string, optional)
  Brief description of the payment.

  - `wallet_payment.external_reference` (string, optional)
  Custom seller reference used to correlate a Mercado Pago payment with an internal order.

  - `wallet_payment.statement_descriptor` (string, optional)
  Text that appears on the cardholder's bank statement along with the amount and date of the charge. Accepts a maximum of 50 alphanumeric characters.

  - `wallet_payment.forward_data` (object, optional)
  Information that payment facilitators must send to identify sub-merchants during the transaction. Required only for transactions in Brazil (MLB).

  - `wallet_payment.forward_data.sub_merchant` (object, optional)
  Sub-merchant data used by payment facilitators to identify the sub-merchant at the time of the transaction.

  - `wallet_payment.forward_data.sub_merchant.sub_merchant_id` (number, optional)
  Sub-merchant code.

  - `wallet_payment.forward_data.sub_merchant.mcc` (string, optional)
  Sub-merchant MCC (Merchant Category Code) according to Abecs classification and/or primary CNAE.

  - `wallet_payment.forward_data.sub_merchant.country` (string, optional)
  Country where the sub-merchant is located.

  - `wallet_payment.forward_data.sub_merchant.address_door_number` (number, optional)
  Street number where the sub-merchant is located.

  - `wallet_payment.forward_data.sub_merchant.zip` (string, optional)
  Postal code of the sub-merchant.

  - `wallet_payment.forward_data.sub_merchant.document_number` (string, optional)
  CPF or CNPJ of the sub-merchant.

  - `wallet_payment.forward_data.sub_merchant.city` (string, optional)
  City where the sub-merchant is located.

  - `wallet_payment.forward_data.sub_merchant.address_street` (string, optional)
  Street where the sub-merchant is located.

  - `wallet_payment.forward_data.sub_merchant.legal_name` (string, optional)
  Legal name of the sub-merchant.

  - `wallet_payment.forward_data.sub_merchant.region_code_iso` (string, optional)
  ISO code of the state where the sub-merchant is located.

  - `wallet_payment.forward_data.sub_merchant.region_code` (string, optional)
  Country code of the sub-merchant.

  - `wallet_payment.forward_data.sub_merchant.document_type` (string, optional)
  Document type of the sub-merchant (CPF or CNPJ).

  - `wallet_payment.forward_data.sub_merchant.phone` (object, optional)
  Phone number of the sub-merchant.

  - `wallet_payment.forward_data.sub_merchant.url` (string, optional)
  URL of the payment facilitator.

  - `wallet_payment.discount` (object, optional)
  Discount to be applied to the payment. Requires a previously created discount promise.

  - `wallet_payment.discount.amount` (number, optional)
  Amount to be deducted from the total payment.

  - `wallet_payment.discount.description` (string, optional)
  Description of the discount being applied.

  - `wallet_payment.discount.code` (number, optional)
  Unique identifier of the coupon used for the discount. Send only when the buyer entered a coupon code during the purchase flow.

  - `wallet_payment.discount.detail` (object, optional)
  Detailed discount information.

  - `wallet_payment.discount.detail.cap` (number, optional)
  Maximum amount that can be deducted from the payment.

  - `wallet_payment.discount.detail.type` (string, optional)
  Type of discount applied.

  - `wallet_payment.discount.detail.value` (number, optional)
  Discount value according to its type.

- `payer` (object, optional)
  Buyer information required to process the payment.

  - `payer.token` (string, optional)
  Payer token obtained from the agreement flow. Used by the integrator to charge the buyer's wallet.

  - `payer.type_token` (string, optional)
  Type of the token. Must be "wallet-tokens" for Wallet Connect payments.

- `binary_mode` (boolean, optional)
  When enabled, the payment can only be approved or rejected. Otherwise, the payment may remain pending.

- `capture` (boolean, optional)
  Indicates whether to capture the payment immediately. In two-step payments, set to "false" to reserve the amount first, then capture it by sending "true" in a separate request.

## Response parameters

- `id` (number, optional)
  Unique identifier of the advanced payment.

- `payments` (array, optional)
  List of payments generated within the advanced payment.

  - `payments[].id` (number, optional)
  Unique payment identifier.

  - `payments[].status` (string, optional)
  Current status of the payment.
Possible enum values:

  - `approved`
  The payment was approved.

  - `in_process`
  The payment is being processed.

  - `rejected`
  The payment was rejected.

  - `payments[].status_detail` (string, optional)
  Detailed reason for the payment status.

  - `payments[].payment_type_id` (string, optional)
  Payer's preferred payment type.
Possible enum values:

  - `credit_card`
  Credit card.

  - `debit_card`
  Debit card.

  - `account_money`
  Account balance.

  - `payments[].payment_method_id` (string, optional)
  Payment method used.

  - `payments[].transaction_amount` (number, optional)
  Payment amount.

  - `payments[].installments` (number, optional)
  Number of installments.

  - `payments[].description` (string, optional)
  Description of the product or service purchased.

  - `payments[].capture` (boolean, optional)
  Indicates whether the payment amount was captured. In two-step payments, the purchase value is first reserved ("capture" = "false") and then captured ("capture" = "true") when the funds are transferred to the collector.

  - `payments[].external_reference` (string, optional)
  Custom seller reference used to correlate a Mercado Pago payment with an internal order.

- `wallet_payment` (object, optional)
  Wallet payment data from a seller with a prior Wallet Connect agreement.

  - `wallet_payment.transaction_amount` (number, optional)
  Payment amount.

  - `wallet_payment.description` (string, optional)
  Brief description of the payment.

  - `wallet_payment.external_reference` (string, optional)
  Custom seller reference used to correlate a Mercado Pago payment with an internal order.

  - `wallet_payment.discount` (object, optional)
  Discount applied to the payment, when applicable.

  - `wallet_payment.discount.amount` (number, optional)
  Amount deducted from the total payment.

  - `wallet_payment.discount.code` (number, optional)
  Unique identifier of the coupon used for the discount.

- `disbursements` (array, optional)
  List of disbursements distributed among the sellers.

  - `disbursements[].collector_id` (string, optional)
  Mercado Pago account ID of the seller receiving the disbursement.

- `payer` (object, optional)

  - `payer.id` (number, optional)
  Buyer's Mercado Pago user ID.

- `site_id` (string, optional)
  Country of origin of the Mercado Pago account.

- `binary_mode` (boolean, optional)
  When enabled, the payment can only be approved or rejected. Otherwise, the payment may remain pending.

- `date_created` (string, optional)
  Date and time the payment was created, in ISO 8601 format.

- `date_last_updated` (string, optional)
  Date and time of the last update to the payment, in ISO 8601 format.

## Errors

| Status | Error | Description |
| ------- | ------- | ----------- |
| 400 | empty_required_header | The "X-Idempotency-Key" header is required and was not sent. Make the request again including it. |
| 500 | internal_error | Some error occurred on our side while attempting to process the request. Please try again later. |

## Request example

### cURL

```bash
curl -X POST \
  'https://api.mercadopago.com/v1/advanced_payments' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <ACCESS_TOKEN>' \
  -d '{
  "wallet_payment": {
  "transaction_amount": "24.50",
  "description": "Payment for the purchase of furniture",
  "external_reference": "Payment_seller_123",
  "statement_descriptor": "descriptor",
  "forward_data": {
  "sub_merchant": {
  "sub_merchant_id": "123123",
  "mcc": "5462",
  "country": "UY",
  "address_door_number": "1294",
  "zip": "11300",
  "document_number": "222222222222222",
  "city": "Montevideo",
  "address_street": "RUA A",
  "legal_name": "LOJINHA DO ZÉ",
  "region_code_iso": "BR-MG",
  "region_code": "BR",
  "document_type": "CI",
  "phone": "1234-5678",
  "url": "www.nomedofacilitador.com.br"
  }
  },
  "discount": {
  "amount": 10,
  "description": "DESC20",
  "code": "WALLET10",
  "detail": {
  "cap": 1000000,
  "type": "percentage",
  "value": 10
  }
  }
  },
  "payer": {
  "token": "abcdef1e23f4567d8e9123eb6591ff68df74c57930551ed980239f4538a7e530",
  "type_token": "wallet-tokens"
  },
  "binary_mode": false,
  "capture": true
  }'
```

## Response example

```json
{
  "id": 10267812,
  "payments": [
  {
  "id": 3870106238,
  "status": "approved",
  "status_detail": "accredited",
  "payment_type_id": "credit_card",
  "payment_method_id": "credit_card",
  "transaction_amount": "24.50",
  "installments": 1,
  "description": "Payment for the purchase of furniture",
  "capture": true,
  "external_reference": "payment_123"
  }
  ],
  "wallet_payment": {
  "transaction_amount": "24.50",
  "description": "Payment for the purchase of furniture",
  "external_reference": "Payment_seller_123",
  "discount": {
  "amount": 10,
  "code": "WALLET10"
  }
  },
  "disbursements": [
  {
  "collector_id": "collectorId"
  }
  ],
  "payer": {
  "id": 8879
  },
  "site_id": "MLU",
  "binary_mode": true,
  "date_created": "2018-10-20T09:34:20.518-04:00",
  "date_last_updated": "2018-10-20T09:34:20.518-04:00"
}
```