/v1/payments
BASE URI https://api.mercadopago.com/v1/payments
HTTP Request
curl
curl -X POST \
'https://api.mercadopago.com/v1/payments' \
-H 'Authorization: Bearer ACCESS_TOKEN_ENV' \
-d '{
"token":"b3a7dbec3eb0d71798c4f19fec445795",
"installments":1,
"transaction_amount":58.80,
"description":"Point Mini a maquininha que dá o dinheiro de suas vendas na hora",
"payment_method_id":"visa",
"payer":{
"email":"test_user_123456@testuser.com",
"identification": {
"number": "19119119100",
"type": "CPF"
}
},
"notification_url":"https://www.suaurl.com/notificacoes/",
"sponsor_id":null,
"binary_mode":false,
"external_reference":"MP0001",
"statement_descriptor":"MercadoPago",
"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_medium@2x.png",
"category_id": "electronics",
"quantity":1,
"unit_price":58.80
}
],
"payer":{
"first_name":"Nome",
"last_name":"Sobrenome",
"address":{
"zip_code":"06233-200",
"street_name":"Av das Nacoes Unidas",
"street_number":3003
},
"registration_date":"2019-01-01T12:01:01.000-03:00",
"phone":{
"area_code":"011",
"number":"987654321"
}
},
"shipments":{
"receiver_address":{
"street_name":"Av das Nacoes Unidas",
"street_number":3003,
"zip_code":"06233200",
"city_name": "Buzios",
"state_name": "Rio de Janeiro"
}
}
}
}'
Request Params
ParameterTypeDescription
payer
Object
Identifies the buyer.
entity_type
String
Entity type of the payer (only for bank transfers).
individual
Payer is individual.
association
Payer is an association.
type
String
Identification type of the associated payer (mandatory if the Payer is a Customer).
customer
Payer is a Customer and belongs to the collector.
registered
The account corresponds to a Mercado Pago registered user.
guest
The payer doesn't have an account.
id
String
Identification of the associated payer.
email
String
Email. (Required)
identification
Object
Personal identification.
type
String
Identification type.
number
String
Identification number.
phone
Object
Phone of the associated payer.
area_code
String
Phone area code.
number
String
Phone number.
extension
String
Phone number's extension.
first_name
String
First name of the associated payer.
last_name
String
Last name of the associated payer.
binary_mode
Boolean
When set to true, the payment can only be approved or rejected. Otherwise in_process status is added.
order
Object
Order identifier.
type
String
Type of order.
mercadolibre
The order is from Mercado Libre.
mercadopago
It is a Mercado Pago merchant_order.
id
Long
Id of the associated purchase order.
external_reference
String
ID given by the merchant in their system.
description
String
Payment reason or item title.
metadata
Object
Valid JSON that can be attached to the payment to record additional attributes of the merchant.
transaction_amount
Float
Product cost. (Required)
coupon_amount
Float
Amount of the coupon discount.
date_of_expiration
Date(ISO_8601)
Payment’s expiration date.
campaign_id
Integer
Discount campaign ID.
coupon_code
String
Discount campaign with a specific code.
differential_pricing_id
Integer
Id of the scheme for the absorption of financing fee.
application_fee
Float
Fee collected by a marketplace or Mercado Pago Application.
capture
Boolean
Determines if the payment should be captured (true, default value) or just reserved (false).
payment_method_id
String
Payment method chosen to do the payment. (Required)
issuer_id
String
Payment method issuer.
token
String
Card token ID. (Required for credit card)
statement_descriptor
String
How will look the payment in the card bill (e.g.: MERCADOPAGO).
installments
Integer
Selected quantity of installments. (Required)
notification_url
String
URL where Mercado Pago will send notifications associated to changes in this payment
callback_url
String
URL where mercadopago does the final redirect (only for bank transfers).
additional_info
Object
Data that could improve fraud analysis and conversion rates. Try to send as much information as possible.
ip_address
String
IP from where the request comes from (only for bank transfers).
items
Array(Object)
List of items to be paid.
id
String
Item code.
title
String
Item name.
description
String
Long item description.
picture_url
String
Image URL.
category_id
String
Category of the item.
quantity
Integer
Item's quantity.
unit_price
Float
Unit price.
payer
Object
Buyer's information.
first_name
String
Buyer's name.
last_name
String
Buyer's last name.
phone
Object
Buyer's phone.
area_code
String
Area code.
number
String
Phone number.
address
Object
Address.
zip_code
String
Zip code.
street_name
String
Street name.
street_number
Integer
Number.
registration_date
Date
Date of registration of the buyer on your site.
shipments
Object
Shipping information.
receiver_address
Object
Buyer's address.
zip_code
String
Zip code.
state_name
String
State.
city_name
String
City Name.
street_name
String
Street name.
street_number
Integer
Number
floor
String
Floor.
apartment
String
Department.
barcode
Object
Barcode information.
type
String
Encoding type.
UCC/EAN 128
Encodes data using the Code 128 symbology.
Code128C
High-density alphanumeric code.
Code39
Media density code.
content
String
Barcode generated.
width
Integer
Width of barcode.
height
Integer
Height of barcode.
HTTP Response
json
{
"id": 20359978,
"date_created": "2019-07-10T10:47:58.000-04:00",
"date_approved": "2019-07-10T10:47:58.000-04:00",
"date_last_updated": "2019-07-10T10:47:58.000-04:00",
"date_of_expiration": null,
"money_release_date": "2019-07-24T10:47:58.000-04:00",
"operation_type": "regular_payment",
"issuer_id": "25",
"payment_method_id": "visa",
"payment_type_id": "credit_card",
"status": "approved",
"status_detail": "accredited",
"currency_id": "[FAKER][CURRENCY][ACRONYM]",
"description": "Point Mini a maquininha que dá o dinheiro de suas vendas na hora",
"live_mode": false,
"sponsor_id": null,
"authorization_code": null,
"money_release_schema": null,
"taxes_amount": 0,
"counter_currency": null,
"shipping_amount": 0,
"pos_id": null,
"store_id": null,
"collector_id": 448876418,
"payer": {
"first_name": "Test",
"last_name": "Test",
"email": "test_user_80507629@testuser.com",
"identification": {
"number": "19119119100",
"type": "CPF"
}
"phone": {
"area_code": "011",
"number": "987654321",
"extension": ""
},
"type": "guest",
"entity_type": null,
"id": null
},
"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_medium@2x.png",
"category_id": "electronics",
"quantity":1,
"unit_price":58.80
}
],
"payer": {
"phone": {
"area_code": "11",
"number": "987654321"
},
"address": {
"zip_code": "06233-200",
"street_name": "Av das Nacoes Unidas",
"street_number": "3003"
},
"first_name": "Nome",
"last_name": "Sobrenome",
"registration_date": "2019-01-01T12:01:01.000-03:00"
},
"shipments": {
"receiver_address":{
"street_name":"Av das Nacoes Unidas",
"street_number":3003,
"zip_code":"06233200",
"city_name": "Buzios",
"state_name": "Rio de Janeiro"
}
}
},
"order": {},
"external_reference": "MP0001",
"transaction_amount": 58.8,
"transaction_amount_refunded": 0,
"coupon_amount": 0,
"differential_pricing_id": null,
"deduction_schema": null,
"transaction_details": {
"payment_method_reference_id": null,
"net_received_amount": 56.16,
"total_paid_amount": 58.8,
"overpaid_amount": 0,
"external_resource_url": null,
"installment_amount": 58.8,
"financial_institution": null,
"payable_deferral_period": null,
"acquirer_reference": null
},
"fee_details": [
{
"type": "mercadopago_fee",
"amount": 2.64,
"fee_payer": "collector"
}
],
"captured": true,
"binary_mode": false,
"call_for_authorize_id": null,
"statement_descriptor":"MercadoPago",
"installments": 1,
"card": {
"id": null,
"first_six_digits": "423564",
"last_four_digits": "5682",
"expiration_month": 6,
"expiration_year": 2023,
"date_created": "2019-07-10T10:47:58.000-04:00",
"date_last_updated": "2019-07-10T10:47:58.000-04:00",
"cardholder": {
"name": "APRO",
"identification": {
"number": "19119119100",
"type": "CPF"
}
}
},
"notification_url": "https://www.suaurl.com/notificacoes/",
"refunds": [],
"processing_mode": "aggregator",
"merchant_account_id": null,
"acquirer": null,
"merchant_number": null,
"acquirer_reconciliation": []
}
Error Codes
CodeDescription
404 NOT_FOUND
2000
Payment not found
403 FORBIDDEN
4
The caller is not authorized to access this resource.
3002
The caller is not authorized to perform this action.
400 BAD_REQUEST
1
Params Error.
3
Token must be for test.
5
Must provide your access_token to proceed.
23
The following parameters must be valid date and format (yyyy-MM-dd'T'HH:mm:ssz) date_of_expiration.
1000
Number of rows exceeded the limits.
1001
Date format must be yyyy-MM-dd'T'HH:mm:ss.SSSZ.
2001
Already posted the same request in the last minute.
2004
POST to Gateway Transactions API fail.
2002
Customer not found.
2006
Card Token not found.
2007
Connection to Card Token API fail.
2009
Card token issuer can't be null.
2060
The customer can't be equal to the collector.
3000
You must provide your cardholder_name with your card data.
3001
You must provide your cardissuer_id with your card data.
3003
Invalid card_token_id.
3004
Invalid parameter site_id.
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.
3006
Invalid parameter cardtoken_id.
3007
The parameter client_id can not be null or empty.
3008
Not found Cardtoken.
3009
unauthorized client_id.
3010
Not found card on whitelist.
3011
Not found payment_method.
3012
Invalid parameter security_code_length.
3013
The parameter security_code is a required field can not be null or empty.
3014
Invalid parameter payment_method.
3015
Invalid parameter card_number_length.
3016
Invalid parameter card_number.
3017
The parameter card_number_id can not be null or empty.
3018
The parameter expiration_month can not be null or empty.
3019
The parameter expiration_year can not be null or empty.
3020
The parameter cardholder.name can not be null or empty.
3021
The parameter cardholder.document.number can not be null or empty.
3022
The parameter cardholder.document.type can not be null or empty.
3023
The parameter cardholder.document.subtype can not be null or empty.
3024
Not valid action - partial refund unsupported for this transaction.
3025
Invalid Auth Code.
3026
Invalid card_id for this payment_method_id.
3027
Invalid payment_type_id.
3028
Invalid payment_method_id.
3029
Invalid card expiration month.
3030
Invalid card expiration year.
4000
card atributte can't be null.
4001
payment_method_id atributte can't be null.
4002
transaction_amount atributte can't be null.
4003
transaction_amount atributte must be numeric.
4004
installments atributte can't be null.
4005
installments atributte must be numeric.
4006
payer atributte is malformed.
4007
site_id atributte can't be null.
4012
payer.id atributte can't be null.
4013
payer.type atributte can't be null.
4015
payment_method_reference_id atributte can't be null.
4016
payment_method_reference_id atributte must be numeric.
4017
status atributte can't be null.
4018
payment_id atributte can't be null.
4019
payment_id atributte must be numeric.
4020
notificaction_url atributte must be url valid.
4021
notificaction_url atributte must be shorter than 500 characters.
4022
metadata atributte must be a valid JSON.
4023
transaction_amount atributte can't be null.
4024
transaction_amount atributte must be numeric.
4025
refund_id can't be null.
4026
Invalid coupon_amount.
4027
campaign_id atributte must be numeric.
4028
coupon_amount atributte must be numeric.
4029
Invalid payer type.
4037
Invalid transaction_amount.
4038
application_fee cannot be bigger than transaction_amount.
4039
application_fee cannot be a negative value.
4050
payer.email must be a valid email.
4051
payer.email must be shorter than 254 characters.
7523
Invalid expiration date.