Transfert de fonds avec Treasury à l'aide d'objets InboundTransfer

Comment transférer des fonds vers un compte financier Treasury depuis un autre de vos comptes.

Les transferts entrants sont des transferts de fonds effectués à l’aide du réseau ACH entre un compte bancaire des États-Unis externe et un compte financier. Ces transferts sont effectués à l’aide des objets InboundTransfer.

Inbound transfers take 2-4 business days to complete unless you’re using the same-day ACH capability. For more information, see the Money movement timelines guide.

Remarque

You can use inbound transfers to move funds from a financial account owner’s bank account. To accept funds from an external party into a financial account, use an ACH Debit into the Payments balance, followed by a payout to the financial account.

Créer un InboundTransfer

Utilisez POST /v1/treasury/inbound_transfers pour créer un objet InboundTransfer qui représente des transferts de type « pull » réalisés sur l’un de vos comptes externes à destination de votre compte financier. Un InboundTransfer vous permet ainsi de transférer des fonds sur votre compte financier en débitant votre compte bancaire externe des États-Unis. Votre requête doit inclure les paramètres suivants :

amount : le montant en centimes à transférer sur le compte financier.
currency : le code de devise ISO à trois lettres (usd étant à ce jour la seule valeur prise en charge).
financial_account : l’ID du compte financier sur lequel les fonds sont transférés.
origin_payment_method: The source of funds for the inbound transfer. You must first set up the account-attached payment method for inbound flows and verify the bank account using a SetupIntent. Alternatively, you can use an existing BankAccount previously set up as a verified ExternalAccount. Whether you use a payment method or a bank account, you need the account owner’s permission to debit the funds from the account.

Le code JSON suivant affiche les données que vous pouvez inclure dans le corps de votre requête.

{
  // The source PaymentMethod or BankAccount. Funds are pulled from this account.
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}" | "{{BANK_ACCOUNT_ID}}",
  // The destination FinancialAccount. Funds arrive in this account.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to debit. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // An optional, internal description for the InboundTransfer.
  "description": "Funds for vendor payment payment_234281",
  // An optional descriptor for the InboundTransfer to send
  // to the network with the debit request. Max 10 characters
  "statement_descriptor": "payment_1",
  // Stripe doesn't support updating InboundTransfers after creation.
  // You can only set metadata at creation time.
  "metadata": null | {{Hash}}
}

La requête suivante déclenche un virement de 200 USD sur le compte financier correspondant à l’ID fourni à l’aide d’un moyen de paiement associé au compte. La valeur de l’en-tête Stripe-Account permet d’identifier le compte Stripe qui détient le compte financier et le moyen de paiement.

Sauf échec de l’opération, la réponse renvoie l’objet InboundTransfer qui inclut une hosted_regulatory_receipt_url permettant au titulaire du compte de consulter les informations relatives à la transaction sur votre plateforme.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Funds for repair",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{IBT_URL}}",
    "linked_flows": null,
    "livemode": false,
    "metadata": {},
    "origin_payment_method": "{{PAYMENT_METHOD_ID}}",
    ...
    "statement_descriptor": "Invoice 12",
    "status": "processing",
    ...
}

Avertissement

Dans de rares cas, Stripe peut annuler une demande d’InboundTransfer en raison de divers facteurs de risque. Dans ces cas, la demande API est erronée et renvoie le code de réponse 402. Le message d’erreur fournit des détails supplémentaires sur les facteurs de risque qui ont conduit à l’intervention.

ACH le jour même

Version bêta privée

ACH le jour même existe actuellement en version bêta avec une disponibilité limitée, sous réserve de l’examen et de l’approbation de Stripe. Pour demander un accès, envoyez un e-mail à treasury-support@stripe.com.

Si vous n’y avez pas accès, les appels à l’API qui incluent des fonctionnalités ou des paramètres ACH le jour même renvoient une erreur.

