API Rimborsi

🤖 Spiega con l'intelligenza artificiale

L’API Rimborsi è uno strumento che consente alle aziende di avviare e gestire rimborsi per le transazioni effettuate tramite il proprio sistema di elaborazione dei pagamenti. Quando un cliente richiede un rimborso, l’API Rimborsi consente all’azienda di elaborare il rimborso in modo rapido e semplice, senza dover gestire manualmente il processo.

Questa API gestisce la comunicazione con l’elaboratore dei pagamenti per garantire che il rimborso sia elaborato correttamente e in conformità con le normative pertinenti.

Creare un rimborso¶

Endpoint

POST /v1/refunds/

Crea un rimborso per un addebito specifico. È possibile specificare facoltativamente un importo per rimborsi parziali. Se non viene fornito alcun importo, verrà rimborsato l’intero importo dell’addebito.

Requisiti

L’addebito deve esistere nel sistema
L’addebito non deve essere già stato rimborsato interamente
Per addebiti reali (live): l’addebito non deve essere già stato pagato sul tuo account

Campi:

Parametro	Descrizione	Tipo	Obbligatorio
charge_id	ID dell’addebito	string	true
amount	Importo da rimborsare (rimborso parziale). Se omesso, viene elaborato il rimborso totale	decimal	false
reason	`duplicate`, `fraudulent` o `requested_by_customer`	string	true
test	Indica se il rimborso è in modalità test (true per test, false per produzione).	boolean	false

Richiesta (Rimborso Totale):

curl -X POST 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
           "reason": "requested_by_customer"
         }'

Richiesta (Rimborso Parziale):

curl -X POST 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
           "amount": 10.50,
           "reason": "requested_by_customer"
         }'

Risposta (Rimborso Totale - 201 Created):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "100.00",
    "currency": "usd",
    "reason": "requested_by_customer",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T15:30:00Z"
}

Risposta (Rimborso Parziale - 201 Created):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "10.50",
    "currency": "usd",
    "reason": "requested_by_customer",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T15:30:00Z"
}

Ottenere un rimborso¶

Endpoint

GET /v1/refunds/{refund_id}/

Questo endpoint restituisce uno specifico oggetto rimborso tramite il suo ID.

Parametri di percorso:

Parametro	Descrizione	Tipo	Obbligatorio
refund_id	ID del rimborso (senza il prefisso ‘re_’)	string	true

Richiesta:

curl -X GET 'https://api.4geeks.io/v1/refunds/1BiPhgCqnAMsdzqhvCTntF7aD/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

{
    "id": "1BiPhgCqnAMsdzqhvCTntF7aD",
    "provider_refund_id": "re_1ABC123XYZ456",
    "charge_id": "1BSt6hCqnAMAMqhvMGiBxOWe",
    "amount": "10.00",
    "currency": "usd",
    "reason": "duplicate",
    "status": "succeeded",
    "test": true,
    "created_at": "2025-12-04T14:20:00Z"
}

Elencare i rimborsi¶

Endpoint

GET /v1/refunds/

Questo endpoint restituisce tutti i rimborsi per il tuo account. Puoi filtrare per charge_id utilizzando i parametri di query.

Parametri di query:

Parametro	Descrizione	Tipo	Obbligatorio
charge_id	Filtra i rimborsi per un ID addebito specifico (opzionale)	string	false
test	Indica se filtrare i rimborsi in modalità test	boolean	false

Richiesta (Elenca tutti i rimborsi):

curl -X GET 'https://api.4geeks.io/v1/refunds/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Richiesta (Filtra per ID addebito):

curl -X GET 'https://api.4geeks.io/v1/refunds/?charge_id=1BSt6hCqnAMAMqhvMGiBxOWe' \
     -u 'sk_test_51O62xYzAbcDef123:'

Risposta (200 OK):

[
    {
        "id": "1BiOrQCqNertMqhvvUMhJajE",
        "provider_refund_id": "re_1XYZ123ABC456",
        "charge_id": "1BSt5sCqnAMAMqhvd871C1Vl",
        "amount": "10.00",
        "currency": "usd",
        "reason": "duplicate",
        "status": "succeeded",
        "test": true,
        "created_at": "2025-12-03T10:15:00Z"
    },
    {
        "id": "1BiPDoCqnNerAMqhvSzxyFXl2",
        "provider_refund_id": "re_2ABC456XYZ789",
        "charge_id": "1BSt5sCqnAMAMqhvd871C1Vl",
        "amount": "40.00",
        "currency": "usd",
        "reason": "fraudulent",
        "status": "succeeded",
        "test": true,
        "created_at": "2025-12-02T16:45:00Z"
    }
]

Gestione degli errori¶

L’API restituisce codici di stato HTTP standard per indicare il successo o il fallimento di una richiesta. Di seguito sono riportati gli errori comuni specifici per i rimborsi:

400 Bad Request¶

Si verifica quando la richiesta manca di campi obbligatori o contiene dati non validi.

Scenari:

