Overview The Payments API provides endpoints to create direct payments with tokenized cards, retrieve payment details, and process refunds. These endpoints interact directly with Mercado Pago’s payment processing system.
These endpoints are only available in local and testing environments when MERCADOPAGO_ENABLE_DEMO_ROUTES=true. They are automatically disabled in production.
Create Payment Creates a new payment with a tokenized card.
Endpoint POST /api/mercadopago/payments
Request Parameters Total payment amount. Minimum value: 0.01
Card token generated by Mercado Pago’s tokenization service
Number of installments. Minimum value: 1
Payment method identifier (e.g., “visa”, “master”, “amex”)
Payer information Payer email address. Must be a valid email format.
Payer identification document Show Identification properties
payer.identification.type
Document type (e.g., “DNI”, “CPF”)
payer.identification.number
Document number
Custom metadata object for additional information
Your internal reference ID for this payment
URL for webhook notifications. Must be a valid URL.
Request Example { "transaction_amount" : 100.5 , "token" : "CARD_TOKEN" , "description" : "Pago pedido 1001" , "installments" : 1 , "payment_method_id" : "visa" , "payer" : { "email" : "[email protected] " }, "external_reference" : "pedido-1001" , "notification_url" : "https://tu-app.test/api/mercadopago/webhooks" }
Response Indicates if the request was successful
The payment object returned by Mercado Pago Unique payment identifier
Payment status: approved, pending, rejected, cancelled, etc.
Detailed status information
Your internal reference ID
cURL Example curl --request POST \ --url http://localhost:8000/api/mercadopago/payments \ --header 'Content-Type: application/json' \ --data '{ "transaction_amount": 100.5, "token": "CARD_TOKEN", "description": "Pago pedido 1001", "installments": 1, "payment_method_id": "visa", "payer": { "email": "[email protected] " } }'
Get Payment Retrieves details of a specific payment.
Endpoint GET /api/mercadopago/payments/{paymentId}
Path Parameters The unique identifier of the payment to retrieve
Response Indicates if the request was successful
Complete payment object with all details from Mercado Pago
cURL Example curl --request GET \ --url http://localhost:8000/api/mercadopago/payments/1234567890
Create Refund Processes a full or partial refund for a payment.
Endpoint POST /api/mercadopago/payments/{paymentId}/refunds
Path Parameters The unique identifier of the payment to refund
Request Parameters Amount to refund. Minimum value: 0.01 If omitted, a full refund will be processed.
Request Example - Full Refund Request Example - Partial Refund Response Indicates if the request was successful
The refund object returned by Mercado Pago ID of the payment being refunded
Refund creation timestamp
cURL Example - Full Refund curl --request POST \ --url http://localhost:8000/api/mercadopago/payments/1234567890/refunds \ --header 'Content-Type: application/json' \ --data '{}'
cURL Example - Partial Refund curl --request POST \ --url http://localhost:8000/api/mercadopago/payments/1234567890/refunds \ --header 'Content-Type: application/json' \ --data '{ "amount": 50 }'
Error Response { "ok" : false , "message" : "Error message describing what went wrong" }
Implementation Notes Availability These endpoints are protected by the mercadopago.demo middleware and only respond when:
MERCADOPAGO_ENABLE_DEMO_ROUTES=true in configurationApplication environment is local or testing
In production or when demo routes are disabled, these endpoints return 404.
Controller Reference Implemented in: src/Http/Controllers/Api/PaymentController.php
store() method: line 15show() method: line 26refund() method: line 35
Request validation:
Payment creation: src/Http/Requests/CreatePaymentRequest.php:16
Refund creation: src/Http/Requests/CreateRefundRequest.php:16
Best Practices Production Usage : For production environments, create your own controllers that inject the PaymentService and RefundService while implementing proper authentication, authorization, and business logic.
Security : Never process payments in production using demo routes. Always implement proper security measures including user authentication and authorization.
Example Production Controller use Fitodac\LaravelMercadoPago\Services\ PaymentService ; final class MercadoPagoPaymentController { public function store ( Request $request , PaymentService $paymentService ) : JsonResponse { // Add your authentication and authorization logic here $payload = $request -> validate ([ 'transaction_amount' => [ 'required' , 'numeric' , 'min:0.01' ], 'token' => [ 'required' , 'string' ], 'description' => [ 'required' , 'string' ], 'installments' => [ 'required' , 'integer' , 'min:1' ], 'payment_method_id' => [ 'required' , 'string' ], 'payer' => [ 'required' , 'array' ], 'payer.email' => [ 'required' , 'email' ], ]); $payment = $paymentService -> create ( $payload ); // Add your business logic here (save to database, send notifications, etc.) return response () -> json ( $payment , 201 ); } }