TestUserService

Overview

The TestUserService class creates test users in MercadoPago’s sandbox environment. Test users are required for testing payment flows without processing real transactions. Source: src/Services/TestUserService.php:9

Test users are only for sandbox/testing environments. They provide test credentials and test payment methods for development and QA.

Constructor

public function __construct(
    private SdkHttpClient $sdkHttpClient,
) {}

Dependencies

sdkHttpClient

SdkHttpClient

required

HTTP client for making direct API calls to MercadoPago. Automatically injected by Laravel’s service container.

Unlike other services, TestUserService uses SdkHttpClient instead of MercadoPagoClientFactory because the MercadoPago SDK doesn’t provide a dedicated test user client.

Methods

create()

Creates a new test user in MercadoPago sandbox.

public function create(array $payload): mixed

Source: src/Services/TestUserService.php:15

Parameters

payload

array

required

The test user configuration data.

Show Payload structure

site_id

string

required

MercadoPago site identifier for the country:

MLA - Argentina
MLB - Brazil
MLM - Mexico
MLC - Chile
MLU - Uruguay
MCO - Colombia
MPE - Peru

Returns

response

array

Test user data from MercadoPago API:

Show Response structure

integer

Test user identifier

nickname

string

Test user nickname/username

string

Test user email address

site_id

string

Country site identifier

site_status

string

User status in the site

date_created

string

ISO 8601 creation timestamp

Usage

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

final class TestUserController
{
    public function store(
        Request $request,
        TestUserService $testUserService
    ): JsonResponse {
        $testUser = $testUserService->create([
            'site_id' => 'MLA', // Argentina
        ]);
        
        return response()->json([
            'id' => data_get($testUser, 'id'),
            'email' => data_get($testUser, 'email'),
            'nickname' => data_get($testUser, 'nickname'),
        ], 201);
    }
}

Site IDs

MercadoPago operates in multiple countries, each with a unique site ID:

Site ID	Country	Currency
`MLA`	Argentina	ARS
`MLB`	Brazil	BRL
`MLM`	Mexico	MXN
`MLC`	Chile	CLP
`MLU`	Uruguay	UYU
`MCO`	Colombia	COP
`MPE`	Peru	PEN

Always create test users for the same country/site as your production MercadoPago account.

Common Patterns

Create test users for different roles

Create separate test users for sellers and buyers:

use Fitodac\LaravelMercadoPago\Services\TestUserService;

$service = app(TestUserService::class);

// Create seller test user
$seller = $service->create(['site_id' => 'MLA']);

// Create buyer test user  
$buyer = $service->create(['site_id' => 'MLA']);

// Store credentials for testing
config([
    'testing.mercadopago.seller_email' => data_get($seller, 'email'),
    'testing.mercadopago.buyer_email' => data_get($buyer, 'email'),
]);

Setup command for development

Create an artisan command to initialize test environment:

use Fitodac\LaravelMercadoPago\Services\TestUserService;
use Illuminate\Console\Command;

class SetupMercadoPagoTesting extends Command
{
    protected $signature = 'mp:setup-testing';
    protected $description = 'Setup MercadoPago test environment';
    
    public function handle(TestUserService $service)
    {
        if (!app()->environment('local', 'testing')) {
            $this->error('This command is only for local/testing environments');
            return 1;
        }
        
        $this->info('Creating test users...');
        
        $siteId = config('mercadopago.site_id', 'MLA');
        
        $seller = $service->create(['site_id' => $siteId]);
        $buyer = $service->create(['site_id' => $siteId]);
        
        $this->info('Test users created successfully!');
        
        $this->newLine();
        $this->info('Seller credentials:');
        $this->line('  Email: ' . data_get($seller, 'email'));
        
        $this->newLine();
        $this->info('Buyer credentials:');
        $this->line('  Email: ' . data_get($buyer, 'email'));
        
        $this->newLine();
        $this->info('Update your .env.testing file with these credentials.');
        
        return 0;
    }
}

Generate test users in tests

Create test users programmatically in PHPUnit tests:

use Fitodac\LaravelMercadoPago\Services\TestUserService;
use Tests\TestCase;

class MercadoPagoPaymentTest extends TestCase
{
    protected function setUp(): void
    {
        parent::setUp();
        
        if (!config('mercadopago.testing')) {
            $this->markTestSkipped('MercadoPago testing not enabled');
        }
    }
    
    public function test_can_create_payment()
    {
        // Create test user
        $testUser = app(TestUserService::class)->create([
            'site_id' => 'MLA',
        ]);
        
        $this->assertArrayHasKey('email', $testUser);
        $this->assertArrayHasKey('nickname', $testUser);
        
        // Use test user credentials for payment testing
        // ...
    }
}

Store test users for reuse

Cache test user data to avoid creating new ones repeatedly:

