Allo

Acheter une recharge de données eSIM

Achète des données mobiles en plus pour une eSIM, au-delà de son palier. Une recharge est débitée une seule fois. Ses données comptent pour le mois civil en…

POST/v2/api/partner/esims/{id}/topups

Achète des données mobiles en plus pour une eSIM, au-delà de son palier. Une recharge est débitée une seule fois. Ses données comptent pour le mois civil en cours uniquement (heure de Paris), et les données non utilisées sont perdues à la fin de ce mois.

Quand une eSIM atteint son quota, les données mobiles s'arrêtent jusqu'au mois suivant ou jusqu'à l'achat d'une recharge. Les appels et les SMS continuent de fonctionner, et la ligne n'est jamais facturée pour des données au-delà du quota. Allo envoie partner.esim.data_low à 80 % du quota et partner.esim.data_exhausted à 100 %, pour que vous puissiez proposer une recharge à votre client à temps.

Requête

  • L'en-tête Idempotency-Key est obligatoire : voir Nouvelles tentatives.
  • code est requis : un top_ups[].code renvoyé par Obtenir l'offre eSIM.
  • L'eSIM doit être ACTIVE. Tant qu'elle est en cours de provisionnement, la requête échoue avec ESIM_NOT_READY.
codeDonnées ajoutées
TOPUP_5GB5 Go (5120 Mo)
TOPUP_10GB10 Go (10240 Mo)
TOPUP_20GB20 Go (20480 Mo)

Un code inconnu échoue avec INVALID_ESIM_TOPUP. Vous pouvez acheter plusieurs recharges pour la même eSIM dans le même mois : leurs données s'additionnent.

Réponse

statusSignification
PENDINGAllo a débité la recharge. Ses données sont ajoutées à l'eSIM une fois le paiement confirmé, et Obtenir une eSIM les affiche alors dans data.allowance_mb.
ACTIVEUne nouvelle tentative, avec la même Idempotency-Key, d'une recharge déjà ajoutée. Rien n'est débité à nouveau.

Facturation

  • Le prix est celui que renvoie Obtenir l'offre eSIM pour le compte : hors taxes, dans la devise de l'abonnement que vous payez pour le compte.
  • Allo prélève d'abord votre crédit prépayé, puis débite le reste sur votre carte enregistrée. Allo ne facture jamais votre client.
  • Si votre crédit prépayé ne couvre pas la recharge et qu'aucune carte n'est enregistrée, la requête échoue avec 402 PARTNER_CREDIT_INSUFFICIENT.
  • Une carte refusée, ou une carte qui exige 3D Secure, échoue avec 402 ESIM_PAYMENT_FAILED. Une validation 3D Secure est impossible via l'API : Allo annule la tentative et rien ne reste en attente. Réessayez avec une autre carte, mise à jour dans le portail partenaire, ou après avoir rechargé votre crédit prépayé.

Nouvelles tentatives

L'en-tête Idempotency-Key est obligatoire sur cet endpoint, pour qu'une nouvelle tentative ne vous débite jamais deux fois. Envoyez un nouvel UUID pour chaque recharge, et le même quand vous réessayez cette recharge.

  • Sans l'en-tête, la requête échoue avec 400 IDEMPOTENCY_KEY_REQUIRED.
  • La clé compte 8 à 100 lettres, chiffres, - ou _. Une clé dans un autre format échoue avec 400 INVALID_IDEMPOTENCY_KEY.
  • Une clé déjà utilisée sur cette eSIM pour une recharge avec un autre code échoue avec 409 IDEMPOTENCY_KEY_ALREADY_USED. Envoyez une nouvelle clé pour une nouvelle recharge.

Erreurs propres à l'eSIM

CodeSignification
ESIM_NOT_READYL'eSIM est encore en cours de provisionnement. Attendez partner.esim.ready, puis réessayez.
ESIM_NOT_ACTIVEL'eSIM a été supprimée, ou le numéro a une commande d'eSIM plus récente. Seule la dernière eSIM du numéro peut être modifiée : utilisez son id, ou commandez une nouvelle eSIM avec Commander une eSIM.
ESIM_TOPUP_PENDINGUne autre recharge pour cette eSIM est encore en cours de paiement. Toujours retryable: true. Réessayez dans quelques minutes, ou reprenez l'achat précédent avec sa Idempotency-Key.
ESIM_SUBSCRIPTION_CONFLICTL'abonnement que vous payez pour le compte ne peut pas être débité pour des eSIM pour le moment. Si l'erreur indique retryable: true, réessayez dans quelques minutes.

Autorisation

Authorizationstring · headerrequis

Api-Key ak_live_…

Paramètres de chemin

idstringrequis

The eSIM id returned by Order eSIM (eso-*).

En-têtes

Idempotency-Keystringrequis

Required. 8 to 100 letters, digits, - or _, for example a UUID. Send a new key for each top-up and the same key when you retry it: Allo does not charge you twice.

Corps

codestringrequis

A top-up code from Get eSIM offer.

Réponses

201Top-up bought
dataobject
4 champs
esim_idstring

The eSIM id (eso-*).

codestring

The top-up you bought.

data_mbinteger<int64>

Mobile data the top-up adds, in MB.

statusenum<string>

PENDING: charged, the data is added once the payment is confirmed. ACTIVE: a retry with the same Idempotency-Key of a top-up already added.

PENDINGACTIVE

400Validation error: MISSING_FIELD (code), INVALID_ESIM_TOPUP, IDEMPOTENCY_KEY_REQUIRED (no Idempotency-Key header) or INVALID_IDEMPOTENCY_KEY.
errorobject
401
402Billing error, nothing is left pending. PARTNER_CREDIT_INSUFFICIENT: your prepaid credit does not cover the charge and your billing account has no card on file. ESIM_PAYMENT_FAILED: your card was declined or requires 3D Secure, and the attempt was cancelled: retry with another payment method or after topping up your credit.
errorobject
403The API key lacks the PARTNER scope.
errorobject
404No eSIM with this id was ordered on an account your API key provisioned (PARTNER_ESIM_NOT_FOUND), or the account the eSIM belongs to is deactivated (PARTNER_ACCOUNT_NOT_FOUND).
errorobject
409The eSIM is still provisioning (ESIM_NOT_READY), was deleted or is not the number's latest eSIM (ESIM_NOT_ACTIVE), another top-up for it is still being paid (ESIM_TOPUP_PENDING, retryable), the Idempotency-Key was already used for another top-up on this eSIM (IDEMPOTENCY_KEY_ALREADY_USED), or the subscription you pay for the account cannot be charged for eSIMs right now (ESIM_SUBSCRIPTION_CONFLICT).
errorobject
429
500The eSIM's data cannot be changed right now (ESIM_UNAVAILABLE). The message gives the reason.
errorobject