sdk-php
Mercado Pago SDK for PHP
This library provides developers with a simple set of bindings to help you integrate Mercado Pago API to a website and start receiving payments.
💡 Requirements
The SDK Supports PHP version 8.2 or higher.
💻 Installation
If you already use another version of MercadoPago PHP SDK, take a look at our migration guide from version 2 to version 3.
First time using Mercado Pago? Create your Mercado Pago account, if you don’t have one already.
-
Download Composer if not already installed.
-
Install PHP SDK for MercadoPago running in command line:
composer require "mercadopago/dx-php:3.0.8"
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.
- 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.
Useful links
Here you can check eg. data structures for each parameter used by the SDK for each class.
🌟 Getting Started with payment via your own website forms
Simple usage looks like:
<?php
// Step 1: Require the library from your Composer vendor folder
require_once 'vendor/autoload.php';
use MercadoPago\Client\Common\RequestOptions;
use MercadoPago\Client\Payment\PaymentClient;
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 PaymentClient();
try {
// Step 4: Create the request array
$request = [
"transaction_amount" => 100,
"token" => "YOUR_CARD_TOKEN",
"description" => "description",
"installments" => 1,
"payment_method_id" => "visa",
"payer" => [
"email" => "user@test.com",
]
];
// 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
$payment = $client->create($request, $request_options);
echo $payment->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\Payment\PaymentClient;
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.
Step 3: Initialize the API client
$client = new PaymentClient();
Step 4: Create the request array
$request = [
"transaction_amount" => 100,
"token" => "YOUR_CARD_TOKEN",
"description" => "description",
"installments" => 1,
"payment_method_id" => "visa",
"payer" => [
"email" => "user@test.com",
]
];
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
$payment = $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 pruchased
$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:
$client = new PreferenceClient();
$client->get("123456789");
📚 Documentation
See our documentation for more details.
- Mercado Pago reference API. Portuguese / English / Spanish
🤝 Contributing
All contributions are welcome, ranging from people wanting to triage issues, others wanting to write documentation, to people wanting to contribute code.
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.
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.
❤️ Support
If you require technical support, please contact our support team at our developers site: English / Portuguese / Spanish
🏻 License
MIT license. Copyright (c) 2023 - Mercado Pago / Mercado Libre
For more information, see the LICENSE file.