Auf Transaktionen für ein Financial Connections-Konto zugreifen

Wir empfehlen Ihnen, eine Kundin/einen Kunden mit einer zu der Kundin/dem Kunden gehörenden E-Mail-Adresse zu erstellen, die Sie dann Ihrer Zahlung hinzufügen. Wenn Sie ein Kundenobjekt anhängen, können Sie später zuvor verknüpfte Konten auflisten. Durch Angabe einer E-Mail-Adresse für das Kundenobjekt kann Financial Connections den Authentifizierungsvorgang optimieren, indem es für eine reibungslose Anmeldung oder reibungslose Registrierung auf Kundenseite sorgt, je nachdem, ob es sich um wiederkehrende Link-Nutzer/innen handelt.

curl https://api.stripe.com/v1/customers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d email={{CUSTOMER_EMAIL}}

Sie müssen ein Konto erfassen, bevor Sie auf seine Transaktionsdaten zugreifen können. Um mehr über die Erfassung von Financial Connections-Konten zu erfahren, lesen Sie den Integrationsleitfaden, der für Ihren Anwendungsfall relevant ist: Zahlungen akzeptieren, Connect-Auszahlungen ermöglichen oder durch andere Daten gestützte Produkte entwickeln.

Bei der Erfassung eines Kontos geben Sie die Daten, auf die Sie Zugriff benötigen, mit dem Parameter Berechtigungen an. Die angeforderten Datenberechtigungen können von den Nutzerinnen und Nutzern im Authentifizierungsablauf eingesehen werden. Financial Connections-Konten können über verschiedene Integrationspfade erfasst werden. Die Art und Weise, wie Sie den Parameter angeben, variiert je nach API leicht.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=20000 \
  -d currency=usd \
  -d customer=
{{CUSTOMER_ID}} \
  -d "payment_method_types[]"=us_bank_account \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=transactions \
  -d "payment_method_options[us_bank_account][financial_connections][permissions][]"=payment_method

Bei der Verwendung dynamischer Zahlungsmethoden für bestimmte Zahlungs-APIs können Sie die angeforderten Berechtigungen auch im Dashboard konfigurieren. Hier erfahren Sie, wie Sie auf zusätzliche Kontodaten für Financial Connections-Konten zugreifen.

Wenn Sie die Transaktionsdaten eines Kontos abonnieren, ruft Stripe jeden Tag automatisch neue Transaktionen im Hintergrund ab und benachrichtigt Sie, wenn diese verfügbar sind. Das Abonnieren täglicher Aktualisierungen ist der einfachste Weg, um die Transaktionsdaten des Kontos auf dem neuesten Stand zu halten.

Um die ID des Financial Connections-Kontos zu erhalten, über das Sie standardmäßig Transaktionen abwickeln möchten, lesen Sie die Dokumentation zu unseren Zahlungsintegrationen oder den Leitfaden für Financial Connections-Sitzungen.

Rufen Sie die Abonnement-API ab, um die Transaktionsdaten zu abonnieren:

curl https://api.stripe.com/v1/financial_connections/accounts/
{{ACCOUNT_ID}}
/subscribe \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d "features[]"=transactions

Zusätzlich zur Aktivierung eines Abonnements für zukünftige Transaktionsdaten wird durch diesen API-Aufruf automatisch eine Transaktionsaktualisierung veranlasst:

{
  "id": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
  "object": "financial_connections.account",
  "display_name": "Savings",
  "institution_name": "Test Bank",
  "status": "active",
  "permissions": ["transactions"],
  "subscriptions": ["transactions"],
  "transaction_refresh": {
    "id": "fctxnref_1aaaxqEitUZY8Svm4QdcWZKt",
    "last_attempted_at": 1706742786,
    "next_refresh_available_at": null,
    "status": "pending"
  }
  // ...
}

Solange Sie Transaktionsdaten abonniert haben, veranlasst Stripe jeden Tag eine neue Aktualisierung.

Warten Sie, bis die Aktualisierung abgeschlossen ist

Alle Datenaktualisierungen von Financial Connections sind asynchron. Nachdem Sie eine Transaktionsaktualisierung veranlasst haben, müssen Sie warten, bis sie abgeschlossen ist, und dann die resultierenden Transaktionen abrufen.

