Create payment - Payments - Mercado Pago Developers
Create payment

POST

https://api.mercadopago.com/v1/payments
This endpoint allows you to create a payment and include all the necessary information. Make sure to add the payment details and the customer's information. In case of success, the request will return a response with status 201.
Products that use it:
Checkout Pro
Subscriptions
Checkout API
Checkout Bricks
Request's 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 en...View more
BODY
additional_info
object
At Payments level, it's only data, and we only forward that information to other APIs like Risk, to perform scoring and prevent fraud, or to Tax, to determine them for international payments.
application_fee
number
Commission (fee) that third parties (integrators) charge their customers, in this case, sellers, for using the marketplace platform and other services. This is a value in reais to be defined by the integrator to the sell...View more
binary_mode
boolean
When set to TRUE, payments can only be approved or rejected. Otherwise they can also result in_process.
callback_url
string
URL where mercadopago does the final redirect (only for bank transfers).
Response parameters
id
number
Unique Payment Identifier, automatically generated by Mercado Pago.
date_created
string
Payment creation date.
date_approved
string
Payment approval date. A payment can be generated in an intermediate state and then approved, so the creation date will not always coincide with the Approval Date.
date_last_updated
string
Date on which the last payment event was recorded.
Errors

400Error

1

Params Error. - If this error appears, please verify the parameters sent in the request.

3

Token must be for test. - If this error occurs, ensure you are using a test token.

8

The name of the following parameters is wrong [additional_info.payer.test] - This error is displayed when the name of a certain parameter is entered incorrectly. In this example, the `additional_info.payer` field. Review the parameter returned in the error and ensure that the information entered is correct.

23

The following parameters must be valid date and format (yyyy-MM-dd'T'HH:mm:ssz) date_of_expiration. - If this error arises, ensure the date_of_expiration is in the correct format.

1000

Number of rows exceeded the limits. - If you encounter this error, reduce the number of rows in your request.

2002

Customer not found. - Verify the customer details and try again if you encounter this error.

2004

POST to Gateway Transactions API fail. - If this error occurs, check the API endpoint and try again.

2006

Card Token not found. - If you see this error, ensure the card token is correct and valid.

2007

Connection to Card Token API fail. - Check your network connection and try again if this error appears.

2009

Card token issuer can't be null. - Ensure that the card token issuer is provided if this error occurs.

2034

Invalid users involved. - If this error appears, ensure that all involved users are either productive or test users. Additionally, verify that the sponsor_id (if applicable) is correct and try again.

2059

You cannot use `application_fee` with this payment. - This error occurs because the Access Token being used was not obtained via OAuth. Make sure to use an Access Token generated through OAuth.

2062

Invalid card token. - Ensure that the card token provided is valid and correct if this error occurs.

2067

Invalid user identification number. - Verify the user identification number and try again if you encounter this error.

2072

Invalid value for transaction_amount. - Ensure that the transaction_amount is valid if this error appears.

2077

Deferred capture not supported. - If this error occurs, note that deferred capture is not supported and adjust your request accordingly.

2123

Invalid operators users involved. - If you see this error, verify the operators involved in the transaction.

2131

Cannot infer Payment Method. - Verify that the `payment_method` field is correctly filled out and matches the payment method used, as well as the number of installments (`installments`).

2198

Invalid test user email. - This error occurs when the payer.email attribute is sent using a non-test email while you are in a testing environment (e.g., using an email @testuser.com). If you encounter this error, check that you are indeed in a testing environment and, if so, use an email as specified.

3000

You must provide your cardholder_name with your card data. - If this error occurs, include the cardholder_name in your request.

3001

You must provide your cardissuer_id with your card data. - If you encounter this error, ensure the cardissuer_id is included in your request.

3003

Invalid card_token_id. - Ensure that the card_token_id is correct and has not been previously used. Try again.

3004

Invalid parameter site_id. - If this error occurs, ensure the site_id is valid and correctly formatted.

3005

Not valid action, the resource is in a state that does not allow this operation. For more information see the state that has the resource. - If you see this error, check the state of the resource and adjust your request accordingly.

3006

Invalid parameter cardtoken_id. - Ensure the cardtoken_id is correct and try again if this error appears.

3007

The parameter client_id cannot be null or empty. - If this error occurs, provide a valid client_id.

3008

Not found Cardtoken. - Verify the cardtoken information and try again if this error appears.

3009

Unauthorized client_id. - If this error occurs, check the client_id permissions and try again.

3010

Not found card on whitelist. - Ensure the card is on the whitelist if this error appears.

3011

