Tops up an existing eSIM with a data plan, paid from your account credit.

The call queues the top-up and returns a recharge_transaction_id straight away; the top-up itself completes a few seconds later. Track the outcome with Recharge Transaction Status (polling) and/or a signed completion callback (notification_url).

Request

• Method: POST
• URL: https://api.bnesim.com/v2.0/enterprise/simcard/recharge
• Content-Type: multipart/form-data
• Authentication: Bearer token required

Parameters

• license_cli (Required): CLI of the customer license that owns the eSIM
• iccid (Required): ICCID of the eSIM to top up - it must belong to license_cli
• product_id (Required): ID of the data plan to add (from the Products endpoint)
• notification_url (Optional): https:// URL that receives a signed callback when the top-up completes or fails. Requires a webhook secret - see Create / Rotate Webhook Secret.

Response Fields

• success: true when the top-up was accepted and queued
• recharge_transaction_id: ID of this top-up - store it and use it with Recharge Transaction Status
• status: initial status of the top-up (TO_BE_PROCESSED)
• remaining_credit: your account credit (EUR) after this charge

Errors

Errors are returned with HTTP 200 and success: false, plus a translation_key and an UPPER_CASE error_code you can branch on:

Completion callback (optional)

When the top-up reaches a final state we POST this JSON to your notification_url:

{
  "event": "recharge.completed",
  "recharge_transaction_id": 1081234,
  "status": "OK",
  "state": "COMPLETED",
  "license_cli": "123456789",
  "iccid": "8948010010047473136",
  "product_id": 106135,
  "timestamp": 1792000000
}

• event: recharge.completed or recharge.failed; state: COMPLETED or FAILED
• Headers: X-BNESIM-Timestamp: <unix seconds> and X-BNESIM-Signature: sha256=<hex>, where <hex> = HMAC-SHA256(your webhook secret, "<timestamp>.<raw body>")
• Verify every callback: recompute the HMAC over the raw request body, compare in constant time, and reject timestamps older than 5 minutes. Answer with any 2xx.
• Delivery is best-effort (2 attempts). Recharge Transaction Status is the source of truth.

$raw = file_get_contents('php://input');
$ts  = $_SERVER['HTTP_X_BNESIM_TIMESTAMP'] ?? '';
$sig = $_SERVER['HTTP_X_BNESIM_SIGNATURE'] ?? '';
$valid = abs(time() - (int) $ts) <= 300
    && hash_equals('sha256=' . hash_hmac('sha256', $ts . '.' . $raw, $webhook_secret), $sig);

Example cURL

curl --request POST \
     --url https://api.bnesim.com/v2.0/enterprise/simcard/recharge \
     --header "accept: application/json" \
     --header "authorization: Bearer {{bearerToken}}" \
     --header "content-type: multipart/form-data" \
     --form license_cli={{license_cli}} \
     --form iccid={{iccid}} \
     --form product_id={{product_id}} \
     --form notification_url=https://example.com/bnesim/recharge-callback

Important Notes

• Do not blindly retry a call that timed out. Every accepted call is a new top-up and is charged separately. Check Recharge Transaction Status (or the eSIM's packages) before trying again.
• Credit is deducted when the request is accepted; remaining_credit shows the balance after the charge.