Buy eSIM top-up
curl --request POST \
--url https://api.withallo.com/v2/api/partner/esims/{id}/topups \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"code": "TOPUP_5GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload = { "code": "TOPUP_5GB" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({code: 'TOPUP_5GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/topups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/esims/{id}/topups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'TOPUP_5GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload := strings.NewReader("{\n \"code\": \"TOPUP_5GB\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"TOPUP_5GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"TOPUP_5GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"code": "TOPUP_5GB",
"data_mb": 5120,
"status": "PENDING"
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}eSIM
Acheter une recharge de données eSIM
Buys a data top-up for an eSIM. The top-up is charged once: Allo draws on your prepaid credit first, then charges your card on file. Its data is added to the eSIM once the payment is confirmed, for the current calendar month (Paris time). Unused data lapses at the end of that month. The Idempotency-Key header is required: send a new UUID for each top-up and the same one when you retry it. A card that requires 3D Secure is refused with ESIM_PAYMENT_FAILED and the attempt is cancelled. Only the number’s latest eSIM can be topped up. Requires the PARTNER scope.
POST
/
v2
/
api
/
partner
/
esims
/
{id}
/
topups
Buy eSIM top-up
curl --request POST \
--url https://api.withallo.com/v2/api/partner/esims/{id}/topups \
--header 'Authorization: <api-key>' \
--header 'Content-Type: application/json' \
--header 'Idempotency-Key: <idempotency-key>' \
--data '
{
"code": "TOPUP_5GB"
}
'import requests
url = "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload = { "code": "TOPUP_5GB" }
headers = {
"Idempotency-Key": "<idempotency-key>",
"Authorization": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {
'Idempotency-Key': '<idempotency-key>',
Authorization: '<api-key>',
'Content-Type': 'application/json'
},
body: JSON.stringify({code: 'TOPUP_5GB'})
};
fetch('https://api.withallo.com/v2/api/partner/esims/{id}/topups', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.withallo.com/v2/api/partner/esims/{id}/topups",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'code' => 'TOPUP_5GB'
]),
CURLOPT_HTTPHEADER => [
"Authorization: <api-key>",
"Content-Type: application/json",
"Idempotency-Key: <idempotency-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.withallo.com/v2/api/partner/esims/{id}/topups"
payload := strings.NewReader("{\n \"code\": \"TOPUP_5GB\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Idempotency-Key", "<idempotency-key>")
req.Header.Add("Authorization", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
.header("Idempotency-Key", "<idempotency-key>")
.header("Authorization", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"code\": \"TOPUP_5GB\"\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.withallo.com/v2/api/partner/esims/{id}/topups")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '<idempotency-key>'
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"code\": \"TOPUP_5GB\"\n}"
response = http.request(request)
puts response.read_body{
"data": {
"esim_id": "eso-2F6A1C9D4B7E8A0F3D5C6B9A1E2F4D7C8B0A3E61",
"code": "TOPUP_5GB",
"data_mb": 5120,
"status": "PENDING"
}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {}
}{
"error": {
"type": "<string>",
"code": "<string>",
"message": "<string>",
"retryable": true,
"request_id": "<string>",
"retry_after_seconds": 123
}
}{
"error": {}
}Scope requis :
PARTNERpartner.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-Keyest obligatoire : voir Nouvelles tentatives. codeest requis : untop_ups[].coderenvoyé par Obtenir l’offre eSIM.- L’eSIM doit être
ACTIVE. Tant qu’elle est en cours de provisionnement, la requête échoue avecESIM_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) |
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 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 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êteIdempotency-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 avec400 INVALID_IDEMPOTENCY_KEY. - Une clé déjà utilisée sur cette eSIM pour une recharge avec un autre
codeéchoue avec409 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, 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. |
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. |
En-têtes
Cette page vous a-t-elle été utile ?