DE
NexCMP kostenlos sichern
Gilt für NexCMP 1.6.1·Aktualisiert ·Als Markdown anzeigen

Stripe ​

Wo im Admin: Finance › Payment channels › Stripe (/payments/stripe). Schalter und Gebühren: Finance › Payment channels › Fees & limits (/payments/fees).

Funktion ​

Stripe wickelt Kartenzahlungen für Guthabenaufladungen ab. Mit demselben Konto können Sie auch Apple Pay, Google Pay, Link und Alipay anbieten und Kunden eine Karte speichern lassen für automatic top-up. Verwenden Sie dies als primären Kanal für internationale Kunden.

Anforderungen ​

KomponenteAnforderung
Stripe-KontoEin Stripe-Konto, das Zahlungen in USD akzeptieren kann. Alipay wird in JPY belastet und muss von Stripe für Ihr Konto freigeschaltet werden.
SchlüsselEin geheimer Schlüssel (sk_live_... oder sk_test_...) und ein öffentlicher Schlüssel (pk_live_... oder pk_test_...). Das Formular akzeptiert nur Schlüssel mit diesen Präfixen.
NetzwerkIhr Panel muss aus dem Internet über HTTPS erreichbar sein (Stripe ruft den Webhook auf) und api.stripe.com über Port 443 erreichen können.
Domain (nur Guthaben)Die kundenorientierte Domain muss /.well-known/apple-developer-merchantid-domain-association bereitstellen – NexCMP erledigt dies für Sie.
AbhängigkeitenKeine.

Gemeinsam genutzte Stripe-Konten

NexCMP verarbeitet nur Webhook-Ereignisse für Zahlungen, die es selbst erstellt hat, sodass Sie ein Stripe-Konto verwenden können, das auch eine andere Anwendung bedient.

Infrastruktur vorbereiten ​

Aufseiten von Stripe:

  1. Melden Sie sich im Stripe Dashboard an. Schalten Sie Test mode ein oder aus, um zu bestimmen, ob Sie einen Probelauf durchführen oder den Live-Betrieb starten. Schlüssel des einen Modus funktionieren niemals mit dem anderen.
  2. Öffnen Sie Developers › API keys. Kopieren Sie den Publishable key, und blenden Sie den Secret key ein, um ihn zu kopieren. Halten Sie den geheimen Schlüssel unter Verschluss.
  3. (Optional) Öffnen Sie Settings › Payment methods, und aktivieren Sie Alipay, falls Sie dies anbieten möchten.
  4. Sie müssen den Webhook nicht manuell erstellen — NexCMP kann dies für Sie erledigen (siehe Schritt 5 unten). Wenn Sie es lieber manuell tun möchten, erstellen Sie einen Endpunkt unter Developers › Webhooks mit der URL und den in Webhook aufgelisteten Ereignissen.

In NexCMP verbinden ​

  1. Öffnen Sie Finance › Payment channels › Stripe (/payments/stripe).
  2. Wählen Sie in der Karte API keys den Mode (live oder test), fügen Sie den Secret key sowie den Publishable key ein.
  3. Klicken Sie auf Save. Die Schlüssel werden in eine Konfigurationsdatei auf dem Server geschrieben, die nur das NexCMP-Dienstkonto lesen kann. Sie werden niemals an den Browser zurückgesendet; danach zeigt die Seite nur noch die letzten 4 Zeichen an.
  4. Klicken Sie auf Check. Ein Dialog meldet die Verbindung, den Modus, das verfügbare und ausstehende Guthaben, die Konto-ID, ob Belastungen aktiviert sind, ob ein Webhook existiert und ob Alipay verfügbar ist. Eine rote Zeile bedeutet, dass dieser Teil Aufmerksamkeit erfordert.
  5. Klicken Sie in der Karte Webhook auf Create webhook, und bestätigen Sie dies. NexCMP fordert Stripe auf, den Endpunkt mit jedem erforderlichen Ereignis zu erstellen, und füllt das Webhook signing secret (whsec_...) automatisch aus. Die im Feld vorausgefüllte URL ist https://<your-domain>/v1/billing/stripe/webhook, zum Beispiel https://cloud.example.com/v1/billing/stripe/webhook.
  6. Öffnen Sie Fees & limits (/payments/fees), lassen Sie Card (Stripe) eingeschaltet, stellen Sie Stripe fee % sowie Stripe fixed fee (cents) auf Ihren echten Tarif ein, und klicken Sie auf Save channels & fees. Siehe Payment channels.

