# Accéder aux transactions d'un compte Financial Connections Accéder aux transactions d'un compte avec l'autorisation de votre utilisateur. L’API Financial Connections vous permet de récupérer des transactions d’un [compte Financial Connections](https://docs.stripe.com/api/financial_connections/accounts/object.md). Utilisez les données de transaction pour créer divers produits et solutions, notamment : - Accélérez le processus d’évaluation des risques et améliorez l’accès de vos utilisateurs au crédit et à d’autres services financiers. - Réduire la fraude et le risque lié à l’inscription de nouveaux utilisateurs en évaluant leur historique de transactions, et comprendre les flux entrants et sortants de leurs comptes financiers. - Aidez vos utilisateurs à suivre leurs dépenses et à gérer leurs factures et leurs finances. ## Before you begin Vous devez disposer d’une inscription Financial Connections pour accéder à transactions en mode production. Accédez aux [paramètres de votre Dashboard](https://dashboard.stripe.com/settings/financial-connections) pour vérifier l’état de votre inscription ou entamer le processus d’inscription. Les données de test Financial Connections sont disponibles en permanence. ## Créer un client [Recommended] [Server-side] Nous vous recommandons de créer un objet *Customer* (Customer objects represent customers of your business. They let you reuse payment methods and give you the ability to track multiple payments) 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](https://docs.stripe.com/api/financial_connections/accounts/list.md). En renseignant une adresse e-mail et un numéro de téléphone 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](https://support.stripe.com/questions/link-for-financial-connections-support-for-businesses). ```curl curl https://api.stripe.com/v1/customers \ -u "<>:" \ -d email={{CUSTOMER_EMAIL}} \ -d phone={{CUSTOMER_PHONE}} ``` ## Demander l'accès aux transactions d'un compte [Côté serveur] 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](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md), [faciliter des virements Connect](https://docs.stripe.com/financial-connections/connect-payouts.md) ou [créer d’autres produits reposant sur les données](https://docs.stripe.com/financial-connections/other-data-powered-products.md). 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](https://docs.stripe.com/financial-connections/fundamentals.md#data-permissions). L’utilisateur peut consulter l’ensemble des autorisations d’accès aux données demandées dans le [flux d’authentification](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow). 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. #### Payment Intents ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -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" ``` #### Setup Intents ```curl curl https://api.stripe.com/v1/setup_intents \ -u "<>:" \ -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" ``` #### Sessions ```curl curl https://api.stripe.com/v1/financial_connections/sessions \ -u "<>:" \ -d "account_holder[type]=customer" \ -d "account_holder[customer]={{CUSTOMER_ID}}" \ -d "permissions[]=transactions" ``` #### Checkout ```curl curl https://api.stripe.com/v1/checkout/sessions \ -u "<>:" \ -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" ``` #### Factures ```curl curl https://api.stripe.com/v1/invoices \ -u "<>:" \ -d "customer={{CUSTOMER_ID}}" \ -d "payment_settings[payment_method_types][]=us_bank_account" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=transactions" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=payment_method" ``` #### Abonnements ```curl curl https://api.stripe.com/v1/subscriptions \ -u "<>:" \ -d customer={{CUSTOMER_ID}} \ -d "payment_settings[payment_method_types][]=us_bank_account" \ -d "payment_settings[payment_method_options][us_bank_account][financial_connections][permissions][]=transactions" \ -d "payment_settings[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](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md?dashboard-or-api=dashboard#access). ## S'abonner aux données de transaction [Côté serveur] 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](https://docs.stripe.com/financial-connections/ach-direct-debit-payments.md#finding-the-financial-connections-account-id) ou le guide sur les [sessions Financial Connections](https://docs.stripe.com/financial-connections/other-data-powered-products.md?platform=web#collect-an-account). Abonnez-vous aux données de transaction en appelant l’[API d’abonnement](https://docs.stripe.com/api/financial_connections/accounts/subscribe.md) : ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/subscribe \ -u "<>:" \ -d "features[]=transactions" ``` > Les abonnements ne sont pas autorisés sur les comptes inactifs. En plus d’activer un abonnement aux données de transactions futures, cet appel à l’API lance automatiquement une actualisation des transactions : ```json { "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](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-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](https://docs.stripe.com/api/events/types.md#event_types-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. ## Récupérer les transactions [Côté serveur] Une fois que Stripe a actualisé les transactions du compte, vous pouvez les récupérer à l’aide de l’[API Transactions List](https://docs.stripe.com/api/financial_connections/transactions/list.md) : ```curl curl -G https://api.stripe.com/v1/financial_connections/transactions \ -u "<>:" \ -d "account={{FINANCIALCONNECTIONSACCOUNT_ID}}" ``` Stripe renvoie une liste [paginée](https://docs.stripe.com/api/pagination.md) comprenant jusqu’à 180 jours d’historique des transactions sur un compte, en fonction de l’institution financière du compte. ```json { "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](https://docs.stripe.com/api/financial_connections/transactions/object.md#financial_connections_transaction_object-status) `pending` (en attente), `posted` (comptabilisée), ou `void` (annulée). Les informations incluses dans le champ [description](https://docs.stripe.com/api/financial_connections/transactions/object.md#financial_connections_transaction_object-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](https://docs.stripe.com/api/events/types.md#event_types-financial_connections.account.refreshed_transactions) observé : ```curl curl -G https://api.stripe.com/v1/financial_connections/transactions \ -u "<>:" \ -d "account={{FINANCIALCONNECTIONSACCOUNT_ID}}" \ -d "transaction_refresh[after]=fctxnref_1LXp8WGxLVUXRs6Hkc5PNUXf" ``` Voici un exemple d’intégration de [webhook](https://docs.stripe.com/webhooks.md#webhook-endpoint-def) qui récupère et enregistre uniquement les données de transaction nouvelles ou mises à jour : #### Python ```python 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 = client.v1.financial_connections.transactions.list(params={ '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) ``` ## Optional: Se désabonner des données de transaction Vous pouvez démarrer, annuler et reprendre un abonnement à tout moment. Pour annuler un abonnement, appelez l’[API Unsubscribe](https://docs.stripe.com/api/financial_connections/accounts/unsubscribe.md) : ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/unsubscribe \ -u "<>:" \ -d "features[]=transactions" ``` Pour reprendre l’abonnement, appelez à nouveau l’[API Subscribe](https://docs.stripe.com/api/financial_connections/accounts/subscribe.md). ## Optional: Actualisation des transactions à la demande Il existe deux alternatives à l’[abonnement](https://docs.stripe.com/financial-connections/transactions.md#subscribe-to-transactions) aux mises à jour quotidiennes : le préchargement des données de transaction et les actualisations à la demande. Vous pouvez utiliser ces méthodes si vous souhaitez uniquement récupérer les données de transaction une seule fois, par exemple pour un cas d’usage, comme l’évaluation du risque de crédit. Ces méthodes ne sont pas incompatibles avec le maintien d’un abonnement, mais la plupart des institutions financières ne mettent pas à jour les transactions plusieurs fois par jour. ### Récupérer les données de transaction de manière anticipée Précisez si vous souhaitez récupérer les transactions du compte *avant* la collecte du compte. Le processus d’actualisation est alors lancé dès que votre utilisateur connecte son compte dans le [flux d’authentification](https://docs.stripe.com/financial-connections/fundamentals.md#authentication-flow). Configurez le paramètre `prefetch` lorsque vous avez besoin des données de transaction de chaque compte associé pour vous assurer de les recevoir au plus vite. Le paramètre `prefetch` est disponible sur toutes les API qui prennent en charge Financial Connections. ```curl curl https://api.stripe.com/v1/payment_intents \ -u "<>:" \ -d amount=20000 \ -d currency=usd \ -d "payment_method_types[]=us_bank_account" \ -d "payment_method_options[us_bank_account][financial_connections][prefetch][]=transactions" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=payment_method" \ -d "payment_method_options[us_bank_account][financial_connections][permissions][]=transactions" ``` Après avoir initié une actualisation des transactions à l’aide de `prefetch`, [attendez la fin de l’opération](https://docs.stripe.com/financial-connections/transactions.md#wait-for-completion). ### Lancer une actualisation à la demande Utilisez [l’API Refresh](https://docs.stripe.com/api/financial_connections/accounts/refresh.md) pour lancer des actualisations des transactions à la demande *après* l’encaissement du compte, et récupérer des informations sur les transactions d’un compte en particulier à votre convenance, ce qui vous permet de reporter la décision à un moment ultérieur. ```curl curl https://api.stripe.com/v1/financial_connections/accounts/{{FINANCIALCONNECTIONSACCOUNT_ID}}/refresh \ -u "<>:" \ -d "features[]=transactions" ``` > Les actualisations ne sont pas autorisées sur les comptes inactifs. Après avoir initié une actualisation des transactions à l’aide de l’API Refresh, [attendez la fin de l’opération](https://docs.stripe.com/financial-connections/transactions.md#wait-for-completion). Une fois les transactions actualisées, Stripe définit la disponibilité des actualisations futures via le champ [transaction_refresh.next_refresh_available_at](https://docs.stripe.com/api/financial_connections/accounts/object.md#financial_connections_account_object-transaction_refresh-next_refresh_available_at). Vérifiez ce champ avant d’initier une nouvelle actualisation des transactions pour vous assurer que des actualisations sont effectivement disponibles actuellement. Si vous tentez une actualisation alors que la valeur est `null` (comme c’est toujours le cas lorsque l’actualisation est en attente ou que le compte est inactif) ou que l’heure actuelle est inférieure à l’horodatage `next_refresh_available_at`, l’actualisation ne sera pas initiée. > Dans le cas improbable où une actualisation échoue, le champ `error` sur le hachage d’actualisation est une fonctionnalité bêta qui renseigne sur la cause de l’échec et indique les étapes suivantes recommandées. Si vous souhaitez l’utiliser, contactez-nous par [e-mail](mailto:financial-connections-beta+refresh-error@stripe.com) pour obtenir votre accès.