Accéder aux transactions d'un compte Financial Connections

Nous vous recommandons de créer un objet Customer contenant une adresse e-mail, qui représentera votre utilisateur et que vous pourrez ensuite associer à votre paiement. L’association d’un objet Customer vous permettra par la suite de répertorier les comptes précédemment associés. En renseignant une adresse e-mail dans l’objet Customer, vous permettez à Financial Connections d’améliorer le flux d’authentification en simplifiant l’inscription ou la connexion de votre utilisateur, selon qu’il s’agit d’un nouvel utilisateur de Link ou d’un utilisateur existant.

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

Vous devez d’abord collecter un compte avant de pouvoir accéder à ses données de transaction. Pour découvrir comment collecter les informations d’un compte Financial Connections, consultez le guide d’intégration correspondant le mieux à votre cas d’usage : accepter des paiements, faciliter des virements Connect ou créer d’autres produits reposant sur les données.

Lorsque vous collectez les données d’un compte, vous devez spécifier les données auxquelles vous avez besoin d’accéder à l’aide du paramètre autorisations. L’utilisateur peut consulter l’ensemble des autorisations d’accès aux données demandées dans le flux d’authentification. Les comptes Financial Connections peuvent être collectés via différents chemins d’intégration, et la façon de spécifier le paramètre varie légèrement en fonction de l’API.

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

Si vous utilisez des moyens de paiement dynamiques pour certaines API de paiement, vous pouvez également configurer les autorisations demandées dans le Dashboard. Découvrez comment accéder aux données supplémentaires sur les comptes Financial Connections.

Lorsque vous vous abonnez aux données de transaction d’un compte, Stripe récupère automatiquement en arrière-plan les nouvelles transactions chaque jour et vous informe dès qu’elles sont disponibles. L’abonnement aux mises à jour quotidiennes est le moyen le plus simple de maintenir les données de transaction du compte à jour.

Pour obtenir l’ID du compte Financial Connections dont vous souhaitez vous abonner aux transactions, consultez la documentation relative à nos intégrations de paiement ou le guide sur les sessions Financial Connections.

Abonnez-vous aux données de transaction en appelant l’API d’abonnement :

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

En plus d’activer un abonnement aux données de transactions futures, cet appel à l’API lance automatiquement une actualisation des transactions :

{
  "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"
  }
  // ...
}

Tant que vous restez abonné aux données de transaction, Stripe lance une nouvelle actualisation chaque jour.

Attendre la fin de l’actualisation

Toutes les actualisations de données Financial Connections sont asynchrones. Après avoir initié une actualisation des transactions, attendez qu’elle se termine, puis récupérez les résultats.

Le champ transaction_refresh d’un compte Financial Connections représente l’état d’actualisation des transactions. Ce champ reste null jusqu’à ce que vous demandiez l’autorisation transactions et initiez une actualisation. Après avoir lancé une actualisation des transactions, l’état passe pending. Une fois terminée, il bascule sur succeeded ou failed. Nous envoyons l’événement financial_connections.account.refreshed_transactions lorsque l’actualisation des transactions a été effectuée. Pour déterminer si l’actualisation a abouti, vérifiez le champ transaction_refresh.status lors du traitement du webhook.

Une fois que Stripe a actualisé les transactions du compte, vous pouvez les récupérer à l’aide de l’API Transactions List :

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

Stripe renvoie une liste paginée comprenant jusqu’à 180 jours d’historique des transactions sur un compte, en fonction de l’institution financière du compte.

{
  "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"
}

Une transaction peut être à l’état pending (en attente), posted (comptabilisée), ou void (annulée). Les informations incluses dans le champ description varient, mais peuvent inclure des métadonnées telles que le nom de l’entreprise.

Récupérer les transactions depuis la dernière actualisation

Vous pouvez choisir de récupérer uniquement les données de transaction apparues depuis votre dernier pull de données. Par exemple, certains utilisateurs enregistrent les données de transaction précédemment récupérées dans leur base de données, puis fusionnent les données nouvelles ou mises à jour dès qu’elles sont disponibles.

Pour récupérer uniquement les données de transaction nouvelles ou mises à jour depuis votre dernière actualisation, transmettez à l’API List l’identifiant transaction_refresh fourni par votre dernier objet d’événement webhook financial_connections.account.refreshed_transactions observé :

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

Voici un exemple d’intégration de webhook qui récupère et enregistre uniquement les données de transaction nouvelles ou mises à jour :

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)