, (*1)
Mercado Pago SDK for PHP
, (*2)
This library provides developers with a simple set of bindings to help you integrate Mercado Pago API to a website and start receiving payments., (*3)
💡 Requirements
The SDK Supports PHP version 8.2 or higher., (*4)
💻 Installation
If you already use another version of MercadoPago PHP SDK, take a look at our migration guide from version 2 to version 3., (*5)
First time using Mercado Pago? Create your Mercado Pago account, if you don’t have one already., (*6)
-
Download Composer if not already installed., (*7)
-
Install PHP SDK for MercadoPago running in command line:, (*8)
composer require "mercadopago/dx-php:3.3.0"
You can also run composer require "mercadopago/dx-php:2.6.2" for PHP7.1 or composer require "mercadopago/dx-php:1.12.6" for PHP5.6., (*9)
- Copy the access_token in the credentials section of the page and replace YOUR_ACCESS_TOKEN with it.
That's it! Mercado Pago SDK has been successfully installed., (*10)
Useful links
Here you can check eg. data structures for each parameter used by the SDK for each class., (*11)
Simple usage looks like:, (*12)
<?php
// Step 1: Require the library from your Composer vendor folder
require_once 'vendor/autoload.php';
use MercadoPago\Client\Common\RequestOptions;
use MercadoPago\Client\Order\OrderClient;
use MercadoPago\Exceptions\MPApiException;
use MercadoPago\MercadoPagoConfig;
// Step 2: Set production or sandbox access token
MercadoPagoConfig::setAccessToken("<ACCESS_TOKEN>");
// Step 2.1 (optional - default is SERVER): Set your runtime enviroment from MercadoPagoConfig::RUNTIME_ENVIROMENTS
// In case you want to test in your local machine first, set runtime enviroment to LOCAL
MercadoPagoConfig::setRuntimeEnviroment(MercadoPagoConfig::LOCAL);
// Step 3: Initialize the API client
$client = new OrderClient();
try {
// Step 4: Create the request array
$request = [
"type" => "online",
"processing_mode" => "automatic",
"total_amount" => "1000.00",
"external_reference" => "ext_ref_1234",
"capture_mode" => "automatic_async",
"payer" => [
"email" => "<PAYER_EMAIL>",
]
"transactions" => [
"payments" => [
[
"amount" => "1000.00",
"payment_method" => [
"id" => "master",
"type" => "credit_card",
"token" => "<CARD_TOKEN>",
"installments" => 1,
"statement_descriptor" => "Store name",
]
]
]
],
];
// Step 5: Create the request options, setting X-Idempotency-Key
$request_options = new RequestOptions();
$request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);
// Step 6: Make the request
$order = $client->create($request, $request_options);
echo "Order ID:" . $order->id;
// Step 7: Handle exceptions
} catch (MPApiException $e) {
echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
echo "Content: ";
var_dump($e->getApiResponse()->getContent());
echo "\n";
} catch (\Exception $e) {
echo $e->getMessage();
}
Step 1: Require the library from your Composer vendor folder
require_once 'vendor/autoload.php';
use MercadoPago\Client\Common\RequestOptions;
use MercadoPago\Client\Order\OrderClient;
use MercadoPago\Exceptions\MPApiException;
use MercadoPago\MercadoPagoConfig;
Step 2: Set production or sandbox access token
MercadoPagoConfig::setAccessToken("<ACCESS_TOKEN>");
You can also set another properties as quantity of retries, tracking headers, timeouts and a custom http client., (*13)
Step 3: Initialize the API client
$client = new OrderClient();
Step 4: Create the request array
$request = [
"type" => "online",
"processing_mode" => "automatic",
"total_amount" => "1000.00",
"external_reference" => "ext_ref_1234",
"capture_mode" => "automatic_async",
"payer" => [
"email" => "<PAYER_EMAIL>",
]
"transactions" => [
"payments" => [
[
"amount" => "1000.00",
"payment_method" => [
"id" => "master",
"type" => "credit_card",
"token" => "<CARD_TOKEN>",
"installments" => 1,
"statement_descriptor" => "Store name",
]
]
]
]
],
Step 5: Create the request options, setting X-Idempotency-Key
$request_options = new RequestOptions();
$request_options->setCustomHeaders(["X-Idempotency-Key: <SOME_UNIQUE_VALUE>"]);
Step 6: Make the request
$order = $client->create($request, $request_options);
Step 7: Handle exceptions
try{
// Do your stuff here
} catch (MPApiException $e) {
// Handle API exceptions
echo "Status code: " . $e->getApiResponse()->getStatusCode() . "\n";
echo "Content: ";
var_dump($e->getApiResponse()->getContent());
echo "\n";
} catch (\Exception $e) {
// Handle all other exceptions
echo $e->getMessage();
}
🌟 Getting started with payment via Checkout Pro
Step 1: Require the libraries
use MercadoPago\MercadoPagoConfig;
use MercadoPago\Client\Preference\PreferenceClient;
use MercadoPago\Exceptions\MPApiException;
Step 2: Create an authentication function
protected function authenticate()
{
// Getting the access token from .env file (create your own function)
$mpAccessToken = getVariableFromEnv('mercado_pago_access_token');
// Set the token the SDK's config
MercadoPagoConfig::setAccessToken($mpAccessToken);
// (Optional) Set the runtime enviroment to LOCAL if you want to test on localhost
// Default value is set to SERVER
MercadoPagoConfig::setRuntimeEnviroment(MercadoPagoConfig::LOCAL);
}
Step 3: Create customer's preference before proceeding to Checkout Pro page
// Function that will return a request object to be sent to Mercado Pago API
function createPreferenceRequest($items, $payer): array
{
$paymentMethods = [
"excluded_payment_methods" => [],
"installments" => 12,
"default_installments" => 1
];
$backUrls = array(
'success' => route('mercadopago.success'),
'failure' => route('mercadopago.failed')
);
$request = [
"items" => $items,
"payer" => $payer,
"payment_methods" => $paymentMethods,
"back_urls" => $backUrls,
"statement_descriptor" => "NAME_DISPLAYED_IN_USER_BILLING",
"external_reference" => "1234567890",
"expires" => false,
"auto_return" => 'approved',
];
return $request;
}
Step 4: Create the preference on Mercado Pago (DOCS)
public function createPaymentPreference(): ?Preference
{
// Fill the data about the product(s) being purchased
$product1 = array(
"id" => "1234567890",
"title" => "Product 1 Title",
"description" => "Product 1 Description",
"currency_id" => "BRL",
"quantity" => 12,
"unit_price" => 9.90
);
$product2 = array(
"id" => "9012345678",
"title" => "Product 2 Title",
"description" => "Product 2 Description",
"currency_id" => "BRL",
"quantity" => 5,
"unit_price" => 19.90
);
// Mount the array of products that will integrate the purchase amount
$items = array($product1, $product2);
// Retrieve information about the user (use your own function)
$user = getSessionUser();
$payer = array(
"name" => $user->name,
"surname" => $user->surname,
"email" => $user->email,
);
// Create the request object to be sent to the API when the preference is created
$request = createPreferenceRequest($item, $payer);
// Instantiate a new Preference Client
$client = new PreferenceClient();
try {
// Send the request that will create the new preference for user's checkout flow
$preference = $client->create($request);
// Useful props you could use from this object is 'init_point' (URL to Checkout Pro) or the 'id'
return $preference;
} catch (MPApiException $error) {
// Here you might return whatever your app needs.
// We are returning null here as an example.
return null;
}
}
In case you need to retrieve the preference by ID:, (*14)
$client = new PreferenceClient();
$client->get("123456789");
📚 Documentation
See our documentation for more details., (*15)
🤝 Contributing
All contributions are welcome, ranging from people wanting to triage issues, others wanting to write documentation, to people wanting to contribute code., (*16)
Please read and follow our contribution guidelines. Contributions not following these guidelines will
be disregarded. The guidelines are in place to make all of our lives easier and make contribution a consistent process for everyone., (*17)
Patches to version 2.x.x
Since the release of version 3.0.0, version 2 is deprecated and will not be receiving new features, only bug fixes. If you need to submit PRs for that version, please do so by using master-v2 as your base branch., (*18)
❤️ Support
If you require technical support, please contact our support team at our developers site: English / Portuguese / Spanish, (*19)
🏻 License
MIT license. Copyright (c) 2023 - Mercado Pago / Mercado Libre
For more information, see the LICENSE file.
Wallogit.com