Using same-day ACH enables funds to arrive in the originating financial account within the same business day if the InboundTransfer call successfully completes before the cutoff time. To use same-day ACH, set the origin_payment_method_options.us_bank_account.ach.submission parameter to same_day.

Risque de fraude associé au traitement des transactions ACH effectuées le jour même

The fast settlement of same-day ACH inbound transfers can expose your platform to greater financial risk than from standard ACH inbound transfers. For example, a connected account can initiate an inbound transfer that gets returned due to insufficient funds in the source account. Same-day settlement leaves more time to potentially withdraw the funds from the financial account before they’re returned. If the connected account withdraws the funds, and then the return causes a negative balance in the financial account, your platform is responsible.

Lorsque les systèmes de prévention de la fraude de Stripe considèrent qu’un transfert entrant présente un risque élevé, la demande de création échoue avec une erreur :

{
  "error": {
    "type": "invalid_request_error",
    "message_code": "inbound_transfer_not_same_day_eligible",
    "message": "This transaction is not eligible for same-day availability at this time. Please try again with `standard` ACH submission."
  }
}

Lorsque vous rencontrez une erreur avec le code de message inbound_transfer_not_same_day_eligible, relancez la requête avec le paramètre origin_payment_method_options.us_bank_account.ach.submission défini surstandard.

Récupérer un InboundTransfer

Utilisez GET /v1/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}} pour récupérer l’objet InboundTransfer avec l’ID associé.

Le code JSON suivant affiche les données que vous pouvez inclure dans le corps de votre requête. Certains des paramètres de la réponse comportent des informations supplémentaires qui ne sont renvoyées que si vous les ajoutez comme valeurs au paramètre expand[]. Les champs que vous pouvez développer affichent le commentaire “Expandable”, comme illustré dans l’exemple de réponse suivant. Pour en savoir plus sur le développement des objets renvoyés, consultez la section consacrée à ce sujet.

{
  "id": "{{INBOUND_TRANSFER_ID}}",
  "object": "inbound_transfer",
  "livemode": false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  // The only current valid PaymentMethod type for InboundTransfers is us_bank_account
  "origin_payment_method": "{{PAYMENT_METHOD_ID}}",

La requête suivante permet de récupérer l’InboundTransfer avec la valeur id de l’{{INBOUND_TRANSFER_ID}}. Avec transaction dans le tableau expand[] du corps, les informations développées pertinentes sont renvoyées.

Sauf échec de l’opération, la réponse renvoie l’objet InboundTransfer avec les informations développées.

{
    "id": "{{INBOUND_TRANSFER_ID}}",
    "object": "inbound_transfer",
    "amount": 20000,
    "created": 1648071297,
    "currency": "usd",
    "description": "Inbound transfer",
    "failure_details": null,
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{INBOUND_TRANSFER_ID}}",

Répertorier les InboundTransfers

Utilisez GET /v1/treasury/inbound_transfers pour récupérer tous les InboundTransfers du compte financier avec l’ID associé. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard ou le status.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by status
  "status": "processing" | "succeeded" | "failed",
  // Filter by FinancialAccount (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Required
}

La requête suivante permet de récupérer tous les transferts entrants qui présentent l’état succeeded pour le compte financier avec l’ID {{FINANCIAL_ACCOUNT_ID}}, qui est associé au compte connecté avec l’ID {{CONNECTED_ACCOUNT_ID}}.

Vérifier manuellement les InboundTransfers

Vous pouvez réduire le risque de transferts entrants en retardant leur soumission à nos partenaires bancaires ou en retenant les fonds pendant une période prolongée. Ces retenues peuvent vous donner plus de temps pour examiner les activités potentiellement suspectes. Vous pouvez demander l’accès à la fonctionnalité inbound_transfers.ach.platform_review, et lorsque cette fonctionnalité est activée, les comptes financiers reçoivent tous les transferts entrants avec l’état requires_confirmation.

Vous trouverez ci-dessous un exemple de configuration de cette fonctionnalité sur un nouveau compte financier. Vous pouvez également ajouter d’autres fonctionnalités.

