iPay API nutzen: Zahlungsabwicklung Integration 2026

TL;DR

Die iPay API ermöglicht Entwicklern die programmgesteuerte Integration von Zahlungsabwicklung, Rechnungsstellung und Finanztransaktionen. Sie nutzt OAuth 2.0 und API-Schlüssel-Authentifizierung, RESTful Endpunkte für Zahlungen, Rückerstattungen, Transaktionen und Abgleich, mit PCI DSS Compliance-Anforderungen und branchenüblichen Ratenbegrenzungen. Dieser Leitfaden behandelt die Authentifizierungseinrichtung, Zahlungsabwicklung, Webhook-Integration, Sicherheits-Compliance und Strategien für die Bereitstellung in der Produktion.

Teste Apidog noch heute

Einführung

Die digitale Zahlungsabwicklung wickelt weltweit jährlich über 8 Billionen US-Dollar ab. Für Entwickler, die E-Commerce-Plattformen, SaaS-Anwendungen oder Marktplatzlösungen entwickeln, ist die Integration einer Zahlungs-API nicht optional – sie ist unerlässlich, um Kundenzahlungen sicher und konform entgegenzunehmen.

Die Realität: Unternehmen verlieren 5-10 % ihres Umsatzes durch fehlgeschlagene Zahlungen, manuelle Abstimmung und Zahlungsbetrug. Eine solide Zahlungs-API-Integration automatisiert die Zahlungsabwicklung, reduziert Fehlschläge durch intelligente Wiederholungslogik, ermöglicht den automatischen Abgleich und implementiert Betrugserkennung.

Dieser Leitfaden zeigt konkrete Implementierungsschritte: Authentifizierung, Zahlungsabwicklung, Rückerstattungen, Webhook-Handling, PCI DSS Compliance, Sicherheits-Best-Practices und Go-Live-Strategien. Nach Abschluss hast du eine produktionsreife Zahlungsintegration.

💡 Apidog vereinfacht das Testen von Zahlungs-APIs. Teste Zahlungs-Endpunkte im Sandbox-Modus, validiere Webhook-Signaturen, prüfe Transaktionsantworten und debugge Integrationsprobleme zentral. Importiere API-Spezifikationen, modelliere Antworten und teile Testszenarien im Team.

Hinweis: Dieser Leitfaden behandelt allgemeine Muster der Zahlungs-API-Integration, die für iPay und ähnliche Zahlungsdienstleister gelten. Prüfe für konkrete Details immer die offizielle iPay-Dokumentation.

Was ist die iPay API?

Zahlungs-APIs wie iPay stellen RESTful Schnittstellen zur Verarbeitung von Finanztransaktionen bereit. Die API verarbeitet:

• Zahlungsautorisierung und -erfassung
• Rückerstattungen und Rückbuchungen
• Transaktionshistorie und Berichterstattung
• Kunden-Tokenisierung (Vault)
• Abonnement und wiederkehrende Abrechnung
• Rechnungsstellung und -verwaltung
• Abgleich und Abrechnung
• Betrugserkennung und -prävention

Hauptfunktionen

Funktion	Beschreibung
RESTful API	JSON-basierte Endpunkte
OAuth 2.0 + API-Schlüssel	Sichere Authentifizierung
Webhooks	Echtzeit-Zahlungsbenachrichtigungen
Tokenisierung	Sichere Kartenspeicherung
3D Secure	SCA-Compliance
PCI DSS	Level 1 Compliance erforderlich
Mehrwährung	Über 100 Währungen unterstützt
Betrugstools	Risikobewertung, Geschwindigkeitsprüfungen

Übersicht des Zahlungsflusses

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Customer  │───▶│   Merchant  │───▶│  Payment    │
│   (Browser) │    │   (Server)  │    │  Gateway    │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Enter Card     │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenize       │                    │
     │───────────────────▶│  3. Create Intent  │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Confirm Payment│
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Result         │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Receipt        │                    │
     │◀───────────────────│                    │

API-Umgebung

Umgebung	URL	Anwendungsfall
Sandbox	https://sandbox.ipay.com/api	Entwicklung, Tests
Produktion	https://api.ipay.com/api	Live-Transaktionen

Erste Schritte: Authentifizierung einrichten

Schritt 1: iPay Konto erstellen

1. Öffne die iPay Händlerregistrierung
2. Schließe die Unternehmensverifizierung (KYB) ab
3. Reiche folgende Dokumente ein:
   • Handelsregisterauszug
   • Bankkontodaten
   • Amtlicher Ausweis
4. Warte auf die Genehmigung (1–3 Werktage)

Schritt 2: API-Zugangsdaten erhalten

1. Logge dich ins iPay Händler-Dashboard ein
2. Navigiere zu Einstellungen → API-Schlüssel
3. Neuen API-Schlüssel generieren
4. Zugangsdaten sicher kopieren

# .env file (NIEMALS im Git speichern)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

Sicherheitshinweis: Nutze getrennte Schlüssel für Sandbox und Produktion.

