AI resources
Create preferencehttps://api.mercadopago.com/checkout/preferences
Generate a preference with the information of a product or service and obtain the necessary URL to start the payment flow.
POST
Request parameters
Header
Authorization
string
REQUIRED
Access Token obtained through the developer panel. Must be sent in all requests.
Body
items
array
REQUIRED
Items information.
payer
object
Payer's information, such as name, last name, e-mail, phone, personal identification, address, and registration date.
payment_methods
object
All configuration related to payments methods, such as excluded payment methods, excluded payment types, default payment method, and installments.
shipments
object
Shipments information.
Response parameters
collector_id
number
Unique ID used to identify the collector. It is the same as the Cust ID.
operation_type
String
Operation data_type.
regular_payment: Normal payment.
money_transfer: Money request.
items
array
Items information.
payer
object
Payer's information, such as name, last name, e-mail, phone, personal identification, address, and registration date.
Errors
400Error
collector_does_not_comply_with_current_regulation
The seller's account ("collector_id") has pending identity validation and regulatory compliance requirements for this site. Resolve them before creating a new preference.
invalid_collector_id
collector_id invalid.
invalid_sponsor_id
sponsor_id is not an active user.
invalid_collector_email
collector is not collector_email owner.
invalid_operation_type
operation_type invalid.
invalid_expiration_date_to
expiration_date_to invalid.
invalid_date
invalid date of expiration.
invalid_expiration_date_from
expiration_date_from invalid.
invalid_items
unit_price invalid.
invalid_back_urls
back_urls invalid. Wrong format.
invalid_payment_methods
installments invalid. Should be a number between 1 and 36.
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 type (<type>) for field shipments.cost.
invalid_binary_mode
binary_mode must be boolean.
sponsor_id site must be the same as collector_id
The sponsor_id site must be the same as the collector_id site.
Request
curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'curl -X POST \
'https://api.mercadopago.com/checkout/preferences'\
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer APP_USR-4*********782856-12*********f202ca494*********f0baa4bb3*********648' \
-d '{
"items": [
{
"id": "Sound system",
"title": "Dummy Title",
"description": "Dummy description",
"picture_url": "https://www.myapp.com/myimage.jpg",
"category_id": "car_electronics",
"quantity": 1,
"currency_id": "COP",
"unit_price": 24.5
}
],
"payer": {
"name": "Sofia",
"surname": "Rodríguez",
"email": "test@testuser.com",
"phone": {
"area_code": "1",
"number": 300
},
"identification": {
"type": "NIT",
"number": "123456789-0"
},
"address": {
"zip_code": "110221",
"street_name": "Example Street",
"street_number": 93
},
"date_created": "2024-04-01T00:00:00Z"
},
"payment_methods": {
"excluded_payment_methods": [
{
"id": "master"
}
],
"excluded_payment_types": [
{
"id": "ticket"
}
],
"default_payment_method_id": "master",
"installments": 10,
"default_installments": 5
},
"shipments": {
"local_pickup": false,
"dimensions": "32 x 25 x 16",
"cost": 20,
"free_shipping": false,
"receiver_address": {
"zip_code": "110221",
"street_name": "Street address test",
"city_name": "Bogotá",
"state_name": "Bogotá D.C.",
"street_number": 93,
"country_name": "Colombia"
}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"notification_url": "https://notificationurl.com",
"additional_info": "Discount 12.00",
"auto_return": "approved",
"external_reference": "1643827245",
"expires": false,
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"marketplace": "NONE",
"marketplace_fee": 0,
"differential_pricing": {
"id": 1
},
"tracks": [
{
"type": "google_ad",
"values": {
"conversion_id": 123,
"conversion_label": "abc",
"pixel_id": "abc"
}
}
]
}'Response
{
"collector_id": 202809963,
"items": [
{
"title": "Dummy Item",
"description": "Multicolor Item",
"currency_id": "COP",
"quantity": 1,
"unit_price": "24.50"
}
],
"payer": {
"email": "test@testuser.com",
"phone": {},
"identification": {
"type": "NIT"
},
"address": {}
},
"back_urls": {
"success": "https://test.com/success",
"pending": "https://test.com/pending",
"failure": "https://test.com/failure"
},
"auto_return": "approved",
"payment_methods": {
"excluded_payment_methods": [
{}
],
"excluded_payment_types": [
{}
]
},
"client_id": "6295877106812064",
"marketplace": "MP-MKT-6295877106812064",
"marketplace_fee": 0,
"shipments": {
"receiver_address": {}
},
"notification_url": "https://notificationurl.com",
"statement_descriptor": "MERCADOPAGO",
"expiration_date_from": "2022-11-17T09:37:52.000-04:00",
"expiration_date_to": "2022-11-17T10:37:52.000-05:00",
"date_created": "2022-11-17T10:37:52.000-05: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",
"preference_expired": true,
"sandbox_init_point": "https://sandbox.mercadopago.com/mla/checkout/pay?pref_id=202809963-920c288b-4ebb-40be-966f-700250fa5370",
"metadata": {}
}