Vous trouverez ci-dessous un exemple de configuration de cette fonctionnalité sur un compte financier existant.

En règle générale, nous envoyons automatiquement les virements entrants à la banque dès leur création. Toutefois, les transferts entrants avec un état requires_confirmation nécessitent une confirmation explicite de l’utilisateur par le biais de l’endpoint /v1/treasury/inbound_transfers/{id}/confirm avant que nous puissions soumettre les transferts à nos partenaires bancaires. Vous pouvez consulter les informations et les indicateurs de risque du transfert entrant avant de confirmer ou d’annuler des transferts entrants à l’état requires_confirmation. Après 5 jours ouvrables, le transfert entrant est automatiquement annulé. Par exemple, Vous avez jusqu’au vendredi suivant pour confirmer un transfert entrant à l’État requires_confirmation créé un vendredi (en supposant qu’il n’y ait pas de jours fériés aux États-Unis).

Utilisez le paramètre funds_availability_delay avec l’endpoint confirm pour préciser le délai (en secondes) de rétention des fonds avant de les débloquer sur le compte financier prévu. Vous pouvez ainsi utiliser ce délai supplémentaire pour vérifier manuellement un transfert. Vous pouvez également utiliser ce champ pour bloquer des fonds au-delà de la période de retour ACH, afin que la banque d’origine ne puisse pas rappeler les fonds une fois qu’ils ont été dépensés. Pour plus de sécurité, définissez la valeur funds_availability_delay sur 432 000, ce qui permet de débloquer les fonds au-delà de la période de retour.

Vous trouverez ci-dessous un exemple d’appel à l’endpoint confirm sans délai de disponibilité.

Vous trouverez ci-dessous un exemple d’appel à l’endpoint confirm avec un délai de disponibilité.

États InboundTransfer

Le tableau suivant détaille chaque état ainsi que les éventuels états de transition.

ÉTAT	DESCRIPTION	PASSE À L’ÉTAT
`processing`	L’`InboundTransfer` a été créé. Stripe peut déclencher le transfert des fonds sur le réseau.	`failed`, `canceled`, `succeeded`, `requires_confirmation`
`requires_confirmation`	L’attribut `InboundTransfer` est créé dans un état d’attente. Stripe n’a pas initié le mouvement de fonds sur le réseau et l’utilisateur doit confirmer explicitement son intention de déclencher ce transfert entrant à l’aide de l’endpoint `/v1/treasury/inbound_transfers/:ID/confirm`.	`processing`, `canceled`
`failed` (définitif)	La confirmation de l’`InboundTransfer` a échoué. Aucune transaction n’a été créée et le `payment_method` n’a pas été débité.	S.O.
`canceled` (définitif)	L’`InboundTransfer` a été annulé avant son envoi au réseau. Stripe annule la transaction et les fonds ne sont pas prélevés sur le compte bancaire externe.	S.O.
`succeeded` (définitif)	L’`InboundTransfer` a abouti et les fonds ont été versés sur le compte. Une transaction a été créée. Les InboundTransfers peuvent être restitués après avoir aboutis si le compte externe récupère les fonds, opération représentée par un ReceivedDebit associé.	S.O.

Tester InboundTransfers

Pour tester votre intégration de bout en bout, utilisez les requêtes SetupIntents de test pour créer un PaymentMethod, puis transmettez ce PaymentMethod dans une requête de création InboundTransfer. Les PaymentMethods valides génèrent des InboundTransfers réussis, tandis que les PaymentMethods non valides (par exemple, ceux qui ne sont pas pris en charge, qui contiennent un compte bancaire non vérifié ou qui n’acceptent pas les flux entrants) produisent les mêmes erreurs qu’en mode production.

Tester les états InboundTransfer

Stripe met également à votre disposition des tokens PaymentMethod de test que vous pouvez utiliser pour déclencher des changements d’état spécifiques :

