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 details.step field indicating where the process stopped, and a details.partialData object with the data obtained so far. The client can then call the corresponding step endpoint to resume the process.

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.",
    "details": {
      "step": "charge",
      "partialData": {
        "msisdnId": "612345678",
        "qrCode": "LPA:1$sm-..."
      }
    }
  },
  "meta": { "requestId": "..." }
}

When details.step is "charge", use the following endpoint to resume:

• "charge" → POST /api/v2/msmvl/activation/step/charge

Possible errors:

Resume the activation process from the charge step (wallet charge + recharge + bundle purchase). Use this when the initial activation succeeded but a subsequent step failed (error response contained "details.step": "charge").

Body (JSON):

{
  "msisdnId": "612345678",
  "qrCode": "LPA:1$sm-...",
  "productId": "PO_Mali_M",
  "brand": "Lebara",
  "simType": "sim",
  "iccId": "89340712341234567890",
  "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": "..." }
}

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 (created when the user had insufficient wallet balance at activation time or when the Ya Ganaste recharge failed).

Query params:

Response:

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

Possible errors:

Complete a pending activation recharge. Performs the external recharge and bundle purchase when needed to finish an activation that was left pending. The pending recharge record is deleted upon success.

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": "..." }
}