2Checkout API: Vollständige Integrationsanleitung für Zahlungsabwicklung (2026)

TL;DR

Die 2Checkout API (jetzt Verifone) ermöglicht Entwicklern die programmatische Abwicklung von Zahlungen, die Verwaltung von Abonnements und die Handhabung von E-Commerce-Transaktionen. Sie unterstützt RESTful-Endpunkte für Bestellungen, Kunden, Produkte und Webhooks mit JSON-basierter Authentifizierung mittels API-Schlüsseln. Dieser Leitfaden deckt alles ab, von der Ersteinrichtung bis zur erweiterten Webhook-Verarbeitung.

Einführung

Die Zahlungsabwicklung ist das Rückgrat jedes Online-Geschäfts. Wenn Sie es falsch machen, verlieren Sie Umsatz. Wenn Sie es richtig machen, erschließen Sie globale Märkte. Die 2Checkout API (kürzlich in Verifone umbenannt) wickelt Zahlungen für über 45.000 Händler weltweit ab und verarbeitet jährlich Transaktionen im Milliardenbereich.

Hier ist die Realität: 67 % der Käufer brechen den Einkaufswagen aufgrund von Zahlungshemmnissen ab. Eine solide Integration der Zahlungs-API wirkt sich direkt auf Ihr Geschäftsergebnis aus.

Dieser Leitfaden führt Sie durch den gesamten Integrationsprozess der 2Checkout API. Sie lernen Authentifizierung, Zahlungsabwicklung, Abonnementverwaltung, Webhook-Handhabung und Fehlerbehebung kennen. Am Ende verfügen Sie über eine produktionsreife Zahlungsintegration.

Was ist die 2Checkout API?

2Checkout (jetzt als Verifone Digital Commerce tätig) bietet eine RESTful API für die Zahlungsabwicklung und Abonnementverwaltung. Die API verarbeitet:

• Einmalige und wiederkehrende Zahlungen
• Kunden- und Produktverwaltung
• Verfolgung des Bestelllebenszyklus
• Bearbeitung von Rückerstattungen und Streitfällen
• Automatisierung von Steuern und Compliance
• Unterstützung mehrerer Währungen (über 100 Währungen)

Hauptfunktionen

Übersicht der API-Architektur

2Checkout verwendet eine versionierte REST-API-Struktur:

https://api.2checkout.com/1/
https://api.2checkout.com/2/

Version 2 ist die aktuell empfohlene Version mit verbesserter Abonnementverwaltung und Webhook-Verarbeitung.

Erste Schritte: Authentifizierung einrichten

Schritt 1: Ihr 2Checkout-Konto erstellen

Bevor Sie auf die API zugreifen können, benötigen Sie ein Händlerkonto:

1. Besuchen Sie die 2Checkout (Verifone) Registrierungsseite
2. Schließen Sie die Geschäftsverifizierung ab (erfordert Geschäftsunterlagen)
3. Warten Sie auf die Genehmigung (dauert in der Regel 24-48 Stunden)
4. Greifen Sie auf Ihr Control Panel zu, um API-Anmeldeinformationen abzurufen

Schritt 2: API-Schlüssel abrufen

Navigieren Sie in Ihrem Control Panel zu Integrationen > API-Schlüssel:

• Privater API-Schlüssel: Wird für die serverseitige Authentifizierung verwendet (diesen geheim halten)
• Öffentlicher API-Schlüssel: Wird für die clientseitige Tokenisierung verwendet (sicher zur Offenlegung)
• Webhook Secret: Wird zur Überprüfung von Webhook-Signaturen verwendet

Sicherheitshinweis: API-Schlüssel niemals in die Versionskontrolle übertragen. Verwenden Sie Umgebungsvariablen:

# .env-Datei
TWOCHECKOUT_PRIVATE_KEY="Ihr_privater_schlüssel_hier"
TWOCHECKOUT_PUBLIC_KEY="Ihr_öffentlicher_schlüssel_hier"
TWOCHECKOUT_WEBHOOK_SECRET="Ihr_webhook_geheimnis_hier"

Schritt 3: Sandbox vs. Produktion

