Mit der API auf Anfechtungen reagieren

Sie können auf Zahlungsanfechtungen im Stripe-Dashboard reagieren, in dem wir Sie durch den Vorgang zur Einreichung der optimalen Beweise für jeden Anfechtungsgrund leiten.

Sie können Zahlungsanfechtungen auch programmgesteuert über die API verwalten. Mit der API können Sie Beweise hochladen, auf Zahlungsanfechtungen reagieren und Anfechtungsereignisse mithilfe von Webhooks empfangen.

Eine Zahlungsanfechtung abrufen

Details zu einer Zahlungsanfechtung erhalten Sie, wenn Sie das Dispute-Objekt abrufen:

curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:"

Die Antwort enthält Informationen über die angefochtene Zahlung und alle Antworten oder Nachweise, die bereits vorgelegt wurden.

{
  object: "dispute"
  id: "{{DISPUTE_ID}}",
  charge: "ch_5Q4BjL06oPWwho",
  evidence: {
    customer_name: "Jane Austen",
    customer_purchase_ip: "127.0.0.1",
    product_description: "Widget ABC, color: red",
    shipping_tracking_number: "Z01234567890",
    uncategorized_text: "Additional notes and comments",
  },
  evidence_details: {
    due_by: 1403047735,
    submission_count: 1
  }
  ...
}

Zahlungsanfechtung aktualisieren

Sie aktualisieren das Dispute-Objekt und übergeben strukturierte Nachweise mit dem Parameter evidence.

curl https://api.stripe.com/v1/disputes/
{{DISPUTE_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  --data-urlencode "evidence[customer_email_address]"="email@example.com" \
  -d "evidence[shipping_date]"=2024-02-01 \
  -d "evidence[shipping_documentation]"=
{{FILE_ID}}

Informationen dazu, wie Sie alle verfügbaren Felder für den Nachweis-Parameter anzeigen, finden Sie unter Nachweis bei angefochtener Zahlung. Sie können zwei Arten von Nachweisen erbringen, je nachdem, welches Feld aktualisiert wird:

• Textbasierte Nachweise, z. B. customer_email und service_date. Für diese Arten von Nachweisen ist eine Textzeichenfolge erforderlich.
• Dateibasierte Nachweise, wie z. B. service_documentation und customer_communication. Diese benötigen eine file_upload-Objekt-ID.

Sie können Dokumente oder Bilder (zum Beispiel einen Vertrag oder Screenshots) als Teil des Beweises über die angefochtene Zahlung über die File Upload API bereitstellen. Sie laden zunächst ein Dokument mit dem Zweck dispute_evidence hoch, wodurch ein File_upload-Objekt generiert wird, das Sie beim Einreichen von Beweisen verwenden können. Stellen Sie sicher, dass die Datei den Empfehlungen von Stripe entspricht, bevor Sie diese zur Übermittlung von Beweisen hochladen.

Wenn Sie nur eine einzelne Datei oder eine große Menge Klartext als Nachweis einreichen möchten, verwenden Sie uncategorized_text oder uncategorized_file. Füllen Sie jedoch so viele Felder wie möglich aus, damit Sie die größtmögliche Chance haben, eine Zahlungsanfechtung abzuwenden.

Mehrere angefochtene Zahlungen für eine einzige Zahlung

Es ist zwar nicht üblich, aber Kundinnen/Kunden können dieselbe Zahlung mehr als einmal anfechten. Beispielsweise könnte eine Zahlung für einen Artikel einer Bestellung teilweise angefochten werden, weil der Artikel bei der Zustellung beschädigt wurde. Dann kann eine Zahlungsanfechtung für einen weiteren Artikel erstellt werden, weil dieser nicht ordnungsgemäß funktioniert.

Stripe unterscheidet alle Zahlungsanfechtungen anhand einer eindeutigen ID. Dabei ist es egal, ob diese zu einer einzelne Zahlung gehören. Wenn Sie die Zahlungsanfechtungen auflisten, können Sie die Ergebnisse so filtern, dass nur Zahlungsanfechtungen für eine bestimmte Zahlung angezeigt werden. Geben Sie dafür die id des PaymentIntent oder Charge-Objekts und den Filter payment_intent oder charge an.

curl -G https://api.stripe.com/v1/disputes \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d payment_intent={{PAYMENT_INTENT_ID}}

Wenn für eine Zahlung mehrere Zahlungsanfechtungen vorliegen, verwenden Sie unbedingt die id der zurückgegebene Zahlungsanfechtung aus der Liste. So stellen Sie sicher, dass Sie sich stets auf die richtige Anfechtung beziehen. Die id geben Sie beim Abrufen oder Aktualisieren der Zahlungsanfechtung an.