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.

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 ist: 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 führt Sie durch den gesamten Prozess der Zahlungs-API-Integration. Sie lernen die Authentifizierungseinrichtung, Zahlungsabwicklung, Rückerstattungsverwaltung, Webhook-Handhabung, PCI DSS Compliance, Best Practices für Sicherheit und Strategien für die Bereitstellung in der Produktion kennen. Am Ende werden Sie eine produktionsreife Zahlungsintegration haben.

Hinweis: Dieser Leitfaden behandelt allgemeine Muster der Zahlungs-API-Integration, die für iPay und ähnliche Zahlungsdienstleister gelten. Spezifische Endpunkt-URLs und Authentifizierungsdetails können variieren – beziehen Sie sich für Implementierungsdetails immer auf 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

Ü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

Erste Schritte: Authentifizierung einrichten

Schritt 1: iPay Konto erstellen

Vor dem Zugriff auf die API:

1. Besuchen Sie die iPay Händlerregistrierung
2. Schließen Sie die Unternehmensverifizierung (KYB) ab
3. Erforderliche Dokumente einreichen:

• Handelsregistereintragung
• Bankkontodaten
• Amtlicher Ausweis

1. Warten Sie auf die Genehmigung (1-3 Werktage)

Schritt 2: API-Zugangsdaten erhalten

Generieren Sie API-Zugangsdaten:

1. Melden Sie sich beim iPay Händler-Dashboard an
2. Navigieren Sie zu Einstellungen > API-Schlüssel
3. Neuen API-Schlüssel erstellen
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: Verwenden Sie separate Schlüssel für Sandbox und Produktion.

Schritt 3: Authentifizierungsmethoden verstehen

iPay unterstützt mehrere Authentifizierungsmethoden:

Schritt 4: Authentifizierte API-Aufrufe tätigen

Wiederverwendbaren API-Client erstellen:

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)}`;
}

// Verwendung
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;
};

// Verwendung
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

Kreditkartendetails tokenisieren

Karte sicher für zukünftige Verwendung speichern:

const tokenizeCard = async (cardData) => {
  // NIEMALS rohe Kartendaten an Ihren Server senden
  // Verwenden Sie stattdessen clientseitige Tokenisierung

  // 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; // Senden Sie token.id an Ihren Server
};

// Serverseitig: Token verwenden, um eine Zahlungsmethode zu erstellen
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 implementieren:

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: 3DS-Herausforderung bearbeiten
// Verwenden Sie iPay.js oder das mobile SDK, um die Authentifizierungsherausforderung anzuzeigen

Rückerstattungsverwaltung

Vollständige Rückerstattung bearbeiten

Gesamte Zahlung zurückerstatten:

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;
};

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

Teilweise Rückerstattung bearbeiten

Teil der Zahlung zurückerstatten:

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;
};

// Verwendung – 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

Kundenverwaltung

Einen Kunden erstellen

Kunden für wiederkehrende Zahlungen speichern:

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;
};

// Verwendung
const customer = await createCustomer({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-0123',
  internalId: 'USR-12345',
  tier: 'premium'
});

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

Zahlungsmethode einem Kunden zuordnen

Karte für zukünftige Verwendung speichern:

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

  return response;
};

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

Zahlungsmethoden eines Kunden auflisten

Gespeicherte Karten abrufen:

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

// Verwendung
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

Webhook-Endpunkte einrichten:

1. Melden Sie sich beim iPay Dashboard an
2. Navigieren Sie zu Entwickler > Webhooks
3. Klicken Sie auf Endpunkt hinzufügen
4. Geben Sie Ihre HTTPS-URL ein
5. Wählen Sie die zu abonnierenden Ereignisse aus

Webhook-Ereignisse

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());

  // An entsprechenden Handler weiterleiten
  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:

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 der Verarbeitung von Live-Zahlungen:

• [ ] PCI DSS Selbstbewertungsfragebogen ausfüllen
• [ ] HTTPS für alle Endpunkte verwenden
• [ ] API-Schlüssel in sicherer Geheimnisverwaltung speichern
• [ ] Webhook-Signaturverifizierung implementieren
• [ ] Idempotenz für alle Zahlungsvorgänge hinzufügen
• [ ] Umfassende Protokollierung einrichten (keine sensiblen Daten)
• [ ] Betrugserkennungsregeln konfigurieren
• [ ] Rückerstattungs- und Streitbeilegungsabläufe testen
• [ ] Runbook für Zahlungsausfälle erstellen
• [ ] Überwachung und Alarmierung einrichten
• [ ] Backup-Zahlungsdienstleister implementieren

Praxisbeispiele

E-Commerce Checkout

Ein Online-Händler integriert Zahlungen:

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

SaaS-Abonnementabrechnung

Ein Softwareunternehmen automatisiert die Abrechnung:

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

Marktplatz-Treuhandservice

Eine Plattform wickelt Zahlungen mehrerer Parteien ab:

• 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 Erkenntnisse:

• Niemals rohe Kartendaten verarbeiten – verwenden Sie Tokenisierung
• Idempotenz für alle Zahlungsvorgänge implementieren
• Webhook-Signaturen verifizieren, um Betrug zu verhindern
• PCI DSS Anforderungen erfüllen
• Gründlich im Sandbox-Modus testen, bevor Sie in Produktion gehen
• Apidog optimiert API-Tests und Teamzusammenarbeit

FAQ-Bereich

Wie authentifiziere ich mich bei der iPay API?

Verwenden Sie die 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 Sie müssen PCI DSS konform sein. Verwenden Sie Tokenisierung, um Karten sicher im iPay-Tresor zu speichern.

Wie gehe ich mit fehlgeschlagenen Zahlungen um?

Implementieren Sie eine Wiederholungslogik mit exponentiellem Backoff, benachrichtigen Sie Kunden und bieten Sie alternative Zahlungsmethoden an.

Was ist Idempotenz und warum ist sie wichtig?

Idempotenz stellt sicher, dass doppelte Anfragen mit demselben Schlüssel dasselbe Ergebnis liefern und so doppelte Abbuchungen verhindert werden.

Wie teste ich Zahlungen, ohne Karten zu belasten?

Verwenden Sie den Sandbox-Modus mit Testkartennummern, die in der iPay-Dokumentation bereitgestellt werden.

Was sind Webhook-Signaturen?

Kryptografische Signaturen, die überprüfen, ob Webhooks von iPay und nicht von einem böswilligen Akteur stammen.