2Checkout bietet separate Umgebungen:

Verwenden Sie während der Entwicklung Sandbox-Anmeldeinformationen. Wechseln Sie erst zu Produktionsschlüsseln, wenn Sie bereit sind, echte Zahlungen zu verarbeiten.

Schritt 4: Authentifizierungsmethoden

2Checkout unterstützt zwei Authentifizierungsansätze:

Methode 1: API-Schlüssel-Authentifizierung (Empfohlen)

Fügen Sie Ihren privaten Schlüssel in den Anfrage-Header ein:

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'GET',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'Content-Type': 'application/json',
    'Accept': 'application/json'
  }
});

Methode 2: HMAC-Signatur-Authentifizierung

Für erhöhte Sicherheit signieren Sie Anfragen mit HMAC-SHA256:

const crypto = require('crypto');

function generateSignature(payload, privateKey) {
  const hash = crypto
    .createHmac('sha256', privateKey)
    .update(JSON.stringify(payload))
    .digest('hex');
  return hash;
}

// Verwendung
const payload = { order_id: '12345', amount: 99.99 };
const signature = generateSignature(payload, privateKey);

const response = await fetch('https://api.2checkout.com/1/orders', {
  method: 'POST',
  headers: {
    'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
    'X-Signature': signature,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Zahlungsabwicklung: Kern-Endpunkte

Eine einmalige Bestellung erstellen

Verarbeiten Sie eine einzelne Zahlung mit dem /orders-Endpunkt:

const createOrder = async (customerData, productData) => {
  const payload = {
    currency: 'USD',
    customer: {
      email: customerData.email,
      first_name: customerData.firstName,
      last_name: customerData.lastName,
      phone: customerData.phone,
      billing_address: {
        address1: customerData.address,
        city: customerData.city,
        state: customerData.state,
        zip: customerData.zip,
        country: customerData.country
      }
    },
    items: [
      {
        name: productData.name,
        quantity: productData.quantity,
        price: productData.price,
        product_code: productData.sku
      }
    ],
    payment_method: {
      type: 'card',
      card_token: customerData.cardToken // Vom clientseitigen Tokenisierungsprozess
    }
  };

  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Erwartete Antwort

{
  "order_id": "ORD-2026-001234",
  "status": "approved",
  "amount": 99.99,
  "currency": "USD",
  "customer_id": "CUST-789456",
  "transaction_id": "TXN-9876543210",
  "created_at": "2026-03-20T10:30:00Z"
}

Umgang mit Zahlungsfehlern

Implementieren Sie immer eine ordnungsgemäße Fehlerbehandlung:

try {
  const result = await createOrder(customer, product);

  if (result.error) {
    // Spezifische Fehlercodes behandeln
    switch (result.error.code) {
      case 'CARD_DECLINED':
        // Kunden zur Eingabe einer anderen Karte auffordern
        break;
      case 'INSUFFICIENT_FUNDS':
        // Entsprechende Nachricht anzeigen
        break;
      case 'INVALID_CVV':
        // CVV-Neueingabe anfordern
        break;
      default:
        // Generischen Fehler protokollieren und anzeigen
        console.error('Zahlung fehlgeschlagen:', result.error);
    }
  }
} catch (error) {
  // Netzwerk- oder Serverfehler
  console.error('API-Anfrage fehlgeschlagen:', error);
}

Häufige Fehlercodes

Kundenverwaltung

Die Verwaltung von Kundendaten ist für Abo-Geschäfte und wiederkehrende Käufe unerlässlich. 2Checkout bietet eine vollständige Kunden-API.

Einen Kunden erstellen

const createCustomer = async (customerData) => {
  const payload = {
    email: customerData.email,
    first_name: customerData.firstName,
    last_name: customerData.lastName,
    phone: customerData.phone,
    company: customerData.company,
    billing_address: {
      address1: customerData.address,
      address2: customerData.address2 || '',
      city: customerData.city,
      state: customerData.state,
      zip: customerData.zip,
      country: customerData.country
    },
    shipping_address: customerData.shippingAddress || null,
    tax_exempt: false,
    language: 'de' // Angepasst für Deutschland
  };

  const response = await fetch('https://api.2checkout.com/1/customers', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Kundenantwort

{
  "customer_id": "CUST-2026-123456",
  "email": "john.doe@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "created_at": "2026-03-20T10:00:00Z",
  "updated_at": "2026-03-20T10:00:00Z",
  "payment_methods": [],
  "subscriptions": [],
  "order_history": []
}

Kundendaten abrufen

const getCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'GET',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      }
    }
  );

  return await response.json();
};

Kundeninformationen aktualisieren

const updateCustomer = async (customerId, updates) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(updates)
    }
  );

  return await response.json();
};