Das Feld transaction_refresh eines Financial Connections-Kontos stellt den Aktualisierungsstatus der Transaktion dar. Dieses Feld bleibt null, bis Sie die Berechtigung transactions anfordern und eine Aktualisierung einleiten. Nachdem Sie eine Aktualisierung der Transaktion gestartet haben, ändert sich der Status in pending und nach Abschluss wechselt er entweder zu succeeded oder zu failed. Wir senden das Ereignis financial_connections.account.refreshed_transactions, wenn die Aktualisierung der Transaktion abgeschlossen ist. Um zu ermitteln, ob die Transaktion erfolgreich aktualisiert wurde, überprüfen Sie das Feld transaction_refresh.status während der Bearbeitung des Webhooks.

Nachdem Stripe Transaktionen auf dem Konto erfolgreich aktualisiert hat, können Sie sie über die Transaktionslisten-API abrufen:

curl -G https://api.stripe.com/v1/financial_connections/transactions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{ACCOUNT_ID}}

Stripe gibt eine paginierte Liste des Transaktionsverlaufs für ein Konto zurück. Je nach Finanzinstitut umfasst diese Liste maximal die letzten 180 Tage, die Tagesanzahl kann jedoch auch geringer sein.

{
  "object": "list",
  "data": [
    {
      "id": "fctxn_1LXp9RGxLVUXRs6HtTSVfxse",
      "object": "financial_connections.transaction",
      "account": "fca_1LDYuMGxLVUXRs6HW0lrat9T",
      "amount": -1000,
      "currency": "usd",
      "description": "Rocket Rides",
      "livemode": true,
      "status": "posted",
      "status_transitions": {
        "posted_at": 1651784999,
        "void_at": null
      },
      "transacted_at": 1651784999,
      "transaction_refresh": "fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf",
      "updated": 1651784999
    },
    {...},
    {...}
  ],
  "has_more": false,
  "url": "/v1/financial_connections/transactions"
}

Der Status einer Transaktion ist pending, posted oder void. Die im Feld Beschreibung enthalten Informationen sind unterschiedlich, können aber Metadaten wie den Unternehmensnamen beinhalten.

Transaktionen seit der letzten Aktualisierung abrufen

Möglicherweise möchten Sie nur neue Transaktionsdaten seit Ihrem letzten Datenabruf abrufen. Einige Nutzer/innen speichern beispielsweise zuvor abgerufene Transaktionsdaten in ihrer Datenbank und führen anschließend neue oder aktualisierte Daten zusammen, sobald diese verfügbar werden.

Um nur Transaktionsdaten abzurufen, die seit Ihrer letzten Aktualisierung aktualisiert wurden oder neu sind, übergeben Sie die Kennung transaction_refresh, die von Ihrem zuletzt überwachten Webhook-Ereignisobjekt financial_connections.account.refreshed_transactions übergeben wurde, an die List API:

curl -G https://api.stripe.com/v1/financial_connections/transactions \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d account=
{{ACCOUNT_ID}} \
  -d "transaction_refresh[after]"=fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf

Nachfolgend finden Sie ein Beispiel für eine Webhook-Integration, die nur neue oder aktualisierte Transaktionsdaten abruft und aufzeichnet:

import stripe
from flask import Flask
app = Flask(__name__)

@app.route('/stripe_webhooks', methods=['POST'])
def webhook():
    event = None
    try:
        event = stripe.Event.construct_from(json.loads(request.data), stripe.api_key)
    except ValueError as e:
        # Invalid payload
        raise e

    if event.type == "financial_connections.account.refreshed_transactions":
        account = event.data.object
        sync_transactions(account["id"], account["transaction_refresh"]["id"])

    return jsonify(success=True)


def sync_transactions(account_id, current_refresh):
    # Fetches the last transaction_refresh observed for this account from internal database
    last_observed_transaction_refresh = get_previous_transaction_refresh(key=account_id)

    # Get transactions since the last seen transaction_refresh
    response = stripe.financial_connections.Transaction.list(
        account=account_id,
        transaction_refresh={"after": last_observed_transaction_refresh},
    )

    # We know every transaction is either new or updated because of the `transaction_refresh` filter in the list endpoint
    for transaction in response.data:
        record_transaction(transaction)  # Saves the transaction to the DB

    # Updates the last observed transaction_refresh for this account to the current refresh
    set_previous_transaction_refresh(key=account_id, value=current_refresh)