VALEUR DU PAYMENT_METHOD	RÉSULTAT
`pm_usBankAccount`	Un `InboundTransfer` qui passe de `processing` à `succeeded`.
`pm_usBankAccount_processing`	Un `InboundTransfer` qui reste à l’état `processing`.
`pm_usBankAccount_internalFailure`	Un `InboundTransfer` qui passe de `processing` à `failed`.

Pour vous permettre de tester plus rapidement divers cas particuliers, certains tokens PaymentMethod simulent des types d’échecs spécifiques :

VALEUR DU PAYMENT_METHOD	RÉSULTAT
`pm_usBankAccount_noAccount`	Un `InboundTransfer` qui passe à l’état failed avec l’indication `failure_details.code= "no_account"`.
`pm_usBankAccount_accountClosed`	Un `InboundTransfer` qui passe à l’état `failed` avec l’indication `failure_details.code= "account_closed"`.
`pm_usBankAccount_invalidAccountNumber`	Un `InboundTransfer` qui passe à l’état failed avec l’indication `failure_details.code= "invalid_account_number"`.
`pm_usBankAccount_insufficientFunds`	Un `InboundTransfer` qui passe à l’état failed avec l’indication `failure_details.code= "insufficient_funds"`.
`pm_usBankAccount_debitNotAuthorized`	Un `InboundTransfer` qui passe à l’état failed avec l’indication `failure_details.code= "debit_not_authorized"`.
`pm_usBankAccount_dispute`	Un `InboundTransfer` qui passe de `processing` à `succeeded` et est ensuite contesté. `inbound_transfer.returned` prend la valeur `true` et un `ReceivedDebit` associé est créé.

Dans tous les cas précédents, la réponse InboundTransfer commence à l’état processing. Vous recevez des événements de webhook pour chaque changement d’état pertinent, et la récupération de l’objet InboundTransfer après sa création renvoie l’état attendu.

Vous pouvez également tester l’état d’erreur en transmettant le token pm_usBankAccount_sameDayACHIneligible en tant que PaymentMethod. Cela déclenche un échec de création d’un InboundTransfer (avec envoi ACH le jour même) et renvoie une erreur.

Endpoints de l’assistant de test InboundTransfer

Stripe fournit aussi des endpoints qui facilitent le test des InboundTransfers dans différents états. Créez un InboundTransfer, puis :

Utilisez le endpoint de test succeed pour faire passer directement le transfert à l’état succeeded avec l’ID associé.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/succeed
Utilisez l’endpoint d’échec de test pour faire basculer directement le transfert sur l’état failed avec l’ID associé.
POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/fail

Ces endpoints sont particulièrement utiles pour tester des scénarios d’erreur, tels que des retours, qui nécessiteraient autrement une action de la part du compte externe depuis lequel provenait l’InboundTransfer.

Incluez le paramètre facultatif failure_details.code dans le corps de la requête pour indiquer le motif de l’échec du transfert. Si vous ne fournissez pas ce paramètre, le transfert échoue et affiche par défaut le code d’échec could_not_process.

{
  "failure_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" | // Generic fallback code
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account"
  }
}

Financial Accounts for platforms also provides a return endpoint to simulate an InboundTransfer that succeeds, but is later returned.

Utilisez l’endpoint de renvoi de test pour simuler la restitution de l’objet InboundTransfer avec l’ID associé.

POST /v1/test_helpers/treasury/inbound_transfers/{{INBOUND_TRANSFER_ID}}/return

Tous les endpoints de test déclenchent des webhooks pour chaque changement d’état pertinent, et la récupération de l’objet InboundTransfer après le changement d’état renvoie l’état attendu.

Webhooks InboundTransfer

Stripe émet les événements InboundTransfer suivants à votre endpoint de webhook :

treasury.inbound_transfer.created à la création d’un InboundTransfer.
treasury.inbound_transfer.{{new_status}} lorsqu’un InboundTransfer change d’état. Il peut prendre les états suivants :
- treasury.inbound_transfer.succeeded
- treasury.inbound_transfer.failed