Einen Kunden löschen

const deleteCustomer = async (customerId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/customers/${customerId}`,
    {
      method: 'DELETE',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY
      }
    }
  );

  return response.status === 204; // Kein Inhalt bei Erfolg
};

Hinweis: Das Löschen eines Kunden mit aktiven Abonnements oder offenen Beträgen schlägt fehl. Kündigen Sie zuerst die Abonnements.

Erweiterte Integrationsmuster

Idempotenz für sichere Wiederholungsversuche

Zahlungs-APIs sollten idempotente Anfragen unterstützen, um doppelte Abbuchungen zu vermeiden:

const createIdempotentOrder = async (payload, idempotencyKey) => {
  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json',
      'X-Idempotency-Key': idempotencyKey // Eindeutig pro Bestellung
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

// Eindeutigen Schlüssel pro Bestellung generieren (in Ihrer Datenbank speichern)
const idempotencyKey = `order_${userId}_${Date.now()}`;

Wenn die Anfrage ein Timeout hatte, aber von 2Checkout verarbeitet wurde, liefert ein Wiederholungsversuch mit demselben Schlüssel das ursprüngliche Ergebnis zurück, anstatt zweimal abzurechnen.

Umgang mit 3D Secure 2.0 (EU-Compliance)

Für europäische Kunden ist die 3D Secure 2.0 Authentifizierung gemäß PSD2 obligatorisch:

const createOrderWith3DS = async (payload) => {
  const response = await fetch('https://api.2checkout.com/1/orders', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      ...payload,
      three_ds: {
        enabled: true,
        challenge_required: 'preferred', // oder 'mandatory' für die EU
        notification_url: 'https://your-site.com/3ds-callback'
      }
    })
  });

  const result = await response.json();

  // 3DS-Weiterleitung behandeln
  if (result.three_ds_redirect_url) {
    // Kunden zur Bankumleitung zur Authentifizierung
    res.redirect(result.three_ds_redirect_url);
  }

  return result;
};

Preise in mehreren Währungen

Preise in lokalen Währungen anzeigen, während die Abrechnung in Ihrer Basiswährung erfolgt:

const getLocalizedPrice = async (basePrice, targetCurrency) => {
  const response = await fetch(
    `https://api.2checkout.com/1/rates?from=USD&to=${targetCurrency}`,
    {
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY
      }
    }
  );

  const rates = await response.json();
  return basePrice * rates.rate;
};

// Verwendung
const eurPrice = await getLocalizedPrice(99.99, 'EUR');
console.log(`Preis: EUR ${eurPrice.toFixed(2)}`);

Pro-Rata-Berechnung für Abonnement-Upgrades

Wenn Kunden mitten im Zyklus ein Upgrade durchführen, berechnen Sie die anteiligen Gebühren:

