Rückerstattungs-API

🤖 Erklären mit KI

Die Rückerstattungs-API ist ein Tool, mit dem Unternehmen Rückerstattungen für Transaktionen einleiten und verwalten können, die über ihr Zahlungsabwicklungssystem getätigt wurden. Wenn ein Kunde eine Rückerstattung beantragt, ermöglicht die Rückerstattungs-API dem Unternehmen, die Rückerstattung schnell und einfach zu bearbeiten, ohne den Rückerstattungsprozess manuell handhaben zu müssen.

Diese API übernimmt die Kommunikation mit dem Zahlungsabwickler, um sicherzustellen, dass die Rückerstattung korrekt und in Übereinstimmung mit allen relevanten Vorschriften verarbeitet wird.

Eine Rückerstattung erstellen¶

Erstellt eine Rückerstattung für eine bestimmte Belastung. Sie können optional einen Betrag für Teilrückerstattungen angeben. Wenn kein Betrag angegeben wird, wird der volle Belastungsbetrag zurückerstattet.

Felder:

Anfrage (Vollständige Rückerstattung):

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"
         }'

Anfrage (Teilrückerstattung):

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"
         }'

Antwort (Vollständige Rückerstattung - 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"
}

Antwort (Teilrückerstattung - 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"
}

Eine Rückerstattung abrufen¶

Dieser Endpunkt gibt ein spezifisches Rückerstattungsobjekt anhand seiner ID zurück.

Pfad-Parameter:

Anfrage:

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

Antwort (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"
}

Rückerstattungen auflisten¶

Dieser Endpunkt gibt alle Rückerstattungen für Ihr Konto zurück. Sie können mit Query-Parametern nach charge_id filtern.

Query-Parameter:

Anfrage (Alle Rückerstattungen auflisten):

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

Anfrage (Nach Belastungs-ID filtern):

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

Antwort (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"
    }
]

Fehlerbehandlung¶

Die API gibt Standard-HTTP-Statuscodes zurück, um den Erfolg oder Misserfolg einer Anfrage anzuzeigen. Nachfolgend sind häufige Fehler aufgeführt, die spezifisch für Rückerstattungen sind:

400 Bad Request¶

Tritt auf, wenn die Anfrage fehlende erforderliche Felder oder ungültige Daten enthält.

Szenarien:

Beispiel für eine Fehlerantwort:

{
    "code": 400,
    "title": "Rückerstattungsfehler",
    "content": "Der angegebene Betrag ist größer als der Betrag der Zahlung.",
    "type": "danger"
}

401 Unauthorized¶

Authentifizierung fehlgeschlagen. Der API-Key ist ungültig, fehlt oder ist fehlerhaft.

Beispiel:

{
    "detail": "Authentifizierungsdaten wurden nicht bereitgestellt."
}

Lösung: - Überprüfen Sie, ob Sie den Header Authorization: Basic <base64_key> hinzugefügt oder -u in cURL verwendet haben - Stellen Sie sicher, dass Ihr API-Key korrekt und aktiv ist - Testen Sie mit Postman, um den Fehler einzugrenzen

404 Not Found¶

Die angeforderte Belastung oder Rückerstattung existiert nicht.

Beispiel:

{
    "detail": "Rückerstattung existiert nicht in Ihrer Liste."
}

Lösung: - Überprüfen Sie, ob die charge_id oder refund_id existiert - Überprüfen Sie, ob Sie das richtige ID-Format verwenden (ohne Präfixe wie ch_ oder re_) - Stellen Sie sicher, dass die Belastung zu Ihrem Entwicklerkonto gehört

409 Conflict¶

Die Belastung wurde bereits an Ihr Konto ausgezahlt und kann nicht mehr zurückerstattet werden.

Beispiel:

{
    "code": 400,
    "title": "Statusfehler der Belastung",
    "content": "Die angeforderte Belastung wurde bereits an Ihr Konto ausgezahlt.",
    "type": "danger"
}

