Weiter zum Inhalt
Konto erstellen oder anmelden
Das Logo der Stripe-Dokumentation
/
Konto erstellenAnmelden

Die Payment Records API

Führen Sie eine einheitliche Historie Ihrer Zahlungen, sowohl auf Stripe als auch außerhalb von Stripe.

Verwenden Sie die Payment Records API, um ein Hauptbuch all Ihrer Zahlungen zu führen. Wenn Sie Zahlungen über Stripe (Zahlungen innerhalb von Stripe) oder mit Drittanbietern (Zahlungen außerhalb von Stripe) abwickeln, verwenden Sie diese API, um einen einheitlichen Verlauf Ihrer Zahlungen zu führen.

Die Payment Records API ermöglicht Ihnen Folgendes:

  • Tätigen Sie Zahlungen mit einem Drittanbieter-Abwickler und melden Sie die Ergebnisse an Stripe, um die volle Funktionalität von Produkten wie Abonnements und Radar zu nutzen.
  • Erstellen Sie komplexe Zahlungsabläufe (z. B. Mehrfacherfassungen), bei denen Sie jede Erfassung nachverfolgen können.
  • Verfolgen Sie von Drittanbietern und Partnern initiierte Zahlungen, einschließlich von Stripe angewiesener Kartentransaktionen.

Beziehung zu PaymentIntents

Mit der Payment Intents API wird eine Reihe verschiedener Zahlungsabläufe verwaltet. Viele erweiterte Anwendungsszenarien erfordern jedoch eine genauere Darstellung des Zahlungsverlaufs.

Wenn Ihre Anwendung Zahlungen sowohl auf Stripe mit PaymentIntents als auch außerhalb von Stripe über einen anderen Abwickler akzeptiert, können Sie PaymentRecords als vollständiges Aufzeichnungssystem verwenden. Wenn Sie die Orchestrierung aktiviert haben:

  • Zahlungen über Stripe: Stripe erstellt für jeden PaymentIntent automatisch einen PaymentRecord.
  • Zahlungen außerhalb von Stripe: Sie können PaymentRecords manuell erstellen, indem Sie Zahlungsdaten über die Payment Records API melden.

PaymentRecords ermöglichen die Interoperabilität zwischen Stripe-Produkten. Produkte wie Abonnements (mit Smart Retries) und außerhalb von Stripe bezahlte Rechnungen verwenden PaymentRecords als Kernelement zur Nachverfolgung von Zahlungsergebnissen.

So rufen Sie den PaymentRecord ab, der einem PaymentIntent zugeordnet ist, für den die Orchestrierung aktiviert ist:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_records/
{{PAYMENT_INTENT_ID}}
 \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

PaymentRecords erstellen und verwalten

Ein PaymentRecord ist der Datensatz einer Zahlung und enthält alle damit verbundenen Versuche und Ergebnisse. Es ist der wichtigste Anhaltspunkt für das Verständnis des Lebenszyklus und Status einer Zahlung.

Jeder PaymentRecord kann mehrere PaymentAttemptRecords haben, die jeweils einen bestimmten Versuch beschreiben, die Zahlung abzuwickeln. Diese Struktur ermöglicht es Ihnen, erfolgreiche, wiederholbare Versuche und fehlgeschlagene Versuche nachzuverfolgen.

Neue Zahlung melden

Um eine Zahlung außerhalb von Stripe zu melden, erstellen Sie einen PaymentRecord mit Details zur Transaktion, einschließlich des Betrags, der Zahlungsmethode, des Abwicklers und relevanter Zeitstempel. Stripe erstellt automatisch ein zugehöriges PaymentAttemptRecord mit den angegebenen Daten, auf die in der Antwort als latest_payment_attempt_record verwiesen wird.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_records/report_payment \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "amount_requested[currency]"=usd \
  -d "amount_requested[value]"=1000 \
  -d initiated_at=1730253453 \
  -d outcome=guaranteed \
  -d "guaranteed[guaranteed_at]"=1746572320 \
  -d "payment_method_details[payment_method]"=