const upgradeSubscription = async (subscriptionId, newPlanId) => {
  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/upgrade`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        plan_id: newPlanId,
        proration: 'immediate', // Differenz sofort berechnen
        invoice_proration: true  // Position auf der Rechnung anzeigen
      })
    }
  );

  return await response.json();
};

Fehlerbehebung bei häufigen Problemen

Problem: Webhooks kommen nicht an

Symptome: Bestellungen werden verarbeitet, aber Ihr System wird nicht aktualisiert.

Diagnose:

// Überprüfen Sie die Webhook-Zustellungsprotokolle im 2Checkout-Dashboard
// Suchen Sie nach fehlgeschlagenen Zustellversuchen oder Nicht-200-Antworten

Lösungen:

1. Vergewissern Sie sich, dass der Endpunkt innerhalb von 5 Sekunden 200 OK zurückgibt
2. Überprüfen Sie die Gültigkeit des SSL-Zertifikats (muss HTTPS sein)
3. Whitelist von 2Checkout IP-Bereichen in Ihrer Firewall
4. Überprüfen Sie die Logik zur Webhook-Signaturüberprüfung
5. Testen Sie mit einem Webhook-Simulator vor der Produktion

Problem: Testzahlungen schlagen in der Sandbox fehl

Symptome: Alle Testkarten werden in der Sandbox-Umgebung abgelehnt.

Lösungen:

1. Bestätigen Sie die Verwendung von Sandbox-API-Schlüsseln (nicht Produktion)
2. Überprüfen Sie die Sandbox-Basis-URL: https://sandbox.2checkout.com/api/
3. Verwenden Sie korrekte Testkartennummern (siehe Abschnitt "Testen")
4. Überprüfen Sie den Status des Sandbox-Kontos (kann nach Inaktivität ablaufen)

Problem: Abonnementverlängerungen schlagen stillschweigend fehl

Symptome: Abonnements werden als aktiv angezeigt, aber Verlängerungen werden nicht verarbeitet.

Diagnose:

// Abonnemant-Zahlungshistorie abfragen
const history = await fetch(
  `https://api.2checkout.com/1/subscriptions/${subId}/payments`,
  { headers: { 'X-Api-Key': privateKey } }
);

Lösungen:

1. Überprüfen Sie das Ablaufdatum der Kunden-Zahlungsmethode
2. Überprüfen Sie die Dunning-Einstellungen im Control Panel
3. Verifizieren Sie die Webhook-Zustellung für subscription.payment_failed
4. Bestätigen Sie, dass das auto_renew-Flag aktiviert ist

Problem: Abweichungen bei der Währungsumrechnung

Symptome: Der abgebuchte Betrag weicht von der erwarteten Umrechnung ab.

Ursache: 2Checkout verwendet tägliche Wechselkurse, die schwanken.

Lösung:

• Zeigen Sie eine "ungefähre" Umrechnung mit Haftungsausschluss an
• Kurse bei der Warenkorberstellung mit 15-minütiger Gültigkeit fixieren
• Transaktionen in der lokalen Währung des Kunden speichern

Problem: AVS (Adressverifizierung) Fehler

Symptome: Legitime Karten werden aufgrund von Adressabweichungen abgelehnt.

Lösungen:

1. Verwenden Sie die automatische Adressvervollständigung (Google Places, Lob)
2. Machen Sie die Postleitzahl an der Kasse erforderlich
3. Implementieren Sie ein "softes" AVS (warnen statt ablehnen)
4. Ermöglichen Sie dem Kunden, die Rechnungsadresse zu aktualisieren

Abonnementverwaltung

2Checkout zeichnet sich durch wiederkehrende Abrechnungen aus. So verwalten Sie Abonnements:

Ein Abonnement erstellen