Schritt 3: Authentifizierungsmethoden verstehen

Methode	Am besten geeignet für	Sicherheitsstufe
Basic Auth	Server-zu-Server	Hoch
OAuth 2.0	Multi-Tenant-Anwendungen	Höher
JWT	Microservices	Hoch

Schritt 4: Authentifizierte API-Aufrufe tätigen

Erstelle einen wiederverwendbaren API-Client:

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Basic authentication (Base64 encoded)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Error: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Beispielaufruf
const account = await ipayRequest('/account');
console.log(`Merchant: ${account.business_name}`);

Zahlungsabwicklung

Erstellen eines Zahlungs-Intents

Zahlung initialisieren:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // In der kleinsten Währungseinheit (Cents)
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'automatic' oder 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Beispiel
const payment = await createPayment({
  amount: 2999, // $29.99
  currency: 'USD',
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Order #ORD-001',
  orderId: 'ORD-001',
  statementDescriptor: 'MYCOMPANY INC'
});

console.log(`Zahlungsstatus: ${payment.status}`);
console.log(`Zahlungs-ID: ${payment.id}`);

Zahlungsstatus-Fluss

requires_payment_method → requires_confirmation → requires_action
                         → processing → requires_capture → succeeded
                                                        → failed
                                                        → canceled

Zahlungsmethoden

Methode	Typ	Anwendungsfall
card	Kredit-/Debitkarte	Standardzahlungen
bank_transfer	ACH, SEPA	Gebührengünstige Überweisungen
digital_wallet	Apple Pay, Google Pay	Mobiler Checkout
buy_now_pay_later	Klarna, Afterpay	Ratenzahlungen

Kreditkartendetails tokenisieren

Kartendaten niemals direkt an deinen Server senden! Tokenisierung immer clientseitig:

const tokenizeCard = async (cardData) => {
  // Clientseitig (Browser/Mobil)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // token.id an Server senden
};

// Serverseitig: Token verwenden
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

3D Secure Authentifizierung

SCA-Compliance:

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // Client-Geheimnis für 3DS zurückgeben
  });

  if (payment.status === 'requires_action') {
    // Client muss 3DS-Herausforderung abschließen
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Clientseitig: iPay.js oder SDK verwenden, um 3DS-Verifizierung durchzuführen

Rückerstattungsverwaltung

Vollständige Rückerstattung bearbeiten

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Beispiel
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Rückerstattungsstatus: ${refund.status}`);
console.log(`Rückerstattungs-ID: ${refund.id}`);

Teilweise Rückerstattung bearbeiten

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // In der kleinsten Währungseinheit
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Beispiel – Rückerstattung von 15,00 $ einer Zahlung von 29,99 $
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Erstattet: $${refund.amount / 100}`);

Gründe für Rückerstattung

Grundcode	Beschreibung
duplicate	Doppelte Abbuchung
fraudulent	Betrügerische Transaktion
requested_by_customer	Kundenanfrage
order_canceled	Stornierung der Bestellung
product_not_received	Artikel nicht geliefert
product_not_as_described	Artikel weicht von der Beschreibung ab

Kundenverwaltung

Einen Kunden erstellen

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Beispiel
const customer = await createCustomer({
  email: '[e-mail]',
  name: 'John Doe',
  phone: '[phone]',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Kunde erstellt: ${customer.id}`);

Zahlungsmethode einem Kunden zuordnen

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Beispiel
await attachPaymentMethod('pm_67890', 'cus_12345');

Zahlungsmethoden eines Kunden auflisten

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Beispiel
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} endend mit ${method.card.last4}`);
  console.log(`Gültig bis: ${method.card.exp_month}/${method.card.exp_year}`);
});

Webhooks

Webhooks konfigurieren

1. Im iPay Dashboard einloggen
2. Zu Entwickler → Webhooks navigieren
3. Endpunkt hinzufügen wählen
4. HTTPS-URL eintragen
5. Ereignisse auswählen

Webhook-Ereignisse

Ereignis	Auslöser
payment.succeeded	Zahlung abgeschlossen
payment.failed	Zahlung abgelehnt
payment.refunded	Rückerstattung bearbeitet
payment.disputed	Rückbuchung eingereicht
customer.created	Neuer Kunde
customer.subscription.updated	Abonnement geändert

Webhooks verarbeiten

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Webhook-Signatur verifizieren
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Ungültige Webhook-Signatur');
    return res.status(401).send('Unbefugt');
  }

  const event = JSON.parse(payload.toString());

  // Handler für relevante Events
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('Unbehandelter Ereignistyp:', event.type);
  }

  // Empfang bestätigen
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Zahlung erfolgreich: ${data.id}`);

  // Bestellstatus aktualisieren
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Bestätigungs-E-Mail senden
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Zahlung fehlgeschlagen: ${data.id} - ${data.failure_code}`);

  // Kunden benachrichtigen
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Wiederholungslogik oder Bestellung als fehlgeschlagen markieren
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}

Sicherheit und Compliance

PCI DSS Anforderungen

