Documentacion API

Referencia para integrar con Mopago

Usa esta documentacion para autenticar tu aplicacion, consultar informacion de wallet, generar links de pago y recibir el webhook normalizado cuando el link se paga.

GET /api/v1/health es un ping tecnico de plataforma. El health de upstream queda como diagnostico operativo interno y no forma parte del flujo normal del integrador.

Ambientes

Usa UAT para pruebas de integracion y produccion solo cuando tus credenciales hayan sido habilitadas.

UAT https://developers-uat.mopago.com/api/v1

Produccion https://developers.mopago.com/api/v1

Primeros pasos

1

Crea una cuenta developer

Tu cuenta queda pendiente hasta aprobacion administrativa.

2

Registra una aplicacion

Guarda el `client_id`, el `secret_key` y los tokens identificadores de developer y aplicacion.

3

Emite un token

Intercambia credenciales por un bearer token `mpp_app_*` y usalo en los endpoints protegidos.

Autenticacion

Los endpoints protegidos requieren un token de aplicacion emitido por POST /api/v1/auth/token.

Header para endpoints protegidos

Authorization: Bearer mpp_app_...
Accept: application/json

Estado de plataforma

Ping tecnico

GET /api/v1/health

Valida que el gateway responde antes de ejecutar pruebas de integracion.

Endpoints disponibles para consumir

Cada ejemplo usa UAT como base URL. Para produccion cambia el host a developers.mopago.com.

Los endpoints proxy mantienen el payload completo de Mopago dentro de data. Los campos internos pueden variar segun la respuesta upstream; el wrapper del gateway siempre incluye status, developer_code, mopago_customer_id, data y raw_body.

Estado de plataforma

GET /api/v1/health

Publico

Headers + request

curl https://developers-uat.mopago.com/api/v1/health \
  -H "Accept: application/json"

Response 200

{
  "status": "ok",
  "service": "mopago-developer-platform",
  "timestamp": "2026-06-16T00:00:00Z"
}

Generar token de aplicacion

POST /api/v1/auth/token

Publico con credenciales

Headers + request

curl -X POST https://developers-uat.mopago.com/api/v1/auth/token \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "developer_identifier_token": "dev_40_char_sha",
    "application_identifier_token": "app_40_char_sha",
    "client_id": "mopago_cli_live",
    "secret_key": "mopago_sec_live"
  }'

Response 200

{
  "status": "ok",
  "token_type": "Bearer",
  "access_token": "mpp_app_...",
  "expires_in": 3600,
  "mopago_customer_id": "12345",
  "application": {
    "id": 10,
    "name": "Mi aplicacion",
    "status": "active"
  }
}

Perfil del usuario Mopago

GET /api/v1/wallet/profile

Requiere bearer

Headers + request

curl https://developers-uat.mopago.com/api/v1/wallet/profile \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json"

Response 200

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "id": 12345,
      "name": "Cliente",
      "last_name": "Mopago",
      "email": "cliente@example.com",
      "phone": "+51999999999",
      "document_type": "DNI",
      "document_number": "12345678",
      "status": "active",
      "created_at": "2026-06-16T00:00:00Z"
    }
  },
  "raw_body": null
}

Verificar token Mopago

GET /api/v1/wallet/verify-token

Requiere bearer

Headers + request

curl https://developers-uat.mopago.com/api/v1/wallet/verify-token \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json"

Response 200

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "valid": true,
      "customer_id": "12345"
    }
  },
  "raw_body": null
}

Saldo actual

GET /api/v1/wallet/current-balance

Requiere bearer

Headers + request

curl https://developers-uat.mopago.com/api/v1/wallet/current-balance \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json"

Response 200

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "balance": "1500.00",
      "currency": "PEN",
      "available": "1500.00"
    }
  },
  "raw_body": null
}

Movimientos de wallet

GET /api/v1/wallet/transactions

Filtros opcionales

Headers + request

curl "https://developers-uat.mopago.com/api/v1/wallet/transactions?transaction=income&typeMov=transfers&period=today&page=1&per_page=20" \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json"

Query params:
transaction=income | expense
typeMov=transfers | recharges | service_payments | mep_dollar_purchase | qr_payment | commission_parent | commission
period=today | yesterday | last_week | last_month
page=1
per_page=20

Response 200

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "transactions": [
        {
          "id": "mov_001",
          "amount": "125.00",
          "transaction": "income",
          "typeMov": "transfers",
          "created_at": "2026-06-16T00:00:00Z"
        }
      ],
      "pagination": {
        "page": 1,
        "per_page": 20,
        "total": 1
      }
    }
  },
  "raw_body": null
}

Crear link de pago

POST /api/v1/payment-links

Requiere bearer

Headers + request

curl -X POST https://developers-uat.mopago.com/api/v1/payment-links \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12500,
    "currency": "PEN",
    "reference": "order_1024",
    "description": "Compra order_1024"
  }'

Response 201

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "id": "plink_1024",
      "payment_url": "https://...",
      "reference": "order_1024",
      "amount": 12500,
      "currency": "PEN",
      "status": "pending"
    }
  },
  "raw_body": null
}

Consultar link de pago

GET /api/v1/payment-links/{id}

Requiere bearer

Headers + request

curl https://developers-uat.mopago.com/api/v1/payment-links/plink_1024 \
  -H "Authorization: Bearer mpp_app_..." \
  -H "Accept: application/json"

Response 200

{
  "status": "ok",
  "developer_code": "mpp_dev_00000001",
  "mopago_customer_id": "12345",
  "data": {
    "success": true,
    "data": {
      "id": "plink_1024",
      "status": "paid",
      "reference": "order_1024",
      "amount": 12500,
      "currency": "PEN",
      "paid_at": "2026-06-16T00:00:00Z"
    }
  },
  "raw_body": null
}

Webhook de link de pago

Configura una URL HTTPS por aplicacion desde el portal developer. Cuando Mopago confirma el pago, la plataforma reenvia un evento normalizado a tu URL.

Evento recibido por tu aplicacion

POST Tu webhook URL

payment_link.paid

Headers + request

Content-Type: application/json
User-Agent: Mopago-Developer-Platform

{
  "source": "mopago_developer_platform",
  "event": "payment_link.paid",
  "payment_id": "order_1024",
  "developer_code": "mpp_dev_00000001",
  "payload": {
    "Payload": {
      "MensajePago": {
        "IdentificadorOrdenVenta": "order_1024",
        "EstadoTransaccion": "APROBADA"
      }
    }
  }
}

Response esperada

HTTP/1.1 200 OK
Content-Type: application/json

{
  "received": true
}

SDKs y REST

Node.jsnpm

PHPcomposer

RESTcurl