Payment Methods API

Overview

The Payment Methods API provides information about all payment methods available for your Mercado Pago account. This includes credit cards, debit cards, and other payment instruments accepted in your configured country.

This endpoint is only available in local and testing environments when MERCADOPAGO_ENABLE_DEMO_ROUTES=true. It is automatically disabled in production.

List Payment Methods

Retrieves all available payment methods for your Mercado Pago account.

Endpoint

GET /api/mercadopago/payment-methods

Request Parameters

This endpoint does not require any parameters.

Response

boolean

Indicates if the request was successful

data

array

Array of payment method objects

Show Payment method properties

string

Payment method identifier (e.g., “visa”, “master”, “amex”)

name

string

Display name of the payment method

payment_type_id

string

Type of payment: credit_card, debit_card, ticket, bank_transfer, etc.

status

string

Payment method status: active or inactive

secure_thumbnail

string

HTTPS URL to payment method logo/icon

thumbnail

string

HTTP URL to payment method logo/icon

deferred_capture

string

Whether deferred capture is supported: supported, unsupported, does_not_apply

settings

array

Array of configuration settings for this payment method

additional_info_needed

array

Additional information required for this payment method

min_allowed_amount

numeric

Minimum transaction amount allowed

max_allowed_amount

numeric

Maximum transaction amount allowed

accreditation_time

integer

Time in minutes for payment accreditation

financial_institutions

array

Available financial institutions (for bank transfers)

processing_modes

array

Available processing modes: aggregator, gateway

Response Example

{
  "ok": true,
  "data": [
    {
      "id": "visa",
      "name": "Visa",
      "payment_type_id": "credit_card",
      "status": "active",
      "secure_thumbnail": "https://http2.mlstatic.com/storage/logos-api-admin/visa.png",
      "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/visa.gif",
      "deferred_capture": "supported",
      "settings": [
        {
          "card_number": {
            "validation": "standard",
            "length": 16
          },
          "bin": {
            "pattern": "^4",
            "installments_pattern": "^4",
            "exclusion_pattern": "^(451766|451772|405896|404175|440066)"
          },
          "security_code": {
            "length": 3,
            "card_location": "back",
            "mode": "mandatory"
          }
        }
      ],
      "additional_info_needed": [
        "cardholder_name",
        "cardholder_identification_number",
        "cardholder_identification_type"
      ],
      "min_allowed_amount": 0.01,
      "max_allowed_amount": 250000,
      "accreditation_time": 0,
      "financial_institutions": [],
      "processing_modes": [
        "aggregator"
      ]
    },
    {
      "id": "master",
      "name": "Mastercard",
      "payment_type_id": "credit_card",
      "status": "active",
      "secure_thumbnail": "https://http2.mlstatic.com/storage/logos-api-admin/master.png",
      "thumbnail": "http://img.mlstatic.com/org-img/MP3/API/logos/master.gif",
      "deferred_capture": "supported",
      "min_allowed_amount": 0.01,
      "max_allowed_amount": 250000,
      "accreditation_time": 0,
      "processing_modes": [
        "aggregator"
      ]
    }
  ],
  "meta": []
}

cURL Example

curl --request GET \
  --url http://localhost:8000/api/mercadopago/payment-methods

Error Response

{
  "ok": false,
  "message": "Error message describing what went wrong"
}

Use Cases

Dynamic Payment Method Display

Use this endpoint to dynamically display available payment methods in your checkout interface:

fetch('/api/mercadopago/payment-methods')
  .then(response => response.json())
  .then(result => {
    if (result.ok) {
      const creditCards = result.data.filter(
        method => method.payment_type_id === 'credit_card'
      );
      
      // Display credit card options to user
      creditCards.forEach(card => {
        displayPaymentOption(card.id, card.name, card.secure_thumbnail);
      });
    }
  });

Validation Rules

Use payment method settings to implement client-side validation:

const paymentMethod = paymentMethods.find(pm => pm.id === selectedMethod);
const settings = paymentMethod.settings[0];

// Validate card number length
if (cardNumber.length !== settings.card_number.length) {
  showError('Invalid card number length');
}

// Validate CVV length
if (cvv.length !== settings.security_code.length) {
  showError('Invalid security code length');
}

Amount Validation

Check if the transaction amount is within allowed limits:

const amount = 150.00;
const validMethods = paymentMethods.filter(method => 
  amount >= method.min_allowed_amount && 
  amount <= method.max_allowed_amount
);

