Payment Links-API

🤖 Erklären mit KI

Die Payment Links-API hilft Unternehmen dabei, Zahlungslinks mit spezifischen Details wie Zahlungsbetrag, Währung, Beschreibung und Kundeninformationen zu generieren und anzupassen.

Sobald der Zahlungslink generiert wurde, können Unternehmen ihn per E-Mail, über soziale Medien oder andere Kommunikationskanäle mit ihren Kunden teilen. Wenn der Kunde auf den Link klickt, wird er auf eine Zahlungsverarbeitungsseite weitergeleitet, auf der er seine Zahlungsdaten eingeben und die Transaktion abschließen kann.

Einen neuen Zahlungslink erstellen¶

POST /v1/payment-links/

Dieser Endpunkt ermöglicht es Ihnen, einen oder mehrere Zahlungslinks für bestimmte Kunden oder ohne Kundendetails zu erstellen.

Query-Parameter:

Felder im Request-Body:

Felder im Kundenobjekt (falls neue Kunden angegeben werden):

*Zusammen erforderlich, wenn id oder customer nicht angegeben werden

Anfrage (Einzelnen Zahlungslink erstellen):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Premium Subscription 1 Year",
           "amount": 99.99,
           "currency": "USD",
           "customers": []
         }'

Anfrage (Zahlungslink für mehrere Kunden erstellen):

curl -X POST 'https://api.4geeks.io/v1/payment-links/?test=false' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "description": "Product License",
           "amount": 49.99,
           "currency": "USD",
           "customers": [
             {
               "id": "550e8400-e29b-41d4-a716-446655440000"
             },
             {
               "first_name": "John",
               "last_name": "Doe",
               "email": "john.doe@example.com"
             }
           ]
         }'

Antwort (201 Created - Einzelner Link):

{
    "code": 201,
    "title": "Zahlungslink erstellt",
    "content": "Der Zahlungslink wurde korrekt erstellt.",
    "type": "success",
    "data": {
        "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
        "link": "http://localhost:4200/pl/b3196f0b-bcba-46bc-b833-0bc845007c89"
    }
}

Antwort (201 Created - Mehrere Links):

{
    "code": 201,
    "title": "Zahlungslink erstellt",
    "content": "Die Zahlungslinks wurden korrekt erstellt.",
    "type": "success",
    "data": [
        {
            "id": "987f6543-b21c-43d8-a567-123456789abc",
            "customer": "550e8400-e29b-41d4-a716-446655440000",
            "customer_name": "Alex Miller",
            "link": "http://localhost:3000/pl/987f6543-b21c-43d8-a567-123456789abc"
        },
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "customer": "650f9501-f40c-52e5-c827-557766551111",
            "customer_name": "John Doe",
            "link": "http://localhost:3000/pl/aabbccdd-1122-3344-5566-77889900aabb"
        }
    ]
}

Alle Zahlungslinks abrufen¶

GET /v1/payment-links/

Dieser Endpunkt ruft alle Zahlungslinks für Ihr Konto mit Unterstützung für Pagination ab.

Query-Parameter:

Anfrage:

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

Anfrage (Mit Pagination):

curl -X GET 'https://api.4geeks.io/v1/payment-links/?page=1' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
    "count": 15,
    "next": "https://api.4geeks.io/v1/payment-links/?page=2",
    "previous": null,
    "results": [
        {
            "id": "aabbccdd-1122-3344-5566-77889900aabb",
            "description": "Premium Subscription 1 Year",
            "amount": "99.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-04T10:30:00Z"
        },
        {
            "id": "ccddee11-2233-4455-6677-88990011aabb",
            "description": "Product License",
            "amount": "49.99",
            "currency": "USD",
            "payment_link": true,
            "active": true,
            "recurring": false,
            "next_date_of_payment": null,
            "status": "pending",
            "test": false,
            "created_on": "2025-12-03T15:45:00Z"
        }
    ]
}

Einen bestimmten Zahlungslink abrufen¶

GET /v1/payment-links/{id}/

Dieser Endpunkt ruft die vollständigen Details eines bestimmten Zahlungslinks anhand seiner ID ab.

Pfad-Parameter:

Anfrage:

curl -X GET 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
    "id": "b3196f0b-bcba-46bc-b833-0bc845007c89",
    "description": "Premium Subscription 1 Year",
    "amount": 99.99,
    "currency": "USD",
    "payment_link": true,
    "active": true,
    "recurring": false,
    "next_date_of_payment": null,
    "status": "pending",
    "test": false,
    "created_on": "2025-12-04T22:56:39.903352Z",
    "payment_logs": []
}

Einen Zahlungslink aktualisieren¶

PUT /v1/payment-links/{id}/

Aktualisiert einen bestehenden Zahlungslink mit neuen Details.

Pfad-Parameter:

Felder im Request-Body (alle optional):

Gültige Statuswerte:

• pending - Wartet auf Zahlung
• paid - Zahlung abgeschlossen
• paid_period - Zeitraumzahlung abgeschlossen
• pending_period - Zeitraumzahlung ausstehend
• cancelled / canceled - Link storniert
• defaulter - Zahlung überfällig
• active - Link ist aktiv
• inactive - Link ist inaktiv

