MpApi

Uma gem Ruby para integração com a API do Mercado Pago, oferecendo uma interface simples e elegante para gerenciar pagamentos, clientes e cartões.

Instalação

Adicione esta linha ao Gemfile da sua aplicação:

gem 'mp_api'

E então execute:

bundle install

Ou instale diretamente:

gem install mp_api

Criando um Cliente

# Inicialize o cliente
client = MpApi::Client.new("SEU_ACCESS_TOKEN")

Pagamentos PIX

# Criar um pagamento PIX
response = client.create_pix_payment(
  amount: 100.50,
  description: "Pagamento de teste",
  payment_method: "pix",
  payer_email: "[email protected]",
  payer_identification_type: "CPF",
  payer_identification_number: "12345678901",
  date_of_expiration: "2025-12-31T23:59:59.000-04:00"
)

Pagamentos com Cartão de Crédito

# Criar um pagamento com cartão de crédito
response = client.create_credit_card_payment(
  amount: 250.00,
  description: "Compra online",
  payment_method: "visa",
  payer_email: "[email protected]",
  payer_identification_type: "CPF",
  payer_identification_number: "12345678901",
  token: "TOKEN_DO_CARTAO",
  installments: 3,
  three_d_secure_mode: true
)

Pagamentos com Cartão Salvo

# Criar pagamento com cartão previamente salvo
response = client.create_saved_credit_card_payment(
  amount: 150.00,
  token: "TOKEN_DO_CARTAO_SALVO",
  installments: 1,
  customer_id: "CUSTOMER_ID"
)

Gerenciamento de Pagamentos

# Consultar um pagamento
payment = client.get_payment("PAYMENT_ID")

# Atualizar status de um pagamento
client.update_payment(
  payment_id: "PAYMENT_ID",
  status: "cancelled"
)

Tokenização de Cartões

# Criar token para um cartão
token_response = client.create_token(
  card_number: "4111111111111111",
  expiration_year: "2028",
  expiration_month: "12",
  security_code: "123",
  cardholder_name: "João Silva"
)

Métodos de Pagamento

# Buscar métodos de pagamento por BIN
payment_methods = client.search_payment_methods(
  first_six_digits: "411111"
)

# Listar todos os métodos de pagamento
all_methods = client.get_payment_methods

Gerenciamento de Clientes

# Buscar cliente por email
customer = client.get_customer("[email protected]")

# Criar um novo cliente
new_customer = client.create_customer(
  email: "[email protected]",
  first_name: "João",
  identification_type: "CPF",
  identification_number: "12345678901",
  phone_area_code: "11",
  phone_number: "999999999"
)

Gerenciamento de Cartões

# Adicionar cartão a um cliente
card = client.create_card(
  customer_id: "CUSTOMER_ID",
  token: "TOKEN_DO_CARTAO"
)

# Remover cartão de um cliente
client.delete_card(
  customer_id: "CUSTOMER_ID",
  card_id: "CARD_ID"
)

Tratamento de Erros

A gem utiliza a classe MpApi::Error para tratamento de erros:

begin
  response = client.create_pix_payment(...)
rescue MpApi::Error => e
  puts "Erro na API: #{e.message}"
end

Funcionalidades

  • ✅ Pagamentos PIX
  • ✅ Pagamentos com cartão de crédito
  • ✅ Pagamentos com cartões salvos
  • ✅ Tokenização de cartões
  • ✅ Gerenciamento de clientes
  • ✅ Gerenciamento de cartões
  • ✅ Consulta de métodos de pagamento
  • ✅ Atualização de pagamentos
  • ✅ Suporte a parcelamento
  • ✅ Suporte a 3D Secure

Dependências

Esta gem depende da gem ac (>= 1.1.0) para funcionalidades de cliente HTTP.