"{{PAYMENT_METHOD_ID}}"
 \
  -d "processor_details[type]"=custom

Fehlgeschlagenen Zahlungsversuch melden

Durch das Melden fehlgeschlagener Zahlungsversuche wird sichergestellt, dass Stripe einen vollständigen Überblick über Ihre Zahlungsabläufe hat, damit andere Produkte funktionieren (zum Beispiel Smart Retries). Wenn ein Zahlungsversuch fehlschlägt, melden Sie den Fehler, indem Sie auf die vorhandene PaymentRecord-ID verweisen und den Zeitpunkt des fehlgeschlagenen Versuchs übergeben.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt_failed \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d failed_at=1730253453

Fehlgeschlagene Zahlungen erneut versuchen

Manchmal versuchen Nutzer/innen, fehlgeschlagene Zahlungen mehrmals zu wiederholen. Sie können einen neuen Zahlungsversuch mit demselben PaymentRecord melden. Für Wiederholungsversuche können dieselbe oder unterschiedliche Zahlungsmethoden und Abwickler verwendet werden.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}}/report_payment_attempt \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d initiated_at=1730253825 \
  -d "payment_method_details[payment_method]"=
"{{PAYMENT_METHOD_ID}}"

Überblick über den Status Ihrer Zahlungen

Sie können PaymentRecord für Ihre Dashboards und Berichtssysteme verwenden. Da Sie über einen einzigen Datensatz verfügen, müssen Sie die Modellierungsunterschiede zwischen Ihren anderen Abwicklern und Stripe nicht abgleichen.

PaymentRecord abrufen

Sie können den PaymentRecord mithilfe der ID abrufen. Bei orchestrierten Zahlungen wird dies in der PaymentIntent-Antwort zurückgegeben. Für vergangene Zahlungen können Sie PaymentRecord auch über die ID des PaymentIntent abrufen.

Der letzte PaymentAttemptRecord ist im PaymentRecord verfügbar und Sie können ihn über das API Datensätze zu Zahlungsversuchen abrufen. Bei vergangenen Zahlungen, die die Charges API verwenden, verwenden Sie die Zahlungs-ID, um den PaymentAttemptRecord abzurufen.

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl https://api.stripe.com/v1/payment_records/{{PAYMENT_RECORD_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"
Example response
{
  "processor_details": {
    "type": "processor_a",
  },
  "latest_payment_attempt_record": "{{PAYMENT_ATTEMPT_RECORD_ID}}",
  "amount_guaranteed": {
    "value": 10000,
    "currency": "usd",
  },
  "payment_method_details": {
    "payment_method": "{{PAYMENT_METHOD_ID}}",
    "type": "card",
  },
}
...

PaymentAttemptRecord abrufen

In Fällen, in denen mehrere Zahlungsversuche vorliegen (z. B. wenn eine Zahlung bei einem anderen Abwickler fehlgeschlagen ist und auf Stripe erfolgreich wiederholt wurde), enthält das PaymentRecord den letzten Zahlungsversuch unter latest_payment_attempt_record. Sie können alle Versuche anzeigen, indem Sie PaymentAttemptRecord abfragen:

Command Line
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
curl -G https://api.stripe.com/v1/payment_attempt_records \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_record={{PAYMENT_RECORD_ID}}
Example response
{
  "object": "list",
  "data": [{
    "id": "par_124",
    "amount_requested": 10000,
    "amount_guaranteed": 10000,
    "amount_failed": 0,
  },
  {
    "id": "par_123",
    "amount_requested": 10000,
    "amount_guaranteed": 0,
    "amount_failed": 10000,
  }]
}
...

Sie können Ihre Zahlungen auch im Dashboard einsehen.

War diese Seite hilfreich?
JaNein