Zum Inhalt springen

Localpayment für Entwickler

Entwickeln Sie entlang der lokalen Details.

Finden Sie die API-Leitfäden, Länderanforderungen, Testtools und Implementierungsbeispiele hinter jedem unterstützten Zahlungsfluss.

Zur DokumentationQuickstart starten
  • REST + JSON
  • HMAC-signierte Webhooks
  • Stage-Sandbox
  • Öffentlicher MCP-Server

Das Wichtigste für Entwickler

Dokumentation

Direkt zu dem, was Sie brauchen

Direktlinks zu docs.localpayment.com: Leitfäden, API-Referenz und Tools.

Ihre ersten Aufrufe

Authentifizieren, kassieren, bestätigen

Drei Schritte decken den Kernablauf ab: Token abrufen, Einzahlung anlegen und den signierten Webhook prüfen, der sie bestätigt. Dasselbe Request-, Status- und Webhook-Modell gilt für alle Länder und Zahlungsmethoden.

  • Tokens laufen nach 5 Minuten ab – erneuern Sie sie mit POST /api/token/refresh/
  • Senden Sie bei jeder Transaktion Ihre eigene eindeutige externalId
  • Der finale Status kommt per Webhook, signiert mit HMAC-SHA256
API-Referenz öffnen
# 1) Access-Token abrufen (Stage · 5 Minuten gültig)
ACCESS_TOKEN=$(curl -s -X POST https://api.stage.localpayment.com/api/token/ \
  -H "Content-Type: application/json" \
  -d "{\"username\": \"$LP_API_USER\", \"password\": \"$LP_API_PASSWORD\"}" \
  | jq -r .access)

# 2) Pix-Einzahlung anlegen (Beispiel, fiktive Werte)
curl -X POST https://api.stage.localpayment.com/api/payin/ \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentMethod": { "type": "BankTransfer", "code": "1314", "flow": "DIRECT" },
    "externalId": "7c1e2f7a-0000-4000-8000-000000000001",
    "country": "BRA",
    "currency": "USD",
    "amount": 100,
    "accountNumber": "<your-account-number>",
    "conceptCode": "0003",
    "merchant": { "type": "COMPANY", "name": "Nortia Commerce Ltda" },
    "payer": {
      "type": "INDIVIDUAL",
      "name": "Maria",
      "lastname": "Silva",
      "document": { "type": "CPF", "id": "000.000.000-00" }
    }
  }'

API-Design

Vorhersehbar by Design

Konventionen, die über Produkte und Länder hinweg gleich bleiben – damit auch Ihr Integrationscode stabil bleibt.

  • REST und JSON

    Ressourcenorientierte URLs, Standard-HTTP-Verben und -Statuscodes, JSON-Bodies. Länder werden mit ISO-3-Codes wie BRA oder MEX angegeben.

  • Kurzlebige Bearer-Tokens

    POST /api/token/ liefert einen 5 Minuten gültigen Access-Token und einen 24 Stunden gültigen Refresh-Token, gesendet als Authorization: Bearer.

  • Ihre ID und unsere

    Jede Transaktion trägt Ihre externalId, wir liefern unsere internalId zurück. Mit beiden können Sie den Status abfragen oder abgleichen.

  • Schutz vor Duplikaten

    Eine wiederverwendete externalId liefert 409 Conflict statt einer zweiten Transaktion – so wiederholen Sie einen Request nach Timeout gefahrlos.

  • Statuscodes für klare Entscheidungen

    Jede Antwort enthält ein status-Objekt mit code, description und detail sowie ein errors-Array. Die Code-Familien zeigen den nächsten Schritt.

  • Rate Limits mit Backoff

    Zu viele Requests liefern 429. Wiederholen Sie mit exponentiellem Backoff und Circuit Breaker – ebenso bei 5xx-Antworten und Code 800.

Fehlerbehandlung

Statuscode-Familien im Überblick

Jede Antwort enthält status.code. Die erste Ziffer zeigt, ob Sie warten, korrigieren, wiederholen oder rückabwickeln sollten.

  • 1xx

    Bedeutung
    Ausstehend
    Beispiele
    100 INPROGRESS
    Was zu tun ist
    Auf den Webhook warten oder den Status abfragen

  • 2xx

    Bedeutung
    Erfolg
    Beispiele
    200 COMPLETED
    Was zu tun ist
    Bestellung ausführen und Ihr Ledger aktualisieren

  • 3xx

    Bedeutung
    Validierung
    Beispiele
    300 abgelehnt (ungültiger Parameter) · 301 für das Land nicht autorisiert
    Was zu tun ist
    Request korrigieren – nicht unverändert wiederholen

  • 7xx

    Bedeutung
    Geschäftsregeln
    Beispiele
    701 ungültiges Konto · 702 unzureichende Deckung
    Was zu tun ist
    Klare Meldung anzeigen oder Ihr Operations-Team alarmieren

  • 8xx

    Bedeutung
    Anbieter oder System
    Beispiele
    800 wiederholbarer Fehler
    Was zu tun ist
    Mit exponentiellem Backoff wiederholen

  • 9xx

    Bedeutung
    Rückabwicklungen
    Beispiele
    902 erstattet · 904 Abo nach fehlgeschlagenen Versuchen gekündigt · 906 Chargeback
    Was zu tun ist
    Leistung rückabwickeln und Ihr Ledger aktualisieren

Verwendete HTTP-Status: 200, 201, 400, 401, 403, 404, 409, 429, 500, 502 und 503. Die Codetabellen je Transaktionstyp finden Sie in der Referenz der Dokumentation.