const createSubscription = async (customerId, planId) => {
  const payload = {
    customer_id: customerId,
    plan_id: planId,
    start_date: new Date().toISOString(),
    billing_cycle: 'monthly', // oder 'annual', 'weekly'
    payment_method: {
      type: 'card',
      card_token: 'tok_card_tokenized'
    },
    options: {
      trial_days: 14, // Optionaler kostenloser Testzeitraum
      auto_renew: true
    }
  };

  const response = await fetch('https://api.2checkout.com/1/subscriptions', {
    method: 'POST',
    headers: {
      'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify(payload)
  });

  return await response.json();
};

Abonnement-Antwort

{
  "subscription_id": "SUB-2026-567890",
  "status": "active",
  "plan_id": "PLAN-PREMIUM-MONTHLY",
  "customer_id": "CUST-789456",
  "current_period_start": "2026-03-20T00:00:00Z",
  "current_period_end": "2026-04-20T00:00:00Z",
  "trial_end": "2026-04-03T00:00:00Z",
  "amount": 29.99,
  "currency": "USD"
}

Ein Abonnement aktualisieren

Ändern Sie Pläne, aktualisieren Sie Zahlungsmethoden oder ändern Sie Mengen:

const updateSubscription = async (subscriptionId, updates) => {
  const payload = {
    ...updates
    // Beispiele:
    // plan_id: 'PLAN-ENTERPRISE-MONTHLY',
    // quantity: 5,
    // payment_method: { card_token: 'new_token' }
  };

  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}`,
    {
      method: 'PUT',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );

  return await response.json();
};

Ein Abonnement kündigen

const cancelSubscription = async (subscriptionId, reason = '') => {
  const payload = {
    cancel_at_period_end: false, // true = nach Ablauf des aktuellen Zeitraums kündigen, false = sofort
    reason: reason
  };

  const response = await fetch(
    `https://api.2checkout.com/1/subscriptions/${subscriptionId}/cancel`,
    {
      method: 'POST',
      headers: {
        'X-Api-Key': process.env.TWOCHECKOUT_PRIVATE_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    }
  );

  return await response.json();
};

Webhook-Integration: Echtzeit-Ereignisverarbeitung

Webhooks benachrichtigen Ihr System über Zahlungsereignisse, ohne dass Sie ständig abfragen müssen. Dies ist entscheidend für Abonnementverlängerungen, fehlgeschlagene Zahlungen und Rückerstattungen.

Schritt 1: Webhook-Endpunkt konfigurieren

In Ihrem 2Checkout Control Panel:

1. Navigieren Sie zu Integrationen > Webhooks
2. Fügen Sie Ihre Endpunkt-URL hinzu (muss HTTPS verwenden)
3. Wählen Sie die Ereignisse aus, die Sie abonnieren möchten
4. Speichern Sie Ihr Webhook Secret und notieren Sie es

Schritt 2: Webhook-Handler erstellen

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

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

  // Webhook-Signatur überprüfen
  const isValid = verifyWebhookSignature(payload, signature, process.env.TWOCHECKOUT_WEBHOOK_SECRET);

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

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

  // An den entsprechenden Handler weiterleiten
  switch (event.type) {
    case 'order.created':
      await handleOrderCreated(event.data);
      break;
    case 'order.approved':
      await handleOrderApproved(event.data);
      break;
    case 'order.declined':
      await handleOrderDeclined(event.data);
      break;
    case 'subscription.created':
      await handleSubscriptionCreated(event.data);
      break;
    case 'subscription.renewed':
      await handleSubscriptionRenewed(event.data);
      break;
    case 'subscription.cancelled':
      await handleSubscriptionCancelled(event.data);
      break;
    case 'refund.processed':
      await handleRefundProcessed(event.data);
      break;
    default:
      console.log('Unbehandelter Ereignistyp:', event.type);
  }

  // Empfangsbestätigung senden
  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')
  );
}

Kritische Webhook-Ereignisse

Best Practices für Webhooks

1. Signaturen immer überprüfen - Verhindert gefälschte Webhooks
2. Schnell 200 OK zurückgeben - 2Checkout versucht es bei Nicht-200-Antworten erneut
3. Asynchron verarbeiten - Ereignisse für die Hintergrundverarbeitung in eine Warteschlange stellen
4. Idempotenz implementieren - Duplikate von Webhook-Zustellungen handhaben
5. Alles protokollieren - Zahlungsstreitigkeiten mit Zeitstempel-Protokollen debuggen

Integration testen

Verwendung der Sandbox-Umgebung

Die 2Checkout-Sandbox ermöglicht Ihnen Tests ohne tatsächliche Gebühren:

// Sandbox-Basis-URL verwenden
const BASE_URL = 'https://sandbox.2checkout.com/api/1';

// Testkartennummern
const TEST_CARDS = {
  APPROVED: '4111111111111111',
  DECLINED: '4000000000000002',
  INSUFFICIENT_FUNDS: '4000000000009995',
  EXPIRED_CARD: '4000000000000069'
};

