Design considerations of the MercadoPago API
Here we show you the most important characteristics of our API's architecture.
Table of contents
REST architecture
We use a REST architecture, based 100% in HTTP standards.
- Stateless: The API does not handle states, all needed information is sent by the client.
- URLs: Every resource has it's own and unique URL, following a logical hierarchy. For example:
- A single collection URL:
https://api.mercadopago.com/v1/payments/:id
- A single user URL:
https://api.mercadopago.com/users/:id
- HTTP methods: All operations are made using the right HTTP method for every case. For example:
GET
: To get resources dataPOST
: To create a new resourcePUT
: To modify a resourceDELETE
: To remove a resource
API's base URL
The API's base URL, from which you can access all resources, is the following one:
https://api.mercadopago.com/
JSON formatted data
The data is sent and received in JSON (JavaScript Object Notation) format, that is a text-based format, simple and easy to use from different platforms. Example:
{
"id": 1,
"attribute": "value",
"object": {
"inner_id": 2,
"inner_attribute": "inner_value"
},
"list": [
"item 1",
"item 2"
]
}
Attributes filtering
You can filter the attributes to only get the data you need. For example:
Without filter:
GET https://api.mercadopago.com/example
{
"id": 1234,
"name": {
"firstname": "John",
"lastname": "Doe"
},
"description": "This is an example",
"items": [
{
"id": 1,
"title": "Example item 1"
},
{
"id": 2,
"title": "Example item 2"
}
]
}
With filter:
GET https://api.mercadopago.com/example?attributes=id,name.firstname,items.title
{
"id": 1234,
"name": {
"firstname": "John"
},
"items": [
{
"title": "Example item 1"
},
{
"title": "Example item 2"
}
]
}
Cross Domain support (CORS)
Our API supports CORS (Cross-Origin Resource Sharing) to allow using it from any domain (origin) through the use of the header:
Access-Control-Allow-Origin: *
UTF-8 encoding
Each request and each response uses UTF-8 encoding.
Date and time in ISO-8601 format
All date/time fields use the ISO-8601 standard. Example:
2014-04-24T16:37:22.032-04:00
IP ranges used in communications from MercadoPago
Whenever information is sent from MercadoPago platform to your servers (for examlpe from IPN or Webhooks), this information will be sent from one of the IPs between the following ranges:
- 209.225.49.0 - 209.225.49.255
- 216.33.197.0 - 216.33.197.255
- 216.33.196.0 - 216.33.196.255
- 63.128.82.0 - 63.128.82.255
- 63.128.83.0 - 63.128.83.255
- 63.128.94.0 - 63.128.94.255
Thus, you can protect your site using a firewall that only allows incoming traffic from these IPs.