Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/scooller/Leben-site/llms.txt

Use this file to discover all available pages before exploring further.

iLeben integrates with Mercado Pago using the official mercadopago/dx-php v3.x SDK, covering the full range of LATAM payment methods including credit cards, debit cards, and local wallet options. The flow is preference-based: the SDK creates a payment preference and returns an init_point URL that redirects the buyer to Mercado Pago’s hosted page. Payment confirmation arrives asynchronously via a signed webhook, separate from the user’s browser return.

​
Configuration

Obtain credentials from the Mercado Pago Developer Panel under your application’s Credentials tab. Use Test credentials in non-production environments and Production credentials in live deployments. 
# From the MP Developer Panel → Credentials
MERCADOPAGO_PUBLIC_KEY=APP_USR-tu-public-key
MERCADOPAGO_ACCESS_TOKEN=APP_USR-tu-access-token

# Secret used to verify webhook signatures
MERCADOPAGO_WEBHOOK_SECRET=tu-webhook-secret
Test and production tokens are distinct and not interchangeable. Using a test ACCESS_TOKEN against the production API (or vice versa) will result in an Invalid access token error.

​
Payment Flow

1

Initiate checkout

The frontend calls POST /api/v1/checkout with gateway: "mercadopago" in the body. The API creates a Payment record with status pending and calls MercadoPagoService::createTransaction().
2

Receive preference data

The API responds with a redirect_url (the init_point) and a preference_id. Store both on the client for tracking.
3

Redirect the user

The frontend redirects the user to the init_point URL. Mercado Pago presents its hosted payment page with all locally available payment methods.
4

Webhook received

After the user completes or abandons the payment, Mercado Pago sends an HTTP POST to /payments/mercadopago/webhook. This is asynchronous and arrives independently of the browser redirect.
5

Signature verification

PaymentWebhookController@mercadopagoWebhook verifies the request signature using MERCADOPAGO_WEBHOOK_SECRET before processing the payload. Requests that fail signature verification are rejected with a 401.
6

Query payment status

The controller calls getTransactionStatus($payment_id) to retrieve the authoritative status from the Mercado Pago API.
7

Idempotent status update

The Payment record is updated only if the incoming status represents a valid state transition. Duplicate webhook deliveries for the same event are safely ignored.
8

User returns to result page

Mercado Pago redirects the buyer to GET /payments/mercadopago/return, handled by PaymentWebhookController@mercadopagoReturn, which reads the final payment status from the database and forwards the user to /payments/success/{payment} or /payments/failed/{payment}.

​
PHP Example

The following snippet shows how to create a Mercado Pago preference using the PaymentGateway facade: 
use App\Models\Payment;
use App\Enums\PaymentGateway;
use App\Enums\PaymentStatus;
use App\Facades\PaymentGateway as PaymentGatewayFacade;

// 1. Persist the payment record
$payment = Payment::create([
    'user_id'    => auth()->id(),
    'project_id' => $project->id,
    'plant_id'   => $plant->id,
    'gateway'    => PaymentGateway::MERCADOPAGO,
    'amount'     => 10000,
    'currency'   => 'CLP',
    'status'     => PaymentStatus::PENDING,
    'metadata'   => ['description' => 'Compra de plantas'],
]);

// 2. Create the preference — SDK returns preference_id + init_point
$transaction = PaymentGatewayFacade::driver('mercadopago')->createTransaction([
    'amount'             => $payment->amount,
    'description'        => $payment->metadata['description'],
    'external_reference' => (string) $payment->id,
    'payer_email'        => auth()->user()->email,
]);

// 3. Redirect the user to Mercado Pago
return redirect($transaction['init_point']);

// 4. MP sends an async webhook to:
// POST /payments/mercadopago/webhook → PaymentWebhookController@mercadopagoWebhook

// 5. MP redirects the buyer to:
// GET /payments/mercadopago/return → PaymentWebhookController@mercadopagoReturn

​
SDK Methods

MethodSignatureDescription
createTransactioncreateTransaction(array $data): arrayCreates a payment preference; returns init_point and preference_id
confirmTransactionconfirmTransaction(string $paymentId): arrayRetrieves a specific MP payment object by ID
getTransactionStatusgetTransactionStatus(string $paymentId): arrayQueries the current status of a payment from the MP API
refundTransactionrefundTransaction(string $paymentId, ?float $amount = null): arrayIssues a full or partial refund for a completed payment

​
Status Mapping

Mercado Pago statuses are mapped to iLeben’s PaymentStatus enum as follows:
Mercado Pago StatusiLeben PaymentStatus
approvedCOMPLETED
pendingPENDING
in_processPROCESSING
rejectedFAILED
cancelledCANCELLED
refundedREFUNDED

​
Webhook Setup

Register your webhook URL in the Mercado Pago Developer Panel.
SettingValue
URLhttps://your-domain.com/payments/mercadopago/webhook
Eventspayment
For local development, use a tunneling tool such as ngrok to expose your local server to the internet. Mercado Pago requires a publicly accessible URL to deliver webhooks.

​
Web Routes

MethodRouteHandlerDescription
POST/payments/mercadopago/webhookPaymentWebhookController@mercadopagoWebhookReceives async payment notifications from MP
GET/payments/mercadopago/returnPaymentWebhookController@mercadopagoReturnReceives the buyer redirect after payment

​
Error Reference

Error MessageCauseResolution
Invalid access tokenA test-mode token is being used against the production API, or a production token against the sandboxVerify that MERCADOPAGO_ACCESS_TOKEN in .env matches the intended environment (Test vs. Production) in the MP Developer Panel.
Webhook not receivedThe webhook URL is not publicly accessible (common in local development)Use ngrok or a similar tunneling tool to expose POST /payments/mercadopago/webhook publicly, then update the URL in the MP Developer Panel.

​
Log Sanitization

Mercado Pago service calls are logged to storage/logs/laravel.log. The mercadopago_payment metadata stored in the database contains only the minimum necessary fields — sensitive payment details and full API payloads are stripped before persistence. 
# Tail Mercado Pago log entries in real time
tail -f storage/logs/laravel.log | grep -i "MercadoPago"

Build docs developers (and LLMs) love

Get started for freeTalk to us