# 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`

<Note>
**Scope requis :** `PARTNER`
</Note>

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`](/fr/docs/webhooks/event-catalog#partneresimdata_low) à 80 % du quota et [`partner.esim.data_exhausted`](/fr/docs/webhooks/event-catalog#partneresimdata_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](#nouvelles-tentatives).
- `code` est requis : un `top_ups[].code` renvoyé par [Obtenir l'offre eSIM](/fr/docs/white-label/get-esim-offer).
- L'eSIM doit être `ACTIVE`. Tant qu'elle est en cours de provisionnement, la requête échoue avec `ESIM_NOT_READY`.

| `code` | Données ajoutées |
|--------|------------------|
| `TOPUP_5GB` | 5 Go (5120 Mo) |
| `TOPUP_10GB` | 10 Go (10240 Mo) |
| `TOPUP_20GB` | 20 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

| `status` | Signification |
|----------|---------------|
| `PENDING` | Allo a débité la recharge. Ses données sont ajoutées à l'eSIM une fois le paiement confirmé, et [Obtenir une eSIM](/fr/docs/white-label/get-esim) les affiche alors dans `data.allowance_mb`. |
| `ACTIVE` | Une 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](/fr/docs/white-label/get-esim-offer) 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é](/fr/docs/partner/get-credit), 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](/fr/help/support/partner-portal), 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

| Code | Signification |
|------|---------------|
| `ESIM_NOT_READY` | L'eSIM est encore en cours de provisionnement. Attendez [`partner.esim.ready`](/fr/docs/webhooks/event-catalog#partneresimready), puis réessayez. |
| `ESIM_NOT_ACTIVE` | L'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](/fr/docs/white-label/order-esim). |
| `ESIM_TOPUP_PENDING` | Une 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_CONFLICT` | L'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. |