Not found payment_method. - Verify the payment_method information and try again if this error occurs.

3012

Invalid parameter security_code_length. - Ensure the security_code_length parameter is correct if this error appears.

3013

The parameter security_code is a required field and cannot be null or empty. - If this error occurs, provide the security_code parameter.

3014

Invalid parameter payment_method. - Ensure the payment_method parameter is correct if this error appears.

3015

Invalid parameter card_number_length. - If this error occurs, ensure the card_number_length parameter is correct.

3016

Invalid parameter card_number. - Verify the card_number parameter and try again if this error appears.

3017

The parameter card_number_id cannot be null or empty. - Ensure the card_number_id parameter is provided if this error occurs.

3018

The parameter expiration_month cannot be null or empty. - Provide the expiration_month parameter if this error occurs.

3019

The parameter expiration_year cannot be null or empty. - Ensure the expiration_year parameter is provided if this error appears.

3020

The parameter cardholder.name cannot be null or empty. - Provide the cardholder.name parameter if this error occurs.

3021

The parameter cardholder.document.number cannot be null or empty. - Ensure the cardholder.document.number parameter is provided if this error appears.

3022

The parameter cardholder.document.type cannot be null or empty. - Provide the cardholder.document.type parameter if this error occurs.

3023

The parameter cardholder.document.subtype cannot be null or empty. - Ensure the cardholder.document.subtype parameter is provided if this error appears.

3024

Not valid action - partial refund unsupported for this transaction. - If this error occurs, note that partial refunds are not supported for this transaction.

3025

Invalid Auth Code. - Verify the Auth Code and try again if this error appears.

3026

Invalid card_id for this payment_method_id. - Ensure the card_id matches the payment_method_id if this error occurs.

3027

Invalid payment_type_id. - If this error appears, verify the payment_type_id and try again.

3028

Invalid payment_method_id. - Verify the payment_method_id and try again if this error occurs.

3029

Invalid card expiration month. - Ensure the card expiration month is valid if this error appears.

3030

Invalid card expiration year. - If this error occurs, verify the card expiration year and try again.

3031

Secure_code_id can't be null. - Ensure the secure_code_id is provided if this error appears.

3032

Invalid security_code_length 3033 3034 - Invalid card_number_validation. - If this error occurs, verify the security_code_length and card_number_validation.

4000

Token attribute can't be null. - Ensure the token attribute is provided if this error appears.

4001

Payment_method_id attribute can't be null. - If this error occurs, provide the payment_method_id attribute.

4002

Transaction_amount attribute can't be null. - Ensure the transaction_amount attribute is provided if this error appears.

4003

Transaction_amount attribute must be numeric. - Verify the transaction_amount is numeric if this error occurs.

4004

Installments attribute can't be null. - If this error appears, ensure the installments attribute is provided.

4005

Installments attribute must be numeric. - Ensure the installments attribute is numeric if this error occurs.

4006

Payer attribute is malformed. - Verify the payer attribute is correctly formatted if this error appears.

4012

Payer.id attribute can't be null. - If this error appears, ensure the payer.id attribute is provided.

4013

Payer.type attribute can't be null. - Ensure the payer.type attribute is provided if this error occurs.

4015

Payment_method_reference_id attribute can't be null. - Provide the payment_method_reference_id attribute if this error appears.

4016

Payment_method_reference_id attribute must be numeric. - Ensure the payment_method_reference_id attribute is numeric if this error occurs.

4017

Status attribute can't be null. - If this error appears, ensure the status attribute is provided.

4018

Payment_id attribute can't be null. - Provide the payment_id attribute if this error occurs.

4019

Payment_id attribute must be numeric. - Ensure the payment_id attribute is numeric if this error appears.

4020

Notification_url attribute must be a valid URL. - If this error occurs, provide a valid URL for the `notification_url` attribute that starts with `https://`.

4021

Notification_url attribute must be shorter than 500 characters. - Ensure the notification_url attribute is within the character limit if this error appears.

4022

Metadata attribute must be a valid JSON. - If this error occurs, ensure the metadata attribute is a valid JSON.

4023

Transaction_amount attribute can't be null. - Provide the transaction_amount attribute if this error appears.

4024

Transaction_amount attribute must be numeric. - Ensure the transaction_amount attribute is numeric if this error occurs.

4025

Refund_id can't be null. - Provide the refund_id if this error appears.

4026

Invalid coupon_amount. - Verify the coupon_amount is correct if this error occurs.

4027

Campaign_id attribute must be numeric. - Ensure the campaign_id attribute is numeric if this error appears.