Zahlungsintegrationen müssen den PCI DSS Anforderungen entsprechen:

Anforderung	Implementierung
Sicheres Netzwerk	HTTPS, Firewalls, sichere Konfigurationen verwenden
Schutz von Kartendaten	Niemals CVV speichern, PAN verschlüsseln
Schwachstellenmanagement	Regelmäßige Sicherheitsupdates, Antivirus
Zugangskontrolle	Geringstes Privileg, MFA, eindeutige IDs
Überwachung	Protokollierung, Intrusion Detection
Sicherheitsrichtlinie	Dokumentierte Richtlinien, regelmäßige Schulungen

Best Practices für Sicherheit

// 1. Tokenisierung verwenden – NIEMALS rohe Kartendaten verarbeiten
const token = await tokenizeCard(cardData); // Clientseitig

// 2. Idempotenz für alle Zahlungsvorgänge implementieren
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Beträge serverseitig validieren
if (req.body.amount !== calculatedAmount) {
  throw new Error('Betragsabweichung – mögliche Manipulation');
}

// 4. Alle Zahlungsvorgänge protokollieren (ohne sensible Daten)
logger.info('Payment attempted', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // NIEMALS protokollieren: Kartennummern, CVV, vollständige Details der Zahlungsmethode
});

// 5. Umgebungsvariablen für Geheimnisse verwenden
const apiKey = process.env.IPAY_API_KEY; // Nicht fest codiert

// 6. Ratenbegrenzung für Zahlungs-Endpunkte implementieren
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 Zahlungsversuche pro Minute
});

Checkliste für die Produktionsbereitstellung

Vor dem Go-Live:

• [ ] PCI DSS Selbstbewertungsfragebogen ausfüllen
• [ ] HTTPS für alle Endpunkte verwenden
• [ ] API-Schlüssel sicher verwalten
• [ ] Webhook-Signaturverifizierung implementieren
• [ ] Idempotenz für alle Zahlungsvorgänge
• [ ] Protokollierung einrichten (keine sensiblen Daten)
• [ ] Betrugserkennungsregeln konfigurieren
• [ ] Rückerstattungen und Dispute testen
• [ ] Runbook für Zahlungsausfälle bereitstellen
• [ ] Überwachung und Alarmierung einrichten
• [ ] Backup-Zahlungsdienstleister konfigurieren

Praxisbeispiele

E-Commerce Checkout

• Herausforderung: Manuelle Zahlungsabwicklung, hohe Abbruchraten
• Lösung: Ein-Seiten-Checkout mit tokenisierten Karten
• Ergebnis: 35 % höhere Konversionsrate, Sofortzahlungen

SaaS-Abonnementabrechnung

• Herausforderung: Manuelle Rechnungserstellung und -erfassung
• Lösung: Wiederkehrende Zahlungen mit automatischer Wiederholung
• Ergebnis: 95 % pünktliche Zahlung, 80 % Einsparung bei der Verwaltungszeit

Marktplatz-Treuhandservice

• Herausforderung: Komplexe geteilte Zahlungen zwischen Anbietern
• Lösung: Zahlungs-Intents mit Übertragungsplanung
• Ergebnis: Automatisierte Auszahlungen an Anbieter, reduzierter Betrug

Fazit

Die Integration einer Zahlungs-API erfordert sorgfältige Beachtung von Sicherheit, Compliance und Fehlerbehandlung. Wichtige To-dos:

• Rohe Kartendaten niemals verarbeiten – immer Tokenisierung nutzen
• Idempotenz für alle Zahlungsvorgänge implementieren
• Webhook-Signaturen prüfen, um Betrug zu verhindern
• PCI DSS erfüllen
• Umfangreich im Sandbox-Modus testen vor Live-Schaltung
• Apidog optimiert API-Tests und Zusammenarbeit im Team

FAQ-Bereich

Wie authentifiziere ich mich bei der iPay API?

Verwende Basic-Authentifizierung mit API-Schlüssel und Geheimnis oder OAuth 2.0 für Multi-Tenant-Anwendungen.

Kann ich die Kreditkartendetails von Kunden speichern?

Ja, aber nur mit PCI DSS Compliance. Nutze Tokenisierung, um Karten sicher im iPay Vault zu speichern.

Wie gehe ich mit fehlgeschlagenen Zahlungen um?

Implementiere Wiederholungslogik mit exponentiellem Backoff, benachrichtige den Kunden und biete alternative Zahlungsmethoden an.

Was ist Idempotenz und warum ist sie wichtig?

Idempotenz garantiert, dass doppelte API-Anfragen mit gleichem Schlüssel das gleiche Ergebnis liefern – das verhindert doppelte Abbuchungen.

Wie teste ich Zahlungen, ohne Karten zu belasten?

Nutze den Sandbox-Modus mit Testkartennummern laut iPay-Dokumentation.

Was sind Webhook-Signaturen?

Kryptografische Signaturen, die sicherstellen, dass Webhooks authentisch von iPay stammen und nicht manipuliert wurden.