Stripe-Seite mit dem Modus, dem Secret Key und dem Publishable Key mit Beispielwerten ausgefüllt

Webhook ​

Das rote Banner "Missing webhook_secret" bleibt bestehen, bis ein Signierungsgeheimnis gespeichert wurde. Ohne dieses werden Stripe-Guthabenaufladungen nicht erfasst, obwohl Stripe das Geld eingezogen hat.

KomponenteWert
URLhttps://<your-domain>/v1/billing/stripe/webhook
Ereignissecheckout.session.completed, payment_intent.succeeded, payment_intent.payment_failed, charge.refunded, charge.dispute.created, charge.dispute.closed, radar.early_fraud_warning.created, refund.updated, refund.failed
SignaturStripe Stripe-Signature-Header, HMAC-SHA256, 300 Sekunden Toleranz. Anfragen mit einer ungültigen Signatur erhalten HTTP 400.
IdempotenzJede Ereignis-ID wird einmal gespeichert; eine wiederholte Zustellung führt niemals zu einer doppelten Gutschrift.

Wenn Sie von einer Version aktualisiert haben, die weniger Ereignisse registriert hat, klicken Sie erneut auf Create webhook — der alte Endpunkt bleibt erhalten, löschen Sie diesen daher im Anschluss manuell im Stripe Dashboard.

Die Zeilen 24h events und Latest event in der Webhook-Karte zeigen Ihnen an, ob Stripe das Panel erreicht. Einzelne Ereignisse sind unter Payment channels › Gateway events (/payments/events, Registerkarte Stripe) aufgelistet, wo jedes Ereignis eingesehen (Payload) oder erneut abgespielt (Replay) werden kann.

  1. In der Karte Wallets (Apple Pay · Google Pay · Link) & Alipay ist das Feld Customer app Domain registered with Stripe mit dem Hostnamen Ihrer Website vorausgefüllt (zum Beispiel cloud.example.com).
  2. Klicken Sie auf Register / verify domain, und bestätigen Sie dies. NexCMP registriert die Domain in den Zahlungsmethoden-Domains von Stripe und bittet Stripe, diese zu validieren.
  3. Das Ergebnis zeigt den Status von Apple Pay, Google Pay und Link. Apple Pay wird nur angezeigt, wenn der Status active ist.
  4. Lassen Sie unter Fees & limits Apple Pay · Google Pay · Link eingeschaltet.

Wallet-Karte mit der registrierten Domain sowie den Status von Apple Pay, Google Pay und Link

Apple Pay bleibt inaktiv

Apple Pay benötigt die Domain-Assotiationsdatei, um HTTP 200 auf Ihrer öffentlichen Domain zu beantworten. Wenn Sie Cloudflare oder einen anderen Proxy davor schalten, blockieren Sie /.well-known/ nicht.

Alipay ​

Alipay ist optional. Aktivieren Sie es in Stripe Dashboard › Settings › Payment methods, klicken Sie auf Check und warten Sie, bis der Dialog anzeigt, dass Alipay verfügbar ist. Schalten Sie dann Alipay (Stripe, JPY display) unter Fees & limits ein. Legen Sie Alipay fee %, Alipay fixed fee, den ¥/USD rate (50–500) und den FX spread % (0–20) fest. Aktualisieren Sie den ¥/USD-Kurs regelmäßig; die Seite warnt, wenn er älter als 7 Tage ist.

Verifizierung ​

  1. Melden Sie sich im Testmodus als Testkunde im Portal an, öffnen Sie Billing, klicken Sie auf Deposit, wählen Sie Card und bezahlen Sie den Mindestbetrag mit der Stripe-Testkarte 4242 4242 4242 4242 (ein beliebiges zukünftiges Datum, ein beliebiger CVC).
  2. Das Guthaben erhöht sich innerhalb von Sekunden und die Zahlung erscheint unter Finance › Billing › Top-ups mit dem Status Completed.
  3. Öffnen Sie Payment channels › Gateway events › Stripe: Sie sollten checkout.session.completed oder payment_intent.succeeded mit einer Verarbeitungszeit sehen.
  4. Wieder auf der Stripe-Seite ist 24h events größer als 0.

Schalten Sie vor dem Live-Gang Mode auf live, fügen Sie die Live-Schlüssel ein und klicken Sie erneut auf Create webhook (Webhooks für Test- und Live-Modus sind getrennt).