4028

Coupon_amount attribute must be numeric. - Verify the coupon_amount attribute is numeric if this error occurs.

4029

Invalid payer type. - Ensure the payer type is valid if this error appears.

4033

Invalid installments. - Verify the installments parameter is correct if this error occurs.

4037

Invalid transaction_amount. - Ensure the transaction_amount is valid if this error appears.

4038

Application_fee cannot be bigger than transaction_amount. - If this error occurs, ensure the application_fee is less than or equal to the transaction_amount.

4039

Application_fee cannot be a negative value. - Ensure the application_fee is a positive value if this error appears.

4050

Payer.email must be a valid email. - If this error occurs, ensure the payer.email is a valid email address.

4051

Payer.email must be shorter than 254 characters. - Ensure the payer.email is within the character limit if this error appears.

4292

Header X-Idempotency-Key can’t be null. - Provide a valid X-Idempotency-Key header if this error occurs.

6033

User unavailable. - If this error appears, check the user status and try again.

7523

Invalid expiration date. - Ensure the expiration date is valid if this error occurs.

401Error

Unauthorized use of live credentials

This error occurs when the access token does not have the required 'payment' scope. Verify that the credentials are correct and have the appropriate permissions.

403Error

4

The caller is not authorized to access this resource. - If this error occurs, verify your access permissions.

3002

The caller is not authorized to perform this action. - If you see this error, ensure you have the necessary permissions to perform this action.

pa_unauthorized_result_from_policies

blocked_by PolicyAgent - At least one policy returned unauthorized - This error occurs when at least one policy returns 'unauthorized'. This can happen if the `authorization` header is removed during the request or if the Access Token is not sent. Please verify the submission of this information and try making a new request.

