Ricarica automatica
Updated:
Ricarica automatica del credito: quando il credito scende al di sotto di una soglia, l’importo configurato viene addebitato sul metodo di pagamento salvato. Disponibile in Solo API v2 — non esiste una versione v1 corrispondente.
Richiede che la funzionalità sia abilitata sul server. Quando è disattivata, entrambi gli endpoint restituiscono Auto top-up is not available.
Risultato finale:
Questa richiesta restituisce la configurazione attuale della ricarica automatica e il risultato dell’ultimo evento di attivazione.
Parametri del percorso
Nome | Valore | Descrizione |
|---|---|---|
Autorizzazione |
| La tua chiave API personale (Come ottenere) |
Esempio
https://proxy-seller.com/personal/api/v2/fj4948ffhg58gh843gh/balance/autotopup/getRisposta
{
"status": "success",
"data": {
"configured": true,
"enabled": true,
"state": "ACTIVE",
"threshold": 10,
"amount": 25,
"subscriptionId": "sub_01hx9k2m4p",
"paymentMethod": {
"id": "sub_01hx9k2m4p",
"status": "active",
"paymentMethod": "card",
"brand": "visa",
"last4": "1234",
"exp": "05/2027"
},
"dailyCountCap": 5,
"monthlyAmountCap": 500,
"failCount": 0,
"lastAttemptAt": "2026-08-14T09:12:44.000+00:00",
"lastEvent": {
"status": "SUCCEEDED",
"amount": 25,
"at": "2026-08-14T09:12:46.000+00:00",
"reason": null
}
},
"errors": []
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Auto top-up is not available",
"code": 49,
"customData": null
}
]
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Error api key",
"code": 503,
"customData": null
},
{
"message": "IP not allowed",
"code": 503,
"customData": null
},
{
"message": "Request limit reached",
"code": 503,
"customData": null
}
]
}Modifica impostazioni
Risultato finale:
Questa richiesta aggiorna la configurazione della ricarica automatica. Aggiornamento parziale: qualsiasi campo omesso mantiene il valore memorizzato, quindi per modificare solo la soglia è sufficiente inviare threshold.
Parametri del percorso
Nome | Valore | Descrizione |
|---|---|---|
Autorizzazione |
| La tua chiave API personale (Come ottenere) |
Corpo della richiesta
Nome | Tipo | Descrizione |
|---|---|---|
abilitato | Booleano | Attiva o disattiva la ricarica automatica |
soglia | Numero | Addebitare quando il saldo scende al di sotto di questo valore. Minimo |
quantità | Numero | Importo di una singola ricarica. Minimo |
subscriptionId | Stringa | Metodo di pagamento da addebitare, tratto da |
dailyCountCap | Numero | Il proprio limite più rigoroso di ricariche ogni 24 ore. Minimo |
monthlyAmountCap | Numero | Il proprio limite dell’importo totale ogni 30 giorni. Deve essere maggiore o uguale a |
Esempio
https://proxy-seller.com/personal/api/v2/fj4948ffhg58gh843gh/balance/autotopup/setRisposta
{
"status": "success",
"data": {
"configured": true,
"enabled": true,
"state": "ACTIVE",
"threshold": 10,
"amount": 25,
"subscriptionId": "sub_01hx9k2m4p",
"paymentMethod": {
"id": "sub_01hx9k2m4p",
"status": "active",
"paymentMethod": "card",
"brand": "visa",
"last4": "4242",
"exp": "05/2027"
},
"dailyCountCap": 5,
"monthlyAmountCap": 500,
"failCount": 0,
"lastAttemptAt": null,
"lastEvent": {
"status": "SETTINGS_SAVED",
"amount": null,
"at": "2026-08-14T10:03:11.000+00:00",
"reason": "enabled: false -> true"
}
},
"errors": []
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Top-up amount must be #min_amount# or more",
"code": 51,
"customData": {
"minAmount": 5
}
}
]
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Top-up amount must cover the threshold, otherwise it will trigger again",
"code": 52,
"customData": null
}
]
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Auto top-up requires a saved payment method",
"code": 53,
"customData": null
}
]
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Your saved card has expired — update it to enable auto top-up",
"code": 56,
"customData": null
}
]
}{
"status": "error",
"data": null,
"errors": [
{
"message": "Threshold must be #min_threshold# or more",
"code": 50,
"customData": {
"minThreshold": 1
}
}
]
}La convalida viene eseguita rispetto al unito risultato, non solo in base alla richiesta. Invio
thresholddi per sé viene comunque rifiutato se il contenuto memorizzatoamountrisulta inferiore alla nuova soglia.La pausa che segue una serie di cariche fallite viene annullata solo quando
enabled: trueviene inviato esplicitamente. La modifica di altri campi in una configurazione messa in pausa mantiene attiva la pausa.I limiti di lunghezza validi si applicano anche quando l’utente non ne ha impostato alcuno:
5ricariche ogni 24 ore e500per ogni periodo di 30 giorni.