// Testadressen
const TEST_ADDRESS = {
  country: 'US',
  zip: '90210' // Löst AVS-Prüfungen aus
};

Webhooks lokal testen

Verwenden Sie ngrok, um Ihren lokalen Server freizulegen:

# ngrok installieren
npm install -g ngrok

# Starten Sie Ihren Server auf Port 3000
node server.js

# Ins Internet freigeben
ngrok http 3000

# Kopieren Sie die ngrok-URL in die 2Checkout-Webhook-Einstellungen

Apidog für API-Tests

Apidog optimiert das Testen der 2Checkout API:

1. OpenAPI-Spezifikation importieren - Laden Sie die API-Definition von 2Checkout
2. Testszenarien erstellen - Erstellen Sie Sammlungen für jeden Endpunkt
3. Antworten simulieren - Testen Sie, ohne die API zu kontaktieren
4. Webhooks validieren - Überprüfen Sie die Payload-Strukturen
5. Mit dem Team teilen - Arbeiten Sie gemeinsam an Integrationstests

Erstellen Sie Umgebungsvariablen für Sandbox- vs. Produktionsschlüssel und wechseln Sie dann mit einem Klick die Kontexte.

Checkliste für die Produktionsbereitstellung

Vor dem Go-Live:

• [ ] Von Sandbox- auf Produktions-API-Schlüssel umstellen
• [ ] Basis-URL auf https://api.2checkout.com/ aktualisieren
• [ ] Webhook-Signaturüberprüfung aktivieren
• [ ] Überwachung für fehlgeschlagene Zahlungen einrichten
• [ ] Wiederholungslogik für vorübergehende Fehler konfigurieren
• [ ] Rückerstattungs- und Chargeback-Workflows testen
• [ ] PCI DSS-Konformität überprüfen (Tokenisierung verwenden)
• [ ] 3D Secure 2.0 für EU-Kunden aktivieren
• [ ] Protokollierung für Audit-Trails einrichten
• [ ] Runbook für Zahlungsprobleme erstellen

Überwachung und Alarmierung

Verfolgen Sie diese Metriken:

// Beispiel: Erfolgsrate der Zahlungen
const successRate = approvedOrders / totalOrders * 100;

if (successRate < 95) {
  // Zahlungsteam benachrichtigen
  sendAlert('Zahlungserfolgsrate ist unter 95% gefallen');
}

// Spezifische Fehlercodes verfolgen
const errorBreakdown = errors.reduce((acc, err) => {
  acc[err.code] = (acc[err.code] || 0) + 1;
  return acc;
}, {});

// Bei einem Anstieg spezifischer Fehler alarmieren
if (errorBreakdown['CARD_DECLINED'] > threshold) {
  sendAlert('Anstieg bei Kartenablehnungen festgestellt');
}

Anwendungsfälle in der Praxis

E-Commerce-Shop-Integration

Ein Modehändler integrierte 2Checkout, um globale Zahlungen abzuwickeln. Ergebnisse:

• Automatische Unterstützung von über 100 Währungen
• Reduzierung des Warenkorbabbruchs um 23 %
• Automatische Bearbeitung der EU-Umsatzsteuer-Compliance
• Verarbeitung von über 2 Mio. US-Dollar im ersten Jahr

Die Implementierung dauerte 3 Wochen, wobei zunächst die gehosteten Checkout-Seiten von 2Checkout verwendet und dann für eine benutzerdefinierte UX auf die direkte API-Integration migriert wurde.

SaaS-Abonnementgeschäft

Ein SaaS für Projektmanagement nutzte 2Checkout-Abonnements:

• Verwaltung von über 5.000 aktiven Abonnements
• Pro-Rata-Berechnung für Plan-Upgrades
• Automatisierte Mahnungen bei fehlgeschlagenen Verlängerungen
• Reduzierung der Abwanderung um 15 % durch intelligente Wiederholungsversuche

Hauptfunktion: Webhook-gesteuerte Zugriffskontrolle. Wenn subscription.renewed eintrifft, den Benutzerzugriff sofort verlängern. Wenn subscription.cancelled, den Widerruf des Zugriffs planen.