Request
curl -X POST \
    'https://api.mercadopago.com/v1/payments'\
    -H 'Content-Type: application/json' \
       -H 'X-Idempotency-Key: 0d5020ed-1af6-469c-ae06-c3bec19954bb' \
       -H 'Authorization: Bearer TEST-4599*********755-11221*********d497ae962*********ecf8d85-1*********' \
    -d '{
  "additional_info": {
    "items": [
      {
        "id": "MLB2907679857",
        "title": "Point Mini",
        "description": "Point product for card payments via Bluetooth.",
        "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
        "category_id": "electronics",
        "quantity": 1,
        "unit_price": 58,
        "type": "electronics",
        "event_date": "2023-12-31T09:37:52.000-04:00",
        "warranty": false,
        "category_descriptor": {
          "passenger": {},
          "route": {}
        }
      }
    ],
    "payer": {
      "first_name": "Test",
      "last_name": "Test",
      "phone": {
        "area_code": 11,
        "number": "987654321"
      },
      "address": {
        "zip_code": "12312-123",
        "street_name": "Av das Nacoes Unidas",
        "street_number": 3003,
        "neighborhood": null,
        "city": 3003,
        "federal_unit": 3003
      }
    },
    "shipments": {
      "receiver_address": {
        "zip_code": "12312-123",
        "state_name": "Rio de Janeiro",
        "city_name": "Buzios",
        "street_name": "Av das Nacoes Unidas",
        "street_number": 3003
      },
      "width": null,
      "height": null
    }
  },
  "application_fee": null,
  "binary_mode": false,
  "campaign_id": null,
  "capture": false,
  "coupon_amount": null,
  "description": "Payment for product",
  "differential_pricing_id": null,
  "external_reference": "MP0001",
  "installments": 1,
  "metadata": {},
  "payer": {
    "entity_type": "individual",
    "type": "customer",
    "id": null,
    "email": "test_user_123@testuser.com",
    "identification": {
      "type": "CPF",
      "number": "95749019047"
    }
  },
  "payment_method_id": "master",
  "token": "ff8080814c11e237014c1ff593b57b4d",
  "transaction_amount": 58
}'
Sample answer
{
  "id": 20359978,
  "date_created": "2019-07-10T14:47:58.000Z",
  "date_approved": "2019-07-10T14:47:58.000Z",
  "date_last_updated": "2019-07-10T14:47:58.000Z",
  "money_release_date": "2019-07-24T14:47:58.000Z",
  "issuer_id": 25,
  "payment_method_id": "visa",
  "payment_type_id": "credit_card",
  "status": "approved",
  "status_detail": "accredited",
  "currency_id": "BRL",
  "description": "Point Mini a maquininha que dá o dinheiro de suas vendas na hora.",
  "taxes_amount": 0,
  "shipping_amount": 0,
  "collector_id": 448876418,
  "payer": {
    "id": 123,
    "email": "test_user_80507629@testuser.com",
    "identification": {
      "number": 19119119100,
      "type": "CPF"
    },
    "type": "customer"
  },
  "metadata": {},
  "additional_info": {
    "items": [
      {
        "id": "PR0001",
        "title": "Point Mini",
        "description": "Producto Point para cobros con tarjetas mediante bluetooth",
        "picture_url": "https://http2.mlstatic.com/resources/frontend/statics/growth-sellers-landings/device-mlb-point-i_medium2x.png",
        "category_id": "electronics",
        "quantity": 1,
        "unit_price": 58
      }
    ],
    "payer": {
      "registration_date": "2019-01-01T15:01:01.000Z"
    },
    "shipments": {
      "receiver_address": {
        "street_name": "Av das Nacoes Unidas",
        "street_number": "3003",
        "zip_code": "12312-123",
        "city_name": "Buzios",
        "state_name": "Rio de Janeiro"
      }
    }
  },
  "external_reference": "MP0001",
  "transaction_amount": 58,
  "transaction_amount_refunded": 50,
  "coupon_amount": 15,
  "transaction_details": {
    "net_received_amount": 56,
    "total_paid_amount": 58,
    "overpaid_amount": 0,
    "installment_amount": 58
  },
  "fee_details": [
    {
      "type": "coupon_fee",
      "amount": 2,
      "fee_payer": "payer"
    }
  ],
  "statement_descriptor": "MercadoPago",
  "installments": 1,
  "card": {
    "first_six_digits": 423564,
    "last_four_digits": 5682,
    "expiration_month": 6,
    "expiration_year": 2023,
    "date_created": "2019-07-10T14:47:58.000Z",
    "date_last_updated": "2019-07-10T14:47:58.000Z",
    "cardholder": {
      "name": "APRO",
      "identification": {
        "number": 19119119100,
        "type": "CPF"
      }
    }
  },
  "notification_url": "https://www.suaurl.com/notificacoes/",
  "processing_mode": "aggregator",
  "point_of_interaction": {
    "type": "PIX",
    "application_data": {
      "name": "NAME_SDK",
      "version": "VERSION_NUMBER"
    },
    "transaction_data": {
      "qr_code_base64": "iVBORw0KGgoAAAANSUhEUgAABRQAAAUUCAYAAACu5p7oAAAABGdBTUEAALGPC/xhBQAAAAFzUkdCAK7OHOkAAAAgY0hSTQAAeiYAAICEAAD6AAAAgOgAAHUwAADqYAAAOpgAABdwnLpRPAAAIABJREFUeJzs2luO3LiWQNFmI+Y/Zd6vRt36KGNXi7ZOBtcagHD4kNLeiLX33v8DAAAAABD879sDAAAAAAA/h6AIAAAAAGSCIgAAAACQCYoAAAAAQCYoAgAAAACZoAgAAAAAZIIiAAAAAJAJigAAAABAJigCAAAAAJmgCAAAAABkgiIAAAAAkAmKAAAAAEAmKAIAAAAAmaAIAAAAAGSCIgAAAACQCYoAAAAAQCYoAgAAAACZoAgAAAAAZIIiAAAAAJAJigAAAABAJigCA...",
      "qr_code": "00020126600014br.gov.bcb.pix0117test@testuser.com0217dados adicionais520400005303986540510.005802BR5913Maria Silva6008Brasilia62070503***6304E2CA",
      "ticket_url": "https://www.mercadopago.com.br/payments/123456789/ticket?caller_id=123456&hash=123e4567-e89b-12d3-a456-426655440000"
    }
  }
}

Navigation

Your integrationsDocumentationAPI referenceSDK library

Resources and Community

ChangelogMercado Pago statusError reportSupportNewsNewsletterPartners Program

Mercado Pago

Your accountTerms of usePrivacy policy

Country and language

Argentina
Argentina
Brasil
México
Uruguay
Colombia
Chile
Perú
English
Español
English
Português
Mercado Pago ofrece servicios de pago y no está autorizado por el Banco Central a operar como entidad financiera. Los fondos acreditados en cuentas de pago no constituyen depósitos en una entidad financiera ni están garantizados conforme legislación aplicable a depósitos en entidades financieras. Copyright © 2025 MercadoLibre S.R.L.

Usamos cookies para mejorar tu experiencia en Mercado Pago. Consultar más en nuestro Centro de Privacidad.

¡Listo! Guardamos tus preferencias.
Algo salió mal. Por favor, vuelve a intentarlo.