Einheitliche HTTP-/JSON-Schnittstelle, SHA-256-Signaturprüfung, asynchrone Benachrichtigungen und aktive Auftragsabfrage. Dieses Dokument behandelt die Signaturregeln, sämtliche Schnittstellenfelder und Anfragebeispiele.
India Payme bietet Händlern zwei zentrale Transaktionsfunktionen: Payin (Inkasso) – Zahlungseinzug vom Endkunden im Auftrag des Händlers; Payout (Auszahlung) – Auszahlung an ein angegebenes Konto im Auftrag des Händlers. Alle Schnittstellen sind POST + JSON und erfordern zwingend eine API-Signatur. Nach der Verarbeitung informiert die Plattform den Händler per asynchroner Benachrichtigung; zusätzlich ist eine aktive Auftragsabfrage möglich.
| Funktion | Methode | Pfad |
|---|---|---|
| Payin-Auftrag erstellen | POST | /transaction/payin/v1/apply |
| Payin-Auftrag abfragen | POST | /transaction/payin/v1/query |
| Payout-Auftrag erstellen | POST | /transaction/payout/v1/apply |
| Payout-Auftrag abfragen | POST | /transaction/payout/v1/query |
| Kontostandsabfrage | POST | /transaction/payout/v1/balance |
Basis-URL (die produktive Gateway-Domain wird nach Kontoeröffnung von der Plattform bereitgestellt):
Melden Sie sich im Händler-Backend → App-Schlüssel an. Jede Anwendung besitzt ein Zugangsdaten-Paar: appKey und appSecret. Dabei ist der appKey identisch mit dem Header appId; appSecret ist der Signaturschlüssel, der ausschließlich lokal zur Signaturberechnung dient und nicht übertragen wird.
Alle Anfragen müssen folgende HTTP-Header enthalten, Content-Type ist application/json:
| Header | Pflicht | Beschreibung |
|---|---|---|
appId | Ja | Händler-App-ID (entspricht appKey) |
timestamp | Ja | Unix-Zeitstempel in Millisekunden |
nonce | Ja | Zufallszeichenfolge, ≥10 Zeichen, einmalig verwendbar |
sign | Ja | Signatur nach den Regeln im nächsten Abschnitt |
Der Signaturalgorithmus ist reines SHA-256 (Hexadezimal, Kleinschreibung), kein HMAC. Der appSecret wird direkt an das Ende der zu signierenden Zeichenfolge angehängt, bevor SHA-256 berechnet wird. Schritte:
appId, timestamp, nonce" zu einer Map zusammenführen (sign selbst ist nicht enthalten);key1=value1&key2=value2… zusammensetzen;appSecret anhängen (ohne Trennzeichen) und aus der gesamten Zeichenfolge den SHA-256-Hex-Wert (Kleinschreibung) bilden – das Ergebnis ist sign.Gültigkeit und Replay-Schutz:
|Serverzeit − timestamp| ≤ 30s, andernfalls wird timestamp has expired zurückgegeben. Bitte sorgen Sie für eine Zeitsynchronisation (NTP) zwischen Client und Gateway.nonce has been used (Fehlercode 900).Node.js-Signaturbeispiel:
POST /transaction/payin/v1/apply — Erstellt einen Zahlungseingangs-Auftrag und liefert den Bezahlseiten-Link payUrl zurück, über den der Nutzer die Zahlung abschließt.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
merchantOrderNo | string | Ja | Händler-Auftragsnummer, muss eindeutig sein |
amount | number | Ja | Auftragsbetrag, Dezimalzahl (z. B. 100.02) |
name | string | Ja | Name des Nutzers. Nur lateinische Buchstaben, ≥3 Zeichen, Leerzeichen erlaubt, keine Symbole oder Ziffern |
phone | string | Ja | Telefonnummer |
email | string | Ja | E-Mail-Adresse |
currency | string | Ja | Währung: INR / PKR / USDT / BDT |
product | string | Ja | Produktcode, von der Plattform gemäß Vertrag vergeben |
notifyUrl | string | Nein | Adresse für asynchrone Benachrichtigung; ohne Angabe wird die Standardadresse des Händlers verwendet |
returnUrl | string | Nein | Weiterleitungsseite nach erfolgreicher Zahlung |
payType | string | Nein | Direktzahlung per Wallet: JAZZCASH / EASYPAISA / BKASH / NAGAD |
Leiten Sie den Nutzer nach Erhalt der payUrl zur Zahlung weiter; das endgültige Ergebnis wird ausschließlich über die asynchrone Benachrichtigung bestätigt.
POST /transaction/payout/v1/apply — Löst eine Auszahlung an ein angegebenes Konto aus. Asynchrone Verarbeitung: Die Schnittstelle prüft und sperrt zunächst das Konto, danach erfolgt die Kanalzuordnung asynchron. Die Rückgabe lautet in der Regel payStatus=0 (Annahme erfolgreich); maßgeblich ist die spätere Abfrage oder Benachrichtigung.
| Feld | Typ | Pflicht | Beschreibung |
|---|---|---|---|
merchantOrderNo | string | Ja | Händler-Auftragsnummer |
amount | number | Ja | Auszahlungsbetrag, mindestens 100.00 |
accountName | string | Ja | Name des Zahlungsempfängers. Nur lateinische Buchstaben, ≥3 Zeichen, Leerzeichen erlaubt |
account | string | Ja | Empfängerkonto |
phone | string | Ja | Telefonnummer |
email | string | Ja | E-Mail-Adresse |
currency | string | Ja | Währung: INR / PKR / USDT / BDT |
bizCode | string | Ja | Auszahlungsart: IMPS / UPI / BANK / JAZZCASH / EASYPAISA / BKASH / NAGAD / ECARD |
payCode | string | Ja | Zahlungsart: CARD / WALLET / NBK / ITT / VC |
branchCode | string | Ja | Clearing-Code: für Indien IFSC; für Pakistan bankcode; für Bangladesch gemäß bizCode |
product | string | Ja | Zahlungsprodukt-Code, von der Plattform vergeben |
bankName | string | Nein | Name der Bank |
swiftCode | string | Nein | SWIFT-Code (für grenzüberschreitende ITT-Überweisungen) |
Payin: POST /transaction/payin/v1/query, Payout: POST /transaction/payout/v1/query. Übergeben Sie merchantOrderNo oder orderNo zur Auftragsidentifikation. Rate-Limit: 5 Anfragen/Sekunde.
POST /transaction/payout/v1/balance — Fragt den Kontostand des Händlers ab. Rate-Limit: 5 Anfragen/Sekunde.
Sobald ein Auftrag einen Endstatus erreicht, benachrichtigt die Plattform per POST (JSON) die notifyUrl des Händlers (ohne Angabe wird die Standardadresse verwendet) und sendet dabei dieselben Signatur-Header (appId/timestamp/nonce/sign) mit. Der Händler sollte mit dem eigenen appSecret nach denselben Regeln die Signatur neu berechnen und vergleichen, um die Echtheit der Benachrichtigung zu prüfen.
Die Payin-Benachrichtigung enthält: merchantOrderNo, orderNo, currency, product, amount, realAmount, status (bei erfolgreichem Zahlungseingang "1"). Die Payout-Benachrichtigung enthält zusätzlich utr (Bank-Transaktionsnummer) und statusDes (Statusbeschreibung); status ist "1" für erfolgreich / "2" für fehlgeschlagen.
Der Händler muss den reinen Text OK oder success zurückgeben (Groß-/Kleinschreibung unerheblich). Andernfalls stellt die Plattform die Zustellung in eine Wiederholungswarteschlange: maximal 5 Versuche, mit steigenden Intervallen in Minuten (1 / 2 / 5 / 10 / 30 / 60 / 120). Die Händlerschnittstelle muss daher idempotent sein (dieselbe orderNo kann mehrfach benachrichtigt werden).
Für die Integration maßgeblich sind die folgenden öffentlichen Statuswerte (die interne Zustandsmaschine ist feingranularer und wird nicht direkt offengelegt):
| Szenario | Feld | Werte |
|---|---|---|
| Rückgabe bei Auftragsannahme | payStatus | 0 erstellt / 1 erfolgreich / 2 fehlgeschlagen / 3 storniert |
| Payin-Abfrage | payStatus | 0 in Bearbeitung / 1 bezahlt / -1 storniert |
| Payout-Abfrage | payStatus | 0 ausstehend / 1 ausgezahlt / -1 storniert |
| Asynchrone Benachrichtigung | status | Payin erfolgreich "1"; Payout "1" erfolgreich / "2" fehlgeschlagen |
Ist code != 0 in der Antwort, ist die Anfrage fehlgeschlagen; msg enthält den Hinweistext. Häufige Fehlercodes:
| code | Beschreibung |
|---|---|
0 | Erfolgreich |
400 | Parameterfehler / Signaturprüfung fehlgeschlagen (Sign invalid) |
900 | Doppelte Anfrage / nonce erneut verwendet |
10000 / 10001 | App existiert nicht / App nicht verfügbar |
10002 | Währung nicht unterstützt |
10003 / 10007 | Händler nicht verfügbar / Händlerkonto nicht verfügbar |
10004 | Produkt nicht freigeschaltet oder Vertrag abgelaufen |
10005 / 10009 | Kein Kanal verfügbar / Kanal vorübergehend nicht verfügbar |
10008 | Kontoguthaben unzureichend |
10010 | IP nicht in der Whitelist |
10011 / 10012 | Produkt ungültig / Zahlungsart ungültig |
10020 | Händler-Auftragsnummer bereits vergeben |
30001 / 30002 | Auftragsnummer fehlerhaft / Währung fehlerhaft oder Konto nicht aktiviert |
Am Beispiel eines Payin-Auftrags:
timestamp (Millisekunden) und nonce (Zufallsstring ≥10 Zeichen) generieren.sign gemäß „Signaturregeln" berechnen.POST /transaction/payin/v1/apply aufrufen.code==0 aus data.payUrl die Zahlung des Nutzers einleiten.OK zurückgeben.Hinweis: Die in diesem Dokument genannten Schnittstellenpfade, Felder und Statuscodes entsprechen der Produktivimplementierung; die produktive Gateway-Domain, verfügbare product-Produktcodes sowie die IP-Whitelist-Richtlinie werden nach Kontoeröffnung von der Plattform bereitgestellt.
Eröffnen Sie Ihr Konto online und erhalten Sie Testzugangsdaten sowie Produktcodes – nach erfolgreichem Sandbox-Test wechseln Sie mit einem Klick in die Produktivumgebung.