Anfrage:

curl -X PUT 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:' \
     -H 'Content-Type: application/json' \
     -d '{
           "active": true,
           "status": "pending",
           "recurring": false,
           "customer": null
         }'

Antwort (200 OK):

{
    "code": 200,
    "title": "Zahlungslink aktualisiert",
    "content": "Der Zahlungslink wurde erfolgreich aktualisiert.",
    "type": "success"
}

Antwort (400 Bad Request - Ungültiger Status):

{
    "code": 400,
    "title": "Ungültiger Status",
    "content": "Der angegebene Zustand ist ungültig.",
    "type": "error"
}

Einen Zahlungslink löschen¶

DELETE /v1/payment-links/{id}/

Löscht einen bestimmten Zahlungslink.

Pfad-Parameter:

Anfrage:

curl -X DELETE 'https://api.4geeks.io/v1/payment-links/aabbccdd-1122-3344-5566-77889900aabb/' \
     -u 'sk_test_51O62xYzAbcDef123:'

Antwort (200 OK):

{
    "code": 200,
    "title": "Gelöscht",
    "content": "Der Zahlungslink wurde erfolgreich entfernt.",
    "type": "success"
}

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 Zahlungslinks sind:

400 Bad Request¶

Tritt auf, wenn die Anfrage fehlerhaft ist oder erforderliche Felder fehlen.

Szenarien:

Beispiel für eine Fehlerantwort:

{
    "code": 406,
    "title": "Fehlende Daten",
    "content": "Sie haben keine Beschreibung für die Zahlung angegeben.",
    "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 Parameter -u 'sk_test_...: oder den Header Authorization: Basic hinzugefügt haben
• Stellen Sie sicher, dass Ihr API-Key korrekt und aktiv ist
• Testen Sie mit Postman unter Verwendung von Basic Auth

404 Not Found¶

Der angeforderte Zahlungslink existiert nicht.

Beispiel:

{
    "code": 404,
    "title": "Zahlungslink nicht gefunden",
    "content": "Der Zahlungslink konnte nicht gefunden werden, bitte überprüfen Sie die ID.",
    "type": "danger"
}

Lösung:

• Überprüfen Sie, ob die Zahlungslink-ID existiert
• Verwenden Sie den List-Endpunkt, um die korrekte Zahlungslink-ID zu finden
• Stellen Sie sicher, dass der Zahlungslink zu Ihrem Entwicklerkonto gehört

Wichtige Hinweise¶

Best Practices¶

1. Klare Beschreibungen hinzufügen – Helfen Sie Kunden zu verstehen, wofür sie bezahlen
2. Richtige Währung verwenden – Passen Sie diese an Ihre Geschäftsregion und die Kundenerwartungen an
3. Mindestbeträge festlegen – Stellen Sie sicher, dass die Beträge mindestens dem Gegenwert von $1,00 USD entsprechen
4. Kunden zuweisen – Verknüpfen Sie Zahlungen mit Kundendatensätzen für eine bessere Nachverfolgung
5. Zahlungsprotokolle überwachen – Verwenden Sie Zahlungsprotokolle, um Transaktionen abzugleichen
6. Status angemessen aktualisieren – Halten Sie den Status des Zahlungslinks mit dem tatsächlichen Zahlungszustand synchron
7. Vor der Produktion testen – Verwenden Sie den Testmodus mit Test-API-Keys zur Validierung

Fehlerbehebung¶

Problem: „Der Betrag liegt unter dem Minimum“¶

Ursache: Der Zahlungsbetrag ist geringer als der Gegenwert von USD $1,00
Lösung:

• Erhöhen Sie das Feld amount auf mindestens 1.00
• Überprüfen Sie die Währungsumrechnung, wenn Sie eine andere Währung als USD verwenden

Problem: „Sie haben keine Beschreibung angegeben“¶

Ursache: Erforderliches Feld description fehlt
Lösung:

• Geben Sie einen klaren, beschreibenden Titel für die Zahlung an
• Beispiel: “Premium-Abonnement”, “Produktlizenz”, “Servicegebühr”

Problem: „Sie haben weder Vorname, Nachname und E-Mail noch eine Kunden-ID angegeben“¶

Ursache: Unvollständige Kundeninformationen
Lösung:

• Geben Sie entweder eine bestehende Kunden-ID im Array customers an
• Oder geben Sie vollständige Kundendetails an: first_name, last_name und email

Problem: „Der angegebene Zustand ist ungültig“¶

Ursache: Ungültiger Statuswert angegeben
Lösung:

• Verwenden Sie nur gültige Statuswerte: pending, paid, paid_period, pending_period, cancelled, canceled, defaulter, active, inactive
• Lesen Sie in der Dokumentation nach, wie Status definiert sind

Problem: „Zahlungslink nicht gefunden“¶

Ursache: Die Zahlungslink-ID existiert nicht oder gehört zu einem anderen Entwicklerkonto
Lösung:

• Überprüfen Sie die Zahlungslink-ID über den List-Endpunkt
• Stellen Sie sicher, dass Sie den richtigen API-Key verwenden
• Überprüfen Sie, ob der Zahlungslink nicht gelöscht wurde

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