Lösung: - Rückerstattungen sind nur möglich, bevor Belastungen auf Ihr Bankkonto überwiesen werden - Kontaktieren Sie den Support, wenn Sie Hilfe bei bereits ausgezahlten Belastungen benötigen

Rückerstattungsgründe¶

Beim Erstellen einer Rückerstattung müssen Sie einen der folgenden Gründe angeben:

Best Practices¶

1. Geben Sie immer einen Grund an – Dies hilft bei der Nachverfolgung und Streitbeilegung
2. Nutzen Sie Teilrückerstattungen, wenn möglich – Wenn Sie eine Korrektur vornehmen, nutzen Sie Teilrückerstattungen anstelle von vollständigen Rückerstattungen
3. Bearbeiten Sie Rückerstattungen zeitnah – Rückerstattungen sind erfolgreicher, wenn sie kurz nach der Belastung eingeleitet werden
4. Prüfen Sie vor der Rückerstattung – Stellen Sie sicher, dass die Belastung zu Ihrem Konto gehört und noch nicht ausgezahlt wurde
5. Überwachen Sie den Rückerstattungsstatus – Nutzen Sie den GET-Endpunkt, um den Abschluss der Rückerstattung zu verifizieren
6. Fehler elegant behandeln – Implementieren Sie eine angemessene Fehlerbehandlung für gängige Szenarien

Fehlerbehebung¶

Problem: „Charge object doesn’t exist“¶

Ursache: Die angegebene charge_id stimmt mit keiner Belastung im System überein
Lösung: - Überprüfen Sie das Format der charge_id (entfernen Sie das Präfix ‘ch_’, falls vorhanden) - Bestätigen Sie, dass die Belastung zu Ihrem Entwicklerkonto gehört - Nutzen Sie die Zahlungs-API, um alle Belastungen aufzulisten und die korrekte ID zu finden

Problem: „Charge requested is already refunded“¶

Ursache: Für diese Belastung wurde bereits eine vollständige Rückerstattung verarbeitet
Lösung: - Prüfen Sie mit GET /v1/refunds/?charge_id=xxx, ob bereits eine Rückerstattung erstellt wurde - Wenn Sie zusätzliche Rückerstattungen benötigen, verarbeiten Sie diese vor der ersten vollständigen Rückerstattung

Problem: „The charge requested is already paid to your account“¶

Ursache: Die Belastung wurde bereits auf Ihr Bankkonto überwiesen
Lösung: - Rückerstattungen können nur vor der Auszahlung verarbeitet werden - Kontaktieren Sie den Support für Belastungen, die bereits ausgezahlt wurden

FAQ¶

F: Kann ich einen Teilbetrag einer Belastung zurückerstatten?
A: Ja, geben Sie den Parameter amount in der Anfrage an. Der Belastungsbetrag wird entsprechend reduziert.

F: Was passiert mit meinem Guthaben bei einer Rückerstattung?
A: Ihr verfügbares Guthaben wird angepasst. Bei vollständigen Rückerstattungen wird die gesamte Belastung storniert. Bei Teilrückerstattungen spiegelt Ihr Guthaben den reduzierten Betrag wider.

F: Kann ich eine Rückerstattung stornieren?
A: Nein, einmal eingeleitete Rückerstattungen können nicht storniert werden. Planen Sie sorgfältig, bevor Sie eine Rückerstattung erstellen.

F: Was ist der Unterschied zwischen vollständigen und Teilrückerstattungen?
A: Vollständige Rückerstattungen machen den gesamten Belastungsbetrag rückgängig und markieren ihn als zurückerstattet. Teilrückerstattungen reduzieren den Belastungsbetrag und markieren ihn als teilweise zurückerstattet.

F: Kann ich eine Belastung mehrmals zurückerstatten?
A: Ja, Sie können mehrere Teilrückerstattungen vornehmen, solange der zurückerstattete Gesamtbetrag den ursprünglichen Belastungsbetrag nicht übersteigt.

• Noch Fragen? Get support.
• Check out the changelog.