Integrationsablauf

Vom ersten Aufruf bis zum Go-live

Der Großteil der Arbeit findet auf Stage statt. Der Produktionszugang folgt nach einem Sicherheits-Review und der Unternehmensverifizierung.

  1. 01

    Stage-Zugangsdaten erhalten

    Stage-Zugangsdaten werden zu Beginn der Partnerschaft ausgestellt. Hinterlegen Sie Ihre Server-IPs im Business Portal.

    Stage

  2. 02

    Entwickeln und testen

    Integrieren Sie Einzahlungen, Auszahlungen oder virtuelle Konten, verarbeiten Sie Webhooks und testen Sie Fehlerszenarien mit Testdaten.

    Stage

  3. 03

    Sicherheits-Review und KYB

    Wir prüfen Ihre Integration und schließen die Unternehmensverifizierung (KYB) ab, bevor wir Produktionszugangsdaten ausstellen.

    Compliance

  4. 04

    Live gehen und expandieren

    Wechseln Sie auf Produktionszugangsdaten und -IPs. Fügen Sie Länder und Methoden per Konfiguration hinzu, ohne Neuintegration.

    Produktion

KI-Entwicklertools

Lassen Sie Ihren KI-Assistenten die Doku lesen

Die Dokumentation von Localpayment ist für KI-gestützte Entwicklungstools gemacht – mit einem MCP-Server, sofort einsetzbaren Prompts und strukturiertem Zugriff, der für KI-Systeme ausgelegt ist.

  • MCP-Server unter docs.localpayment.com/mcp – ohne Authentifizierung
  • Ein llms.txt-Index und eine Markdown-Version jeder Doku-Seite
  • Eine Prompt-Bibliothek sowie Integrations- und QA-Agenten für gängige Agent-Frameworks
  • „Ask AI“ direkt in der Dokumentation
KI-Tools entdecken
{
  "mcpServers": {
    "localpayment-docs": {
      "url": "https://docs.localpayment.com/mcp"
    }
  }
}

Sicherheit

Standardmäßig sicher, ab dem ersten Request

Kontrollen, die in API und Business Portal eingebaut sind – nicht nachträglich angeflanscht.

  • Verschlüsselung bei Übertragung und Speicherung

    TLS 1.2+ bei der Übertragung und AES-256 im Ruhezustand, mit Schlüsselrotation über AWS KMS.

  • Nur Server-zu-Server

    Aufrufe laufen per HTTPS von Ihrem Backend. Legen Sie Zugangsdaten oder Tokens niemals in einem Browser oder einer mobilen App offen.

  • IP-Allowlisting

    Nur die Server-IPs, die Sie im Business Portal freigeben, können die API aufrufen – für Stage und Produktion.

  • Signierte Webhooks

    Jede Benachrichtigung trägt eine HMAC-SHA256-Signatur, sodass Sie alles ablehnen können, was nicht von uns stammt.

  • Auszahlungen mit Vier-Augen-Prinzip

    Verlangen Sie eine zweite Freigabe, bevor eine Auszahlung Ihr Konto verlässt – per API oder im Portal.

  • MFA und rollenbasierter Zugriff

    Business-Portal-Nutzer melden sich mit Multi-Faktor-Authentifizierung an und erhalten nur die Rechte, die ihre Rolle benötigt.

FAQ für Entwickler

Gibt es ein SDK?

Offizielle Server-SDKs gibt es nicht: Die API ist schlichtes REST und JSON, jeder HTTP-Client funktioniert. Für Kartenformulare tokenisiert das JavaScript-SDK Smart Fields die Kartendaten in gehosteten Feldern und verkleinert so Ihren PCI-Scope.

Wie erhalte ich Sandbox-Zugangsdaten?

Stage-Zugangsdaten werden zu Beginn der Partnerschaft ausgestellt. Stellen Sie uns Ihr Projekt über das Kontaktformular vor, und unser Team begleitet Sie durch das Onboarding.

Welche Base-URLs verwende ich?

Stage: https://api.stage.localpayment.com. Produktion: https://api.v3.localpayment.com. Jede Umgebung hat eigene Zugangsdaten.

Wie lange dauert eine Integration?

Teams gehen in der Regel innerhalb weniger Wochen live. Nach der Integration kommen neue Märkte per Konfiguration hinzu, ohne Neuintegration.

Wie werden Wiederholungen und Duplikate behandelt?

Senden Sie pro Transaktion eine eindeutige externalId. Wiederholen Sie mit derselben externalId, erhalten Sie 409 Conflict statt eines Duplikats. Wiederholen Sie 429, 5xx und Code 800 mit exponentiellem Backoff.

Wo sehe ich den Servicestatus?

Auf status.localpayment.com – mit Einzahlungs-, Auszahlungs- und Authentifizierungsdiensten, lokalen Schienen und Incident-Historie. Hilfe erhalten Sie unter support@localpayment.com; der Support ist rund um die Uhr erreichbar.

Entwickler-Leitfäden

Bereit zum Entwickeln?

Sprechen Sie mit unserem Team, um die Partnerschaft zu starten und Stage-Zugangsdaten zu erhalten, oder erkunden Sie gleich die Dokumentation.

Zur DokumentationStage-Zugang anfragen

Wie können wir helfen?

Ihr Exemplar herunterladen

Hinterlassen Sie Ihre Daten und erhalten Sie sofort die vollständige Ausgabe.