Scenario	Messaggio di errore	Soluzione
charge_id mancante	`"Charge object doesn't exist."`	Verifica che il charge_id sia corretto ed esista
Rimborso parziale superiore all’importo dell’addebito	`"The amount provided is greater than the amount of the payment."`	Riduci l’importo del rimborso affinché sia inferiore o uguale all’addebito
Addebito già rimborsato interamente	`"Charge requested is already refunded"`	Controlla se l’addebito è già stato rimborsato
Campo reason mancante	`"reason field is required"`	Includi una motivazione valida: `duplicate`, `fraudulent`, o `requested_by_customer`

Esempio di risposta di errore:

{
    "code": 400,
    "title": "Errore rimborso",
    "content": "L'importo fornito è superiore all'importo del pagamento.",
    "type": "danger"
}

401 Unauthorized¶

Autenticazione fallita. La chiave API non è valida, è mancante o è formattata male.

Esempio:

{
    "detail": "Le credenziali di autenticazione non sono state fornite."
}

Soluzione: - Verifica di aver incluso l’header Authorization: Basic <base64_key> o di aver usato -u in cURL - Assicurati che la tua chiave API sia corretta e attiva - Testa con Postman per il debug

404 Not Found¶

L’addebito o il rimborso richiesto non esiste.

Esempio:

{
    "detail": "Il rimborso non esiste nella tua lista."
}

Soluzione: - Verifica che il charge_id o il refund_id esista - Controlla di utilizzare il formato ID corretto (senza prefissi come ch_ o re_) - Assicurati che l’addebito appartenga al tuo account sviluppatore

409 Conflict¶

L’addebito è già stato pagato sul tuo account e non può essere rimborsato.

Esempio:

{
    "code": 400,
    "title": "Errore stato addebito",
    "content": "L'addebito richiesto è già stato pagato sul tuo account.",
    "type": "danger"
}

Soluzione: - I rimborsi sono possibili solo prima che gli addebiti vengano depositati sul tuo conto bancario - Contatta il supporto se hai bisogno di assistenza con addebiti già pagati

Motivi del rimborso¶

Quando crei un rimborso, devi specificare uno dei seguenti motivi:

Motivo	Caso d’uso
`duplicate`	L’addebito era duplicato o elaborato due volte
`fraudulent`	L’addebito era fraudolento o non autorizzato
`requested_by_customer`	Il cliente ha richiesto un rimborso

Migliori pratiche¶

Specifica sempre un motivo - Questo aiuta con il tracciamento e la risoluzione delle controversie
Usa rimborsi parziali quando possibile - Se stai effettuando una correzione, usa rimborsi parziali invece di rimborsi totali
Elabora i rimborsi tempestivamente - È più probabile che i rimborsi vadano a buon fine se avviati subito dopo l’addebito
Verifica prima di rimborsare - Controlla che l’addebito appartenga al tuo account e non sia stato già pagato
Monitora lo stato del rimborso - Usa l’endpoint GET per verificare il completamento del rimborso
Gestisci gli errori in modo appropriato - Implementa una corretta gestione degli errori per gli scenari comuni

Risoluzione dei problemi¶

Problema: “Charge object doesn’t exist”¶

Causa: Il charge_id fornito non corrisponde ad alcun addebito nel sistema
Soluzione: - Verifica il formato del charge_id (rimuovi il prefisso ‘ch_’ se incluso) - Conferma che l’addebito appartenga al tuo account sviluppatore - Usa l’API Pagamenti per elencare tutti gli addebiti e trovare l’ID corretto

Problema: “Charge requested is already refunded”¶

Causa: Un rimborso totale è già stato elaborato per questo addebito
Soluzione: - Controlla se un rimborso è già stato creato utilizzando GET /v1/refunds/?charge_id=xxx - Se hai bisogno di ulteriori rimborsi, elaborali prima del rimborso totale iniziale

Problema: “The charge requested is already paid to your account”¶

Causa: L’addebito è stato depositato sul tuo conto bancario
Soluzione: - I rimborsi possono essere elaborati solo prima del pagamento (payout) - Contatta il supporto per addebiti che sono già stati pagati

FAQ¶

D: Posso rimborsare un importo parziale di un addebito?
A: Sì, specifica il parametro amount nella richiesta. L’importo dell’addebito verrà ridotto di conseguenza.

D: Cosa succede al mio saldo quando effettuo un rimborso?
A: Il tuo saldo disponibile viene aggiornato. Per i rimborsi totali, l’intero addebito viene annullato. Per i rimborsi parziali, il tuo saldo rifletterà l’importo ridotto.

D: Posso annullare un rimborso?
A: No, una volta avviati, i rimborsi non possono essere annullati. Pianifica attentamente prima di creare un rimborso.

D: Qual è la differenza tra rimborsi totali e parziali?
A: I rimborsi totali annullano l’intero importo dell’addebito e lo contrassegnano come rimborsato. I rimborsi parziali riducono l’importo dell’addebito e lo contrassegnano come parzialmente rimborsato.

D: Posso rimborsare un addebito più volte?
A: Sì, puoi emettere più rimborsi parziali a condizione che l’importo totale rimborsato non superi l’importo dell’addebito originale.

Hai ancora domande? Richiedi supporto..
Check out the changelog.