Fazit

Die 2Checkout API bietet alles, was für die Zahlungsabwicklung und Abonnementverwaltung benötigt wird. Wichtigste Erkenntnisse:

• Verwenden Sie die Sandbox-Umgebung für alle Entwicklungs- und Testphasen
• Implementieren Sie die HMAC-Signaturüberprüfung für Webhooks
• Behandeln Sie Fehler elegant mit spezifischer Fehlercode-Behandlung
• Testen Sie Abonnement-Workflows gründlich (Testphase, Verlängerung, Kündigung)
• Überwachen Sie Zahlungsmetriken in der Produktion
• Nutzen Sie Apidog, um API-Tests und die Teamzusammenarbeit zu optimieren

FAQ-Bereich

Was ist die 2Checkout API?

Die 2Checkout API (jetzt Verifone) ist eine RESTful-Schnittstelle zur Abwicklung von Zahlungen, Verwaltung von Abonnements, Bearbeitung von Rückerstattungen und Automatisierung von E-Commerce-Transaktionen. Sie unterstützt JSON-Payloads, HMAC-Authentifizierung und Echtzeit-Webhooks.

Ist 2Checkout dasselbe wie Verifone?

Ja. 2Checkout wurde 2020 von Verifone übernommen und in Verifone Digital Commerce umbenannt. Die API-Endpunkte und Funktionalitäten bleiben dieselben, obwohl einige Dokumentationen sich auf Verifone beziehen.

Wie erhalte ich meinen 2Checkout API-Schlüssel?

Melden Sie sich in Ihrem 2Checkout Control Panel an, navigieren Sie zu Integrationen > API-Schlüssel und generieren Sie einen neuen Schlüssel. Sie erhalten einen privaten Schlüssel (serverseitig) und einen öffentlichen Schlüssel (clientseitige Tokenisierung).

Hat 2Checkout eine Sandbox-Umgebung?

Ja. Verwenden Sie https://sandbox.2checkout.com/api/ zum Testen. Erstellen Sie ein separates Sandbox-Konto, um Test-API-Schlüssel zu erhalten und Testtransaktionen ohne echte Abbuchungen zu verarbeiten.

Welche Zahlungsmethoden unterstützt 2Checkout?

2Checkout unterstützt Kreditkarten (Visa, Mastercard, Amex, Discover), PayPal, Apple Pay, Google Pay, Banküberweisungen und lokale Zahlungsmethoden in über 100 Ländern.

Wie gehe ich sicher mit Webhooks um?

Überprüfen Sie immer den X-Webhook-Signature-Header mithilfe von HMAC-SHA256 mit Ihrem Webhook Secret. Verarbeiten Sie Ereignisse asynchron und geben Sie sofort 200 OK zurück, um Wiederholungsversuche zu vermeiden.

Was passiert, wenn eine Abonnementzahlung fehlschlägt?

2Checkout sendet einen subscription.payment_failed-Webhook. Implementieren Sie eine Wiederholungslogik (typischerweise 3 Versuche über 7 Tage) und senden Sie einen subscription.cancelled-Webhook, wenn alle Wiederholungsversuche fehlschlagen.

Ist 2Checkout PCI DSS-konform?

Ja, 2Checkout ist PCI DSS Level 1 zertifiziert. Verwenden Sie die clientseitige Tokenisierung, um die Handhabung roher Kartendaten zu vermeiden, was Ihren PCI-Compliance-Umfang reduziert.

Kann ich Abonnements in der Sandbox testen?

Ja. Die Sandbox unterstützt das Testen des vollständigen Abonnement-Lebenszyklus, einschließlich Testphasen, Verlängerungen, Upgrades, Downgrades und Kündigungen. Verwenden Sie die Testkarte 4111111111111111 für erfolgreiche Zahlungen.

Wie bearbeite ich Rückerstattungen über die API?

Senden Sie eine POST-Anfrage an /refunds mit der Bestell-ID und dem Rückerstattungsbetrag. 2Checkout verarbeitet teilweise oder vollständige Rückerstattungen und sendet nach Abschluss einen refund.processed-Webhook.