use Fitodac\LaravelMercadoPago\Services\TestUserService;
use Illuminate\Support\Facades\Cache;

function getOrCreateTestUser(string $siteId = 'MLA', string $role = 'seller')
{
    $cacheKey = "mercadopago.test_user.{$siteId}.{$role}";
    
    return Cache::remember($cacheKey, now()->addDays(30), function () use ($siteId) {
        return app(TestUserService::class)->create(['site_id' => $siteId]);
    });
}

// Usage
$sellerTestUser = getOrCreateTestUser('MLA', 'seller');
$buyerTestUser = getOrCreateTestUser('MLA', 'buyer');

Testing Workflows

Using test users

Create test users using this service
Get test credentials from the response (email, access token)
Configure test environment with test user credentials
Use test cards provided by MercadoPago for testing payments
Test payment flows in sandbox environment

Test cards

MercadoPago provides test card numbers for different scenarios:

Card	Number	CVV	Expiration
Approved	5031 7557 3453 0604	123	11/25
Insufficient funds	5031 4332 1540 6351	123	11/25
Rejected	5031 4336 9399 1761	123	11/25

Test card numbers vary by country. Check MercadoPago’s test cards documentation for your specific country.

Environment Considerations

Never use test users or test credentials in production environments. Test users only work in MercadoPago’s sandbox and will fail in production.

Environment detection

Restrict test user creation to appropriate environments:

use Fitodac\LaravelMercadoPago\Services\TestUserService;

public function createTestUser(Request $request)
{
    // Only allow in non-production environments
    if (app()->environment('production')) {
        abort(403, 'Test users cannot be created in production');
    }
    
    $testUser = app(TestUserService::class)->create([
        'site_id' => $request->input('site_id', 'MLA'),
    ]);
    
    return response()->json($testUser);
}

Middleware for test endpoints

namespace App\Http\Middleware;

use Closure;
use Illuminate\Http\Request;

class RequireTestingEnvironment
{
    public function handle(Request $request, Closure $next)
    {
        if (!app()->environment('local', 'testing', 'staging')) {
            abort(403, 'This endpoint is only available in testing environments');
        }
        
        return $next($request);
    }
}

// Apply to routes
Route::middleware('testing.environment')->group(function () {
    Route::post('/test-users', [TestUserController::class, 'store']);
});

Error Handling

MercadoPagoException

exception

Thrown by the MercadoPago API for errors:

Invalid site ID
Invalid credentials
API rate limits
Network errors

MercadoPagoConfigurationException

exception

Thrown when:

MercadoPago SDK is not properly configured
HTTP client cannot be initialized

Error handling example

use Fitodac\LaravelMercadoPago\Services\TestUserService;

try {
    $testUser = app(TestUserService::class)->create([
        'site_id' => $siteId,
    ]);
    
    return response()->json([
        'success' => true,
        'test_user' => $testUser,
    ]);
    
} catch (\Exception $e) {
    \Log::error('Test user creation failed', [
        'site_id' => $siteId,
        'error' => $e->getMessage(),
    ]);
    
    return response()->json([
        'success' => false,
        'error' => 'Could not create test user',
        'message' => $e->getMessage(),
    ], 500);
}

PaymentService

Test payments with test user credentials

PreferenceService

Test checkout preferences

Additional Resources

Testing Guide

Complete guide to testing MercadoPago integration

MercadoPago Test Users Documentation

Official test users documentation

Services

Demo Endpoints

Configuration

Overview

Constructor

Dependencies

Methods

create()

Parameters

Returns

Usage

Site IDs

Common Patterns

Create test users for different roles

Setup command for development

Generate test users in tests

Store test users for reuse

Testing Workflows

Using test users

Test cards

Environment Considerations

Environment detection

Middleware for test endpoints

Error Handling

Error handling example

PaymentService

PreferenceService

Additional Resources

Testing Guide

MercadoPago Test Users Documentation

Build docs developers (and LLMs) love

Services

Demo Endpoints

Configuration

​Overview

​Constructor

​Dependencies

​Methods

​create()

​Parameters

​Returns

​Usage

​Site IDs

​Common Patterns

​Create test users for different roles

​Setup command for development

​Generate test users in tests

​Store test users for reuse

​Testing Workflows

​Using test users

​Test cards

​Environment Considerations

​Environment detection

​Middleware for test endpoints

​Error Handling

​Error handling example

​Related Services

PaymentService

PreferenceService

​Additional Resources

Testing Guide

MercadoPago Test Users Documentation

Build docs developers (and LLMs) love

Overview

Constructor

Dependencies

Methods

create()

Parameters

Returns

Usage

Site IDs

Common Patterns

Create test users for different roles

Setup command for development

Generate test users in tests

Store test users for reuse

Testing Workflows

Using test users

Test cards

Environment Considerations

Environment detection

Middleware for test endpoints

Error Handling

Error handling example

Related Services

Additional Resources