API v2 Documentation

Activate a SIM or eSIM card. Performs the full flow: ICC validation (SIM only), document/age validation, activation with the telecom platform, wallet charge, recharge and bundle purchase when applicable.

If the external activation succeeds but a later step fails, the error response will include a recovery object with an activationId and a step field indicating where the process stopped. The client must call POST /api/v2/msmvl/activation/resume with just { "activationId": ... } to resume.

Body (JSON):

{
  "productId": "PO_Mali_M",
  "brand": "Lebara",
  "name": "Juan",
  "surname": "Pérez",
  "surname2": "García",
  "documentNumber": "12345678A",
  "dateOfBirth": "1990-05-15",
  "nationalityId": "ES",
  "iccId": "89340712341234567890",
  "simType": "sim",
  "identificationType": "personal-identity-code",
  "email": "user@example.com",
  "language": "eng"
}

Body fields:

Success response:

{
  "data": {
    "msisdnId": "612345678",
    "qrCode": "LPA:1$sm-...",
    "valueCharged": 5.00,
    "provisionId": "PROV-123456"
  },
  "message": "Activation completed successfully. The amount has been deducted from the wallet...",
  "meta": { "requestId": "..." }
}

Success data fields:

Error response (with step recovery):

{
  "error": {
    "code": "WALLET_UPDATE_FAILED",
    "message": "Failed to process the activation charge.",
    "recovery": {
      "activationId": 42,
      "step": "charge",
      "partialData": {
        "msisdnId": "612345678",
        "qrCode": "LPA:1$sm-..."
      }
    }
  },
  "meta": { "requestId": "..." }
}

When the response includes error.recovery, call the resume endpoint with the activationId:

POST /api/v2/msmvl/activation/resume
{ "activationId": 42 }

Possible values of recovery.step:

Possible errors:

Resume an activation that stopped mid-way. Use this when a previous call to POST /api/v2/msmvl/activation returned an error that included error.recovery.activationId. The server reads the activation state from the database and continues from the step where it stopped.

Body (JSON):

{
  "activationId": 42
}

Body fields:

Success response:

{
  "data": {
    "msisdnId": "612345678",
    "qrCode": "LPA:1$sm-...",
    "valueCharged": 5.00,
    "provisionId": "PROV-123456"
  },
  "message": "Activation completed successfully. The amount has been deducted from the wallet...",
  "meta": { "requestId": "..." }
}

Possible errors:

Get the facial value (activation cost) for a given ICC ID. Used to determine how much balance the SIM already has before activation.

Path params:

Query params:

Response:

{
  "data": {
    "value": 10.00
  },
  "meta": { "requestId": "..." }
}

Get MSMVL activation history for the authenticated user.

Query params:

Response:

{
  "data": {
    "activationHistory": [
      {
        "id": 1,
        "msisdnId": "612345678",
        "qrCode": "LPA:1$sm-...",
        "createdAt": "2026-03-11T10:00:00.000Z"
      }
    ],
    "total": 42
  },
  "message": "Activation history retrieved successfully.",
  "meta": { "requestId": "..." }
}

Get pending recharges for incomplete MSMVL activations. A pending recharge record is created only when the user had insufficient wallet balance at activation time (INSUFFICIENT_BALANCE). Other failure cases (recharge API errors, BundleCash errors) are handled via the /resume endpoint and do not create a pending recharge record.

Query params:

Response:

{
  "data": [...],
  "message": "Pending activation recharges retrieved successfully.",
  "meta": { "requestId": "..." }
}

Possible errors:

Admin-only endpoint. Completes an activation left pending due to insufficient wallet balance (INSUFFICIENT_BALANCE). Bypasses the wallet and calls Masmovil directly (Topup for physical SIM, BundleCash for eSIM). On success, the pending recharge record is deleted and the activation status in msmvl_historial_activaciones is updated to completed. If the SIM facial value already covers the product price, no external call is made but cleanup is still applied. For other failure types use POST /resume instead.

Body (JSON):

{
  "mobileNumber": "612345678"
}

Body fields:

Success response:

{
  "data": {
    "msisdnId": "612345678",
    "amount": 500
  },
  "message": "Recarga realizada correctamente para completar el proceso de activación.",
  "meta": { "requestId": "..." }
}

Success data fields:

Possible errors:

Validate if an ICC ID (SIM card identifier) is available for activation.

Query params:

Validate minimum age requirement (must be at least 18 years old).

Query params:

Validate an identification document number.

Query params:

Get the list of available products for a brand.

Query params:

Get the operator info for a phone number (current operator, origin, portability status).

Get balance for a phone number.

Query params:

Get comprehensive MSISDN info (ICC ID, IMSI, PINs, PUKs, status, product, balance, bonuses, QR code).

Query params:

Get active services for a phone number.

Query params:

Get eSIM activation QR info (URL and request date) for a phone number.

Query params:

Get inventory info (ID and brand) for a mobile number.

Path params:

Response:

{
  "data": {
    "id": "INV_12345",
    "brand": "Lebara"
  },
  "meta": { "requestId": "..." }
}