Skip to main content

​
Overview

The CustomerService class handles customer creation and retrieval in MercadoPago. Customers are used to store payer information and manage saved payment methods (cards). Source: src/Services/CustomerService.php:9

​
Constructor

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 customer in MercadoPago. 
public function create(array $payload): mixed
Source: src/Services/CustomerService.php:15

​
Parameters

​
payload
array
required
The customer configuration data.

​
Returns

​
response
mixed
MercadoPago customer object containing:

​
Usage

use Fitodac\LaravelMercadoPago\Services\CustomerService;
use Illuminate\Http\JsonResponse;
use Illuminate\Http\Request;

final class CustomerController
{
    public function store(
        Request $request,
        CustomerService $customerService
    ): JsonResponse {
        $customer = $customerService->create([
            'email' => $request->email,
            'first_name' => $request->first_name,
            'last_name' => $request->last_name,
            'phone' => [
                'area_code' => $request->area_code,
                'number' => $request->phone_number,
            ],
            'identification' => [
                'type' => 'DNI',
                'number' => $request->dni,
            ],
            'description' => 'Premium customer',
            'metadata' => [
                'user_id' => auth()->id(),
                'plan' => 'premium',
            ],
        ]);
        
        // Store customer ID for future use
        auth()->user()->update([
            'mercadopago_customer_id' => data_get($customer, 'id'),
        ]);
        
        return response()->json([
            'customer_id' => data_get($customer, 'id'),
        ], 201);
    }
}

​
get()

Retrieves customer information by customer ID. 
public function get(string $customerId): mixed
Source: src/Services/CustomerService.php:24

​
Parameters

​
customerId
string
required
The unique customer identifier returned when the customer was created

​
Returns

​
response
mixed
MercadoPago customer object with the same structure as the create() method response. Contains all customer information and metadata.

​
Usage

use Fitodac\LaravelMercadoPago\Services\CustomerService;

$service = app(CustomerService::class);

$customerId = auth()->user()->mercadopago_customer_id;
$customer = $service->get($customerId);

$email = data_get($customer, 'email');
$name = data_get($customer, 'first_name') . ' ' . data_get($customer, 'last_name');

​
Common Patterns

​
One customer per user

Create a MercadoPago customer for each application user: 
// Add to User model
public function getOrCreateMercadoPagoCustomer()
{
    if ($this->mercadopago_customer_id) {
        return app(CustomerService::class)
            ->get($this->mercadopago_customer_id);
    }
    
    $customer = app(CustomerService::class)->create([
        'email' => $this->email,
        'first_name' => $this->first_name,
        'last_name' => $this->last_name,
        'metadata' => [
            'user_id' => $this->id,
        ],
    ]);
    
    $this->update([
        'mercadopago_customer_id' => data_get($customer, 'id'),
    ]);
    
    return $customer;
}

​
Customer with saved cards

Customers are required for saving payment methods: 
use Fitodac\LaravelMercadoPago\Services\CustomerService;
use Fitodac\LaravelMercadoPago\Services\CardService;

// Create customer first
$customer = app(CustomerService::class)->create([
    'email' => '[email protected]',
    'first_name' => 'John',
    'last_name' => 'Doe',
]);

$customerId = data_get($customer, 'id');

// Then save card
$card = app(CardService::class)->create($customerId, [
    'token' => $cardToken,
]);

​
Error Handling

​
MercadoPagoConfigurationException
exception
Thrown when:
  • MercadoPago SDK is not installed
  • Required SDK classes are not found
  • SDK methods are unavailable
​
MercadoPagoException
exception
Thrown by the MercadoPago SDK for API errors:
  • Invalid credentials
  • Invalid customer data
  • Customer not found (for get() method)
  • Duplicate customer
  • Network errors

​
Error handling example

use Fitodac\LaravelMercadoPago\Exceptions\MercadoPagoConfigurationException;

try {
    $customer = $customerService->create($payload);
} catch (MercadoPagoConfigurationException $e) {
    \Log::error('MercadoPago configuration error', [
        'message' => $e->getMessage(),
    ]);
    return response()->json(['error' => 'Service misconfigured'], 500);
} catch (\Exception $e) {
    \Log::error('Customer creation failed', [
        'message' => $e->getMessage(),
        'payload' => $payload,
    ]);
    return response()->json(['error' => 'Customer creation failed'], 500);
}

CardService

Save and manage customer payment methods

PaymentService

Process payments for customers

​
Additional Resources

Managing Customers Guide

Complete guide to customer management

MercadoPago API Documentation

Official customers API reference

Build docs developers (and LLMs) love

Get started for freeTalk to us