Implementation Notes

Availability

This endpoint is protected by the mercadopago.demo middleware and only responds when:

MERCADOPAGO_ENABLE_DEMO_ROUTES=true in configuration
Application environment is local or testing

In production or when demo routes are disabled, this endpoint returns 404.

Controller Reference

Implemented in: src/Http/Controllers/Api/PaymentMethodController.php:12

PaymentMethodService - Service layer for payment method operations

Payment Methods Integration - Guide to integrating payment methods
Checkout Customization - Customize payment method display

Payment Types

Mercado Pago supports various payment types:

Type	Description	Examples
`credit_card`	Credit card payments	Visa, Mastercard, Amex
`debit_card`	Debit card payments	Visa Debit, Maestro
`ticket`	Cash payment vouchers	Boleto, OXXO, Pago Fácil
`bank_transfer`	Bank transfers	PIX, PSE
`atm`	ATM payments	RedLink, Banelco
`digital_currency`	Digital wallets	Mercado Pago Account

Best Practices

Cache Results: Payment methods rarely change. Cache the results for a reasonable time (e.g., 24 hours) to reduce API calls.

Production Usage: For production environments, create your own controller that injects the PaymentMethodService and implements caching strategies.

Country-Specific: Available payment methods depend on your Mercado Pago account configuration and country. Test thoroughly for your target market.

Example Production Controller

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

final class PaymentMethodController
{
    public function index(PaymentMethodService $paymentMethodService): JsonResponse
    {
        $paymentMethods = Cache::remember(
            'mercadopago.payment_methods',
            now()->addDay(),
            fn() => $paymentMethodService->all()
        );

        return response()->json($paymentMethods);
    }
}

Example with Filtering

use Fitodac\LaravelMercadoPago\Services\PaymentMethodService;

Route::get('/checkout/payment-methods', function (
    Request $request,
    PaymentMethodService $service
) {
    $methods = $service->all();
    
    // Filter by payment type if requested
    if ($type = $request->input('type')) {
        $methods = array_filter(
            $methods,
            fn($method) => $method['payment_type_id'] === $type
        );
    }
    
    // Filter by amount if provided
    if ($amount = $request->input('amount')) {
        $methods = array_filter(
            $methods,
            fn($method) => 
                $amount >= $method['min_allowed_amount'] &&
                $amount <= $method['max_allowed_amount']
        );
    }
    
    return response()->json(array_values($methods));
});

Testing

Verify Available Methods

curl http://localhost:8000/api/mercadopago/payment-methods | jq '.data[].id'

Check Credit Card Methods

curl http://localhost:8000/api/mercadopago/payment-methods | \
  jq '.data[] | select(.payment_type_id == "credit_card") | {id, name}'

Validate Amount Limits

curl http://localhost:8000/api/mercadopago/payment-methods | \
  jq '.data[] | {id, min: .min_allowed_amount, max: .max_allowed_amount}'

Services

Demo Endpoints

Configuration

Overview

List Payment Methods

Endpoint

Request Parameters

Response

Response Example

cURL Example

Error Response

Use Cases

Dynamic Payment Method Display

Validation Rules

Amount Validation

Implementation Notes

Availability

Controller Reference

Payment Types

Best Practices

Example Production Controller

Example with Filtering

Testing

Verify Available Methods

Check Credit Card Methods

Validate Amount Limits

Build docs developers (and LLMs) love

Services

Demo Endpoints

Configuration

​Overview

​List Payment Methods

​Endpoint

​Request Parameters

​Response

​Response Example

​cURL Example

​Error Response

​Use Cases

​Dynamic Payment Method Display

​Validation Rules

​Amount Validation

​Implementation Notes

​Availability

​Controller Reference

​Related Services

​Related Guides

​Payment Types

​Best Practices

​Example Production Controller

​Example with Filtering

​Testing

​Verify Available Methods

​Check Credit Card Methods

​Validate Amount Limits

Build docs developers (and LLMs) love

Overview

List Payment Methods

Endpoint

Request Parameters

Response

Response Example

cURL Example

Error Response

Use Cases

Dynamic Payment Method Display

Validation Rules

Amount Validation

Implementation Notes

Availability

Controller Reference

Related Services

Related Guides

Payment Types

Best Practices

Example Production Controller

Example with Filtering

Testing

Verify Available Methods

Check Credit Card Methods

Validate Amount Limits