Overview The PaymentService class handles direct payment processing with tokenized cards and payment status retrieval. This service allows you to create payments within your application without redirecting users to MercadoPago’s checkout.
Source : src/Services/PaymentService.php:9Constructor public function __construct ( private MercadoPagoClientFactory $clientFactory , ) {}
Dependencies clientFactory
MercadoPagoClientFactory
required
Factory for creating and configuring MercadoPago SDK clients. Automatically injected by Laravel’s service container.
Methods create() Creates a new payment using tokenized card data.
public function create ( array $payload ) : mixed
Source : src/Services/PaymentService.php:15Parameters The payment configuration data. Payment amount (must be greater than 0)
Card token obtained from MercadoPago.js SDK
Number of payment installments (minimum 1)
Payment method identifier (e.g., “visa”, “master”, “amex”)
Payer information:
email (string, required): Payer’s email addressidentification (array, optional): ID document details
type (string): Document type (e.g., “DNI”, “CPF”)number (string): Document number
Your internal order or transaction reference
Webhook URL for payment status notifications
Custom key-value data for your application
Returns MercadoPago payment object containing: Unique payment identifier
Payment status: approved, pending, in_process, rejected, cancelled, refunded, or charged_back
Detailed status reason (e.g., “accredited”, “cc_rejected_insufficient_amount”)
Currency code (e.g., “ARS”, “BRL”)
Payment type (e.g., “credit_card”, “debit_card”)
ISO 8601 creation timestamp
ISO 8601 approval timestamp (null if not approved)
Payer information including email and identification
Card details (first 6 digits, last 4 digits, cardholder info)
Usage Controller injection
With error handling
use Fitodac\LaravelMercadoPago\Services\ PaymentService ; use Illuminate\Http\ JsonResponse ; use Illuminate\Http\ Request ; final class PaymentController { public function store ( Request $request , PaymentService $paymentService ) : JsonResponse { $payment = $paymentService -> create ([ 'transaction_amount' => 100.50 , 'token' => $request -> card_token , 'description' => 'Premium subscription' , 'installments' => 1 , 'payment_method_id' => 'visa' , 'payer' => [ 'email' => '[email protected] ' , ], 'external_reference' => 'ORDER-12345' , 'notification_url' => route ( 'mercadopago.webhooks' ), ]); if ( data_get ( $payment , 'status' ) === 'approved' ) { return response () -> json ([ 'success' => true , 'payment_id' => data_get ( $payment , 'id' ), ]); } return response () -> json ([ 'success' => false , 'status' => data_get ( $payment , 'status' ), 'detail' => data_get ( $payment , 'status_detail' ), ], 422 ); } }
get() Retrieves payment information by payment ID.
public function get ( string $paymentId ) : mixed
Source : src/Services/PaymentService.php:24Parameters The unique payment identifier returned when the payment was created
Returns MercadoPago payment object with the same structure as the create() method response. Contains current payment status and all payment details.
Usage Controller method
Checking payment status
Route definition
use Fitodac\LaravelMercadoPago\Services\ PaymentService ; use Illuminate\Http\ JsonResponse ; public function show ( string $paymentId , PaymentService $paymentService ) : JsonResponse { $payment = $paymentService -> get ( $paymentId ); return response () -> json ([ 'id' => data_get ( $payment , 'id' ), 'status' => data_get ( $payment , 'status' ), 'status_detail' => data_get ( $payment , 'status_detail' ), 'amount' => data_get ( $payment , 'transaction_amount' ), 'date_approved' => data_get ( $payment , 'date_approved' ), ]); }
Payment Statuses Status Description approvedPayment approved and credited pendingPayment pending further processing in_processPayment is being reviewed rejectedPayment was rejected cancelledPayment was cancelled refundedPayment was refunded charged_backPayment was charged back
Common Status Details Status Detail Meaning accreditedPayment successfully credited pending_contingencyPending review pending_review_manualManual review required cc_rejected_bad_filled_card_numberInvalid card number cc_rejected_bad_filled_dateInvalid expiration date cc_rejected_bad_filled_security_codeInvalid CVV/security code cc_rejected_insufficient_amountInsufficient funds cc_rejected_high_riskRejected by fraud prevention
Error Handling MercadoPagoConfigurationException
Thrown when:
MercadoPago SDK is not installed
Required SDK classes are not found
SDK methods are unavailable
Thrown by the MercadoPago SDK for API errors:
Invalid credentials
Invalid payment data
Payment not found (for get() method)
Network errors
Error handling example use Fitodac\LaravelMercadoPago\Exceptions\ MercadoPagoConfigurationException ; try { $payment = $paymentService -> create ( $payload ); if ( data_get ( $payment , 'status' ) === 'approved' ) { // Success } } catch ( MercadoPagoConfigurationException $e ) { return response () -> json ([ 'error' => 'Service misconfigured' ], 500 ); } catch ( \ Exception $e ) { \ Log :: error ( 'Payment error' , [ 'message' => $e -> getMessage (), 'payload' => $payload , ]); return response () -> json ([ 'error' => 'Payment processing failed' ], 500 ); }
RefundService Refund approved payments
PaymentMethodService Get available payment methods
WebhookService Handle payment notifications
CustomerService Manage customer data
Additional Resources
Processing Payments Guide Complete guide to payment processing
MercadoPago API Documentation Official payments API reference