Customers API

Overview

The Customers API allows you to create and manage customer records in Mercado Pago, retrieve customer information, and manage their saved payment cards. This is useful for storing customer payment methods for future transactions.

These endpoints are only available in local and testing environments when MERCADOPAGO_ENABLE_DEMO_ROUTES=true. They are automatically disabled in production.

Create Customer

Creates a new customer record in Mercado Pago.

Endpoint

POST /api/mercadopago/customers

Request Parameters

string

required

Customer email address. Must be a valid email format.

first_name

string

Customer first name

last_name

string

Customer last name

phone

object

Customer phone information

Show Phone properties

phone.area_code

string

Phone area code

phone.number

string

Phone number

identification

object

Customer identification document

Show Identification properties

identification.type

string

Document type (e.g., “DNI”, “CPF”, “CUIT”)

identification.number

string

Document number

default_address

object

Customer default address

Show Address properties

default_address.zip_code

string

ZIP/Postal code

default_address.street_name

string

Street name

default_address.street_number

integer

Street number

metadata

object

Custom metadata object for additional information

Request Example

{
  "email": "[email protected]",
  "first_name": "Ada",
  "last_name": "Lovelace"
}

Response

boolean

Indicates if the request was successful

data

object

The customer object returned by Mercado Pago

Show Customer properties

string

Unique customer identifier

string

Customer email

first_name

string

Customer first name

last_name

string

Customer last name

phone

object

Customer phone information

identification

object

Customer identification document

default_address

object

Customer default address

date_created

string

Customer creation timestamp

cards

array

Array of saved cards for this customer

cURL Example

curl --request POST \
  --url http://localhost:8000/api/mercadopago/customers \
  --header 'Content-Type: application/json' \
  --data '{
    "email": "[email protected]",
    "first_name": "Ada",
    "last_name": "Lovelace"
  }'

Get Customer

Retrieves details of a specific customer.

Endpoint

GET /api/mercadopago/customers/{customerId}

Path Parameters

customerId

string

required

The unique identifier of the customer to retrieve

Response

boolean

Indicates if the request was successful

data

object

Complete customer object with all details including saved cards

cURL Example

curl --request GET \
  --url http://localhost:8000/api/mercadopago/customers/123456789

Add Card to Customer

Adds a tokenized card to a customer’s saved payment methods.

Endpoint

POST /api/mercadopago/customers/{customerId}/cards

Path Parameters

customerId

string

required

The unique identifier of the customer

Request Parameters

token

string

required

Card token generated by Mercado Pago’s tokenization service

Request Example

{
  "token": "CARD_TOKEN"
}

Response

boolean

Indicates if the request was successful

data

object

The card object returned by Mercado Pago

Show Card properties

string

Unique card identifier

customer_id

string

ID of the customer who owns this card

first_six_digits

string

First 6 digits of the card number

last_four_digits

string

Last 4 digits of the card number

expiration_month

integer

Card expiration month

expiration_year

integer

Card expiration year

payment_method

object

Payment method information

date_created

string

Card creation timestamp

cURL Example

curl --request POST \
  --url http://localhost:8000/api/mercadopago/customers/123456789/cards \
  --header 'Content-Type: application/json' \
  --data '{
    "token": "CARD_TOKEN"
  }'

Delete Customer Card

Removes a saved card from a customer’s payment methods.

Endpoint

DELETE /api/mercadopago/customers/{customerId}/cards/{cardId}

Path Parameters

customerId

string

required

The unique identifier of the customer

cardId

string

required

The unique identifier of the card to delete

Response

boolean

Indicates if the request was successful

data

object

Confirmation object from Mercado Pago

cURL Example

curl --request DELETE \
  --url http://localhost:8000/api/mercadopago/customers/123456789/cards/987654321

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 configuration
Application 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/CustomerController.php

store() method: line 15
show() method: line 26
storeCard() method: line 35
destroyCard() method: line 47

Request validation:

Customer creation: src/Http/Requests/CreateCustomerRequest.php:16
Card storage: src/Http/Requests/StoreCustomerCardRequest.php:16

CustomerService - Service layer for customer operations
CardService - Service layer for card operations

Managing Customers - Complete guide on customer management
Saved Cards - Working with saved payment methods

Best Practices

Production Usage: For production environments, create your own controllers that inject the CustomerService and CardService while implementing proper authentication and authorization.

Security: Always validate that users can only access and modify their own customer records. Implement proper authorization checks in your production controllers.

Card Tokens: Card tokens must be generated using Mercado Pago’s client-side tokenization. Never send raw card data through your server.

Example Production Controller

use Fitodac\LaravelMercadoPago\Services\CustomerService;

final class CustomerManagementController
{
    public function store(Request $request, CustomerService $customerService): JsonResponse
    {
        // Ensure user is authenticated
        $user = $request->user();
        
        $payload = $request->validate([
            'email' => ['required', 'email'],
            'first_name' => ['sometimes', 'string'],
            'last_name' => ['sometimes', 'string'],
        ]);

        $customer = $customerService->create($payload);
        
        // Save customer ID to your database associated with the user
        $user->update(['mercadopago_customer_id' => $customer['id']]);

        return response()->json($customer, 201);
    }
}

Services

Demo Endpoints

Configuration

Overview

Create Customer

Endpoint

Request Parameters

Request Example

Response

cURL Example

Get Customer

Endpoint

Path Parameters

Response

cURL Example

Add Card to Customer

Endpoint

Path Parameters

Request Parameters

Request Example

Response

cURL Example

Delete Customer Card

Endpoint

Path Parameters

Response

cURL Example

Error Response

Implementation Notes

Availability

Controller Reference

Best Practices

Example Production Controller

Build docs developers (and LLMs) love

Services

Demo Endpoints

Configuration

​Overview

​Create Customer

​Endpoint

​Request Parameters

​Request Example

​Response

​cURL Example

​Get Customer

​Endpoint

​Path Parameters

​Response

​cURL Example

​Add Card to Customer

​Endpoint

​Path Parameters

​Request Parameters

​Request Example

​Response

​cURL Example

​Delete Customer Card

​Endpoint

​Path Parameters

​Response

​cURL Example

​Error Response

​Implementation Notes

​Availability

​Controller Reference

​Related Services

​Related Guides

​Best Practices

​Example Production Controller

Build docs developers (and LLMs) love

Overview

Create Customer

Endpoint

Request Parameters

Request Example

Response

cURL Example

Get Customer

Endpoint

Path Parameters

Response

cURL Example

Add Card to Customer

Endpoint

Path Parameters

Request Parameters

Request Example

Response

cURL Example

Delete Customer Card

Endpoint

Path Parameters

Response

cURL Example

Error Response

Implementation Notes

Availability

Controller Reference

Related Services

Related Guides

Best Practices

Example Production Controller