Limits & Hinweise ​

  • Beträge und Währung. Wallets lauten auf USD. Karten-, Wallet- und Link-Zahlungen werden in USD belastet; Alipay wird dem Kunden in JPY angezeigt und zu Ihrem Kurs umgerechnet.
  • Gebühren. Die tatsächliche Gebühr von Stripe wird nicht automatisch ausgelesen; der von Ihnen festgelegte Prozentsatz bestimmt, was der Kunde sieht und dem Guthaben gutgeschrieben wird. Wählen Sie Customer pays top-up fee unter Fees & limits, um die Gebühr zusätzlich zu erheben.
  • Gespeicherte Karten. Wenn der Kunde Save card for auto top-up ankreuzt, wird die Karte bei Stripe gespeichert, nicht auf Ihrem Server. Siehe Saved payment methods.
  • Rückerstattungen. Eine Rückerstattung auf die Karte erfolgt in zwei Schritten: Ein Administrator erstellt eine Rückerstattungsanfrage für eine abgeschlossene Zahlung (Finance › Billing › Top-ups, Rückerstattungsaktion für die Zahlung) und genehmigt sie dann unter Finance › Payouts › Card refunds (/billing/payouts). Alipay-Rückerstattungen erfolgen asynchron; eine fehlgeschlagene (refund.failed) erstattet den einbehaltenen Betrag an das Wallet zurück.
  • Streitfälle. Bei charge.dispute.created sperrt NexCMP das Kundenkonto, stoppt dessen Prepaid-Dienste (es wird nichts gelöscht) und sendet eine Admin-Benachrichtigung. Wenn Sie gewinnen (charge.dispute.closed), wird der Betrag dem Wallet wieder gutgeschrieben.
  • Ausstehende Zahlungen. Wenn ein Webhook niemals eintrifft, gleicht NexCMP Zahlungen, die länger als 10 Minuten im Status ausstehend verbleiben, eigenständig mit Stripe ab und schließt sie ab. Zahlungen, die älter als 7 Tage sind, werden ignoriert.
  • Resellers können ihr eigenes Stripe-Konto verknüpfen (Webhook https://<their-domain>/v1/billing/stripe/webhook/r/<id>); siehe Resellers.

Fehlerbehebung ​

SymptomUrsacheBehebung
"Secret Key muss mit sk_live_/sk_test_ beginnen"Falscher Schlüssel eingefügtFügen Sie den Secret Key aus Developers › API keys ein.
"Secret Key stimmt nicht mit dem Live-/Test-Modus überein"Modus und Schlüssel stimmen nicht übereinPassen Sie Mode an das Präfix des Schlüssels an.
"Publishable Key muss mit pk_ beginnen"Falscher SchlüsselVerwenden Sie den veröffentlichbaren Schlüssel.
Prüfung meldet fehlgeschlagene VerbindungFalscher Schlüssel, widerrufener Schlüssel oder der Server kann api.stripe.com nicht erreichenFügen Sie den Schlüssel erneut ein; testen Sie mit curl -I https://api.stripe.com vom Server aus.
Rotes Banner „Missing webhook_secret“Das Signierungsgeheimnis ist nicht gespeichertKlicken Sie auf Create webhook oder fügen Sie das whsec_...-Geheimnis aus dem Stripe-Dashboard ein und klicken Sie auf Save.
Geld abgebucht, aber das Guthaben hat sich nicht geändertWebhook nicht zugestellt oder Signaturprüfung fehlgeschlagenÜberprüfen Sie, ob die URL auf /v1/billing/stripe/webhook endet, das Geheimnis zum Endpunkt passt und spielen Sie das Ereignis unter Gateway events erneut ab. Öffnen Sie in Stripe den Endpunkt und prüfen Sie die Zustellungsversuche (HTTP 400 bedeutet ein falsches Signierungsgeheimnis).
"Create webhook" schlägt fehlDie URL ist kein HTTPS oder nicht erreichbarVerwenden Sie Ihre öffentliche https://-Domain.
Apple-Pay-Status nicht aktivDomain nicht validiertKlicken Sie erneut auf Register / verify domain, nachdem die Domain-Zuordnungsdatei mit 200 antwortet.
Alipay im Prüfdialog nicht verfügbarBei Stripe nicht aktiviertAktivieren Sie es im Stripe-Dashboard und klicken Sie dann auf Check.
Kunde sieht kein KartenformularCard (Stripe) ist deaktiviert oder kein geheimer Schlüssel vorhandenAktivieren Sie es unter Fees & limits und speichern Sie die Schlüssel.