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.

Les transferts entrants sont effectués sous 2 à 4 jours ouvrables, sauf si vous utilisez la fonctionnalité de règlement ACH le jour même. Pour plus d’informations, consultez le guide dédié aux délais de transfert de fonds.

Remarque

Vous pouvez utiliser les transferts entrants pour transférer des fonds à partir du compte bancaire d’un titulaire de compte financier. Pour accepter des fonds provenant d’un tiers sur un compte financier, effectuez un prélèvement ACH sur le solde des paiements, suivi d’un virement sur le compte financier.

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 : la source de fonds qu’utilisera le transfert entrant. Vous devez d’abord configurer le moyen de paiement associé au compte pour la prise en charge des flux entrants et vérifier les informations du compte bancaire à l’aide d’un SetupIntent. Vous pouvez également utiliser un BankAccount existant, préalablement vérifié et configuré en tant qu’ExternalAccount. Que vous utilisiez un moyen de paiement ou un compte bancaire, vous devez obtenir l’autorisation du titulaire du compte pour débiter les fonds du compte.

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 does not 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.

L’utilisation de l’ACH le jour même permet aux fonds d’arriver sur le compte financier à l’origine de la transaction le même jour ouvrable si l’appel InboundTransfer est effectué avec succès avant l’heure limite. Pour utiliser l’ACH le jour même, attribuez la valeur same_day au paramètre origin_payment_method_options.us_bank_account.ach.submission.

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

Avec le règlement rapide des virements entrants ACH le jour même, votre plateforme peut s’exposer à un risque financier plus important qu’avec les virements entrants ACH standard. Par exemple, un compte connecté peut initier un transfert entrant qui est retourné en raison d’une insuffisance de fonds sur le compte source. Le règlement le jour même augmente le risque que les fonds soient retirés du compte financier avant qu’ils ne soient renvoyés. Si le compte connecté retire les fonds et que le retour entraîne un solde négatif sur le compte financier, votre plateforme est responsable de ce découvert.

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, l’objet InboundTransfer prend d’abord l’état processing. Vous recevez des webhooks pour chaque changement d’état pertinent, et la récupération de l’objet InboundTransfer après sa création renvoie l’état attendu.

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

Treasury propose également un endpoint return qui permet de simuler un InboundTransfer qui aboutit mais qui est restitué par la suite.

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