/checkout/preferences
BASE URI https://api.mercadopago.com/checkout/preferences
HTTP Request
curl
curl -X POST \
'https://api.mercadopago.com/checkout/preferences?access_token=ACCESS_TOKEN_ENV' \
-H 'content-type:application/json' \
-d '{
"items": [
{
"title": "Dummy Item",
"description": "Multicolor Item",
"quantity": 1,
"currency_id": "[FAKER][CURRENCY][ACRONYM]",
"unit_price": 10.0
}
]
}'
Request Params
ParameterTypeDescription
items
Array(Object)
Items information.
id
String(256)
Item ID.
title
String(256)
Item title. It will be displayed in the payment process.
description
String(256)
Item description.
picture_url
String(600)
Item image URL.
category_id
String(256)
Item category ID.
quantity
Integer
Item quantity.
currency_id
String(3)
Currency ID. ISO_4217 code.
unit_price
Float
Unit price.
payer
Object
Buyer Information.
name
String(256)
Buyer name.
surname
String(256)
Buyer last name.
email
String(256)
Buyer e-mail address.
phone
Object
Buyer phone.
area_code
String(256)
Area code.
number
String(256)
Number.
identification
Object
Personal identification.
type
String(256)
Identification Type.
number
String(256)
Number.
address
Object
Buyer address.
zip_code
String(256)
Zip code.
street_name
String(256)
Street name.
street_number
Integer
Street number.
date_created
Date(ISO_8601)
Registration date.
payment_methods
Object
Set up payment methods to be excluded from the payment process.
excluded_payment_methods
Array(Object)
Payment methods not allowed in payment process (except account_money).
id
String(256)
Payment method ID.
excluded_payment_types
Array(Object)
Payment types not allowed in payment process.
id
String(256)
Payment method data_type ID.
default_payment_method_id
String(256)
Payment method to be preferred on the payments methods list.
installments
Integer
Maximum number of credit card installments to be accepted.
default_installments
Integer
Prefered number of credit card installments.
shipments
Object
Shipments information.
mode
String
Shipment mode.
custom
Custom shipping.
me2
Mercado Envíos.
not_specified
Shipping mode not specified.
local_pickup
Boolean
The payer have the option to pick up the shipment in your store (mode:me2 only).
dimensions
String
Dimensions of the shipment in cm x cm x cm, gr (mode:me2 only)
default_shipping_method
Integer
Select default shipping method in checkout (mode:me2 only).
free_methods
Array(Object)
Offer a shipping method as free shipping (mode:me2 only).
id
Integer
Shipping method ID.
cost
Float
Shipment cost (mode:custom only).
free_shipping
Boolean
Free shipping for mode:custom.
receiver_address
Object
Shipping address.
zip_code
String(256)
Zip code.
street_name
String(256)
Street name.
street_number
Integer
Street number.
floor
String(256)
Floor.
apartment
String(256)
Apartment.
back_urls
Object
URLs to return to the sellers website.
success
String(600)
Approved payment URL.
pending
String(600)
Pending payment URL.
failure
String(600)
Canceled payment URL.
notification_url
String(500)
URL where you'd like to receive a payment notification.
additional_info
String(600)
Additional information.
auto_return
String
If specified, your buyers will be redirected back to your site immediately after completing the purchase.
approved
The redirection takes place only for approved payments.
all
The redirection takes place only for approved payments, forward compatibility only if we change the default behavior
external_reference
String(256)
Reference you can synchronize with your payment system.
expires
Boolean
Boolean value that determines if a preference expire.
expiration_date_from
Date(ISO_8601)
Date since the preference will be active.
expiration_date_to
Date(ISO_8601)
Date when the preference will be expired.
marketplace
String(256)
Origin of the payment. Default value: NONE
marketplace_fee
Float
Marketplace's fee charged by application owner. Default value: 0 in local currency
differential_pricing
Object
Differential pricing configuration for this preference.
id
Integer
Differential pricing ID.
tracks
Array (Object)
Tracks to be executed during the users's interaction in the Checkout flow.
type
String
Track type. Specifies which tool the values belong to.
google_ad
Allows configurations for GTM's Google Ads Conversion Tracking tag. Necessary values: conversion_id and conversion_label.
facebook_ad
Allows configurations for Facebook Pixel. Necessary values: pixel_id.
values
Map
Configuration values according the track type.
HTTP Response
json
{
"collector_id": 202809963,
"operation_type": "regular_payment",
"items": [
{
"id": "",
"picture_url": "",
"title": "Dummy Item",
"description": "Multicolor Item",
"category_id": "",
"currency_id": "[FAKER][CURRENCY][ACRONYM]",
"quantity": 1,
"unit_price": 10
}
],
"payer": {
"name": "",
"surname": "",
"email": "",
"date_created": "",
"phone": {
"area_code": "",
"number": ""
},
"identification": {
"type": "",
"number": ""
},
"address": {
"street_name": "",
"street_number": null,
"zip_code": ""
}
},
"back_urls": {
"success": "",
"pending": "",
"failure": ""
},
"auto_return": "",
"payment_methods": {
"excluded_payment_methods": [
{
"id": ""
}
],
"excluded_payment_types": [
{
"id": ""
}
],
"installments": null,
"default_payment_method_id": null,
"default_installments": null
},
"client_id": "6295877106812064",
"marketplace": "MP-MKT-6295877106812064",
"marketplace_fee": 0,
"shipments": {
"receiver_address": {
"zip_code": "",
"street_number": null,
"street_name": "",
"floor": "",
"apartment": ""
}
},
"notification_url": null,
"external_reference": "",
"additional_info": "",
"expires": false,
"expiration_date_from": null,
"expiration_date_to": null,
"date_created": "2018-02-02T15:22:23.535-04:00",
"id": "202809963-920c288b-4ebb-40be-966f-700250fa5370",
"init_point": "https://www.mercadopago.com/mla/checkout/start?pref_id=202809963-920c288b-4ebb-40be-966f-700250fa5370",
"sandbox_init_point": "https://sandbox.mercadopago.com/mla/checkout/pay?pref_id=202809963-920c288b-4ebb-40be-966f-700250fa5370"
} Error Codes
CodeDescription
400 bad_request
invalid_collector_id
collector_id must be a number.
invalid_collector_id
collector_id invalid.
invalid_sponsor_id
sponsor_id not found.
invalid_sponsor_id
sponsor_id must be a number
invalid_sponsor_id
sponsor_id should be different than collector_id.
invalid_sponsor_id
sponsor_id site must be the same as collector_id.
invalid_sponsor_id
sponsor_id didn't accept MercadoPago's Terms and Conditions.
invalid_sponsor_id
sponsor_id is not an active user.
invalid_collector_email
collector is not collector_email(secure) owner
invalid_collector_email
collector is not collector_email owner
invalid_operation_type
operation_type invalid.
invalid_expiration_date_to
expiration_date_to invalid.
invalid_expiration_date_from
expiration_date_from invalid.
invalid_items
amount cannot be paid with Mercado Pago.
invalid_items
items needed.
invalid_items
items invalid. Wrong format
invalid_items
currency_id needed.
invalid_items
currency_id invalid.
invalid_items
quantity needed.
invalid_items
quantity must be a number.
invalid_items
unit_price needed.
invalid_items
unit_price must be a number.
invalid_items
unit_price invalid.
invalid_payer
payer invalid. Wrong format
invalid_payer
payer name invalid. Max length 100.
invalid_payer
payer surname invalid. Max length 100.
invalid_payer
payer email invalid. Max length 150.
invalid_back_urls
back_urls invalid. Wrong format
invalid_payment_methods
payment_methods invalid. Wrong format
invalid_payment_methods
the combination of payment methods and payment types cannot exclude all payment methods.
invalid_payment_methods
amount cannot be paid with MercadoPago.
invalid_payment_methods
excluded_payment_methods invalid. Wrong format.
invalid_payment_methods
id needed.
invalid_payment_methods
account_money cannot be excluded.
invalid_payment_methods
cannot exclude all payments methods.
invalid_payment_methods
excluded_payment_types invalid. Wrong format.
invalid_payment_methods
cannot exclude all payments types.
invalid_payment_methods
client_id invalid.
invalid_payment_methods
client_id must be a number.
invalid_installments
installments invalid. Should be only 1, 3, 6, 9, 12, 15, 18, 21 or 24.
invalid_installments
installments must be a number.
invalid_marketplace_fee
marketplace_fee must be a number.
invalid_marketplace_fee
marketplace_fee must be a positive number.
invalid_marketplace_fee
marketplace_fee must not be greater than total amount.
invalid_id
preference_id not found.
invalid_access_token
access denied
invalid_shipments
invalid shipment mode
invalid_shipments
collector doesn't have me2 active.
invalid_shipments
shipments.dimensions invalid
invalid_shipments
shipments.free_methods invalid
invalid_shipments
shipments.free_methods ID must be a number
invalid_shipments
invalid free_methods
invalid_shipments
shipments.local_pickup invalid
invalid_shipments
shipments.default_shipping_method must be a number
invalid_shipments
invalid shipments.default_shipping_method
invalid_shipments
shipments.free_shipping invalid
invalid_shipments
shipments.cost must be a number
invalid_shipments
shipments.cost invalid
invalid_shipments
Invalid dimensions format
invalid_shipments
Invalid dimension values
invalid_shipments
Invalid total amount, with me2 it cannot be lesser than .
invalid_binary_mode
binary_mode must be boolean.