Transférer des fonds à l'aide d'objets OutboundTransfer

Un objet OutboundTransfer permet de faciliter les transferts de fonds depuis un compte financier. Utilisez un OutboundTransfer pour envoyer des fonds via le réseau ACH ou via un virement bancaire national vers un compte bancaire externe détenu par un de compte connecté.

En règle générale, les transferts sortants arrivent à la banque destinataire dans un délai maximal de 2 jours ouvrables, qu’il s’agisse d’un virement bancaire ou ACH.

Pour en savoir plus, consultez le guide sur la chronologie de transfert de fonds.

Les OutboundTransfers prennent en charge les moyens de paiement de type us_bank_account. Vous pouvez également utiliser un BankAccount existant qui appartient au marchand en tant qu’ExternalAccount.

Créer un OutboundTransfer

Utilisez POST /v1/treasury/outbound_transfers pour créer un OutboundTransfer pour le compte financier avec l’ID associé. Sur l’ensemble des paramètres disponibles, quatre sont obligatoires :

• amount : montant du transfert en centimes.
• currency : code de devise ISO à trois lettres.
• financial_account : l’ID du compte financier source d’où proviennent les fonds.
• destination_payment_method : l’ID du PaymentMethod de destination ou du BankAccount qui va recevoir les fonds.
• destination_payment_method_data : compte financier utilisé pour la réception des fonds.

{
  // The source financial account to pull funds from.
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // The amount to send. 10.00 USD in this case.
  "amount": 1000,
  "currency": "usd",
  // The destination PaymentMethod or BankAccount.
  // This should be nil if destination_payment_method is set.
  destination_payment_method_data: {
  type: "financial_account", // us_bank_account is not supported
  financial_account: "{{FINANCIAL_ACCOUNT_ID}}",
  },

  // This should be nil if destination_payment_method_data is set.
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}"  | "{{BANK_ACCOUNT_ID}}",
  // Optionally, to explicitly specify a network, override the `network` value
  // This should be nil if destination_payment_method_data is set.
  "destination_payment_method_options": {
    "us_bank_account": {
      "network": "ach" | "us_domestic_wire"
    }
  },
  // A description visible on the external bank statement.
  "statement_descriptor": "Bank xfer",
  // An optional internal description to identify this OutboundTransfer
  "description": "Transfer to my external account",
  // Stripe doesn't support updating originated transfers after creation.
  // You can only set metadata at creation.
  "metadata": nil | Hash,
}

La requête suivante permet de créer un OutboundTransfer sur un PaymentMethod associé à un compte et dont les fonds proviennent du compte financier identifié.

curl https://api.stripe.com/v1/treasury/outbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d amount=1000 \
  -d currency=usd \
  -d destination_payment_method=
"{{PAYMENT_METHOD_ID}}" \
  -d statement_descriptor="Test xfer" \
  -d "destination_payment_method_options[us_bank_account][network]"=ach

Sauf échec de l’opération, la réponse renvoie le nouvel objet OutboundTransfer.

{
    "id": "{{OUTBOUND_TRANSFER_ID}}",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": true,
    "created": 1648479987,
    "currency": "usd",
    "description": null,
    "destination_payment_method": "{{PAYMENT_METHOD_ID}}" | null,
    "destination_payment_method_details": {

ACH le jour même

L’utilisation de la fonctionnalité ACH le jour même permet d’envoyer des fonds qui arrivent le jour ouvrable même si l’appel OutboundTransfer aboutit avant l’heure limite. Pour utiliser la fonctionnalité ACH le jour même, définissez le paramètre destination_payment_method_options.us_bank_account.network sur ach et le paramètre destination_payment_method_options.us_bank_account.ach.submission sur same_day.

Virement bancaire : numéros de routage

Pour les virements bancaires, certaines banques peuvent utiliser un numéro de routage distinct des virements ACH. Par conséquent, vous pourriez recevoir une erreur lors de la création du virement si le numéro de routage du moyen de paiement ne prend pas en charge les virements bancaires. Le cas échéant, vous devez ajouter un nouveau moyen de paiement avec le numéro de routage de votre banque.

Virement bancaire : adresse du bénéficiaire

Les virements bancaires nécessitent des métadonnées ACH ainsi que le nom du bénéficiaire et son adresse de facturation. L’adresse est celle du titulaire du compte recevant le virement et non l’adresse de sa banque.

Lorsque vous saisissez l’adresse billing_details.address pour un moyen de paiement, tous les champs d’adresse doivent être renseignés. Si vous tentez d’effectuer un virement et que les champs de l’adresse billing_details.address sont incomplets, une erreur se produit.

Récupérer un OutboundTransfer

Utilisez GET /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}} pour récupérer les informations de l’OutboundTransfer avec l’ID associé.

La requête suivante permet de récupérer l’OutboundTransfer avec l’ID associé en développant les informations de la Transaction.

curl -G https://api.stripe.com/v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}} \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d "expand[]"=transaction

Sauf échec de l’opération, la réponse renvoie l’objet OutboundTransfer et l’ID associé. 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": "{{OUTBOUND_TRANSFER_ID}}",
  "object": "outbound_transfer",
  "livemode": Boolean,
  "created": Timestamp,
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}", // Expandable
  "amount": 1000,
  "currency": "usd",
  "destination_payment_method": "{{PAYMENT_METHOD_ID}}",
  "description": "Transfer to my external account",

Annuler un OutboundTransfer

Utilisez POST /v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel pour annuler l’OutboundTransfer avec l’ID associé. L’objet OutboundTransfer inclut un paramètre cancelable dont la valeur booléenne indique si vous pouvez ou non annuler le transfert. Une fois que vous avez soumis un OutboundTransfer au réseau, la valeur cancelable bascule sur false et cet endpoint envoie une erreur pour le transfert.

curl -X POST https://api.stripe.com/v1/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/cancel \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
"

Sauf échec de l’opération, la réponse renvoie l’objet OutboundTransfer avec l’état canceled.

{
    "id": "{{OUTBOUND_TRANSFER_ID}} ",
    "object": "outbound_transfer",
    "amount": 1000,
    "cancelable": false,
    "created": 1648487177,
    "currency": "usd",
    ...
    "status": "canceled",
    "status_transitions": {
        "canceled_at": 1648487198,
        "failed_at": null,
        "posted_at": null,
        "returned_at": null
    },
    "transaction": "{{TRANSACTION_ID}}"
}

Répertorier les OutboundTransfers

Utilisez GET /v1/treasury/outbound_transfers pour répertorier les OutboundTransfers envoyés depuis le compte financier avec l’ID du paramètre financial_account. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard ou par status.

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

La requête suivante permet de récupérer les OutboundTransfers provenant du compte financier identifié. Les paramètres inclus limitent la réponse aux trois premiers transferts suivant l’OutboundTransfer dont vous avez fourni l’ID.

curl -G https://api.stripe.com/v1/treasury/outbound_transfers \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -H "Stripe-Account: 
{{CONNECTED_ACCOUNT_ID}}
" \
  -d financial_account=
"{{FINANCIAL_ACCOUNT_ID}}" \
  -d limit=3 \
  -d starting_after={{OUTBOUND_TRANSFER_ID}}

Sauf échec de l’opération, la réponse renvoie la liste des objets OutboundTransfer qui respectent les critères de filtre.

États OutboundTransfer

Le tableau suivant détaille chaque status ainsi que les éventuels états de transition des OutboundTransfers.

Tester les OutboundTransfers

En mode test, vous pouvez indiquer le destination_payment_method comme moyen de paiement de test. Lorsque vous testez votre intégration, vous pouvez créer vos propres PaymentMethods en mode test ou utiliser nos ID de test.

Dans tous les cas, la réponse de l’objet OutboundTransfer présente l’état processing. Stripe déclenche des webhooks pour les changements d’état pertinents, et la récupération de l’objet OutboundTransfer après sa création renvoie l’état attendu.

Endpoints d’aide au test des objets OutboundTransfer

Stripe fournit des endpoints qui vous aident à tester des OutboundTransfers dans différents états. Après avoir créé un OutboundTransfer, utilisez ces endpoints pour le faire directement passer à l’état posted, failed, canceled ou returned.

• Utilisez l’endpoint de publication de test pour faire passer l’état de l’objet OutboundTransfer identifié de processing (en cours de traitement) à posted (publié).

  POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/post

• Utilisez l’endpoint d’échec de test pour faire passer l’état de l’objet OutboundTransfer identifié de processing (en cours de traitement) à failed (en échec).

  POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/fail

• Utilisez l’endpoint de renvoi de test pour faire passer l’état de l’objet OutboundTransfer identifié de posted (publié) à returned (renvoyé).

  POST /v1/test_helpers/treasury/outbound_transfers/{{OUTBOUND_TRANSFER_ID}}/return

Ces endpoints sont particulièrement utiles pour tester des scénarios d’erreur, tels que des restitutions, qui nécessiteraient autrement une action extérieure.

Pour l’endpoint return, incluez le paramètre facultatif returned_details.code dans le corps de la requête pour indiquer le motif de la restitution du transfert. Si vous ne fournissez pas ce paramètre, le transfert affiche par défaut le code de retour declined.

{
  "returned_details": {
    "code": "account_closed" |
          "account_frozen" |
          "bank_account_restricted" |
          "bank_ownership_changed" |
          "could_not_process" |
          "invalid_account_number" |
          "incorrect_account_holder_name" |
          "invalid_currency" |
          "no_account" |
          "declined"
  }
}

Nous fournissons également un endpoint de modification de test pour simuler la publication des informations de suivi d’un Outbound Transfer de test. Le champ tracking_details peut uniquement être défini pour les objets de test.

Dans tous les cas, Stripe déclenche des webhooks pour chaque changement d’état pertinent. La récupération de l’objet OutboundTransfer après le changement d’état renvoie l’état attendu.

Webhooks OutboundTransfer

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

• treasury.outbound_transfer.created à la création d’un OutboundTransfer.
• treasury.outbound_transfer.{{new_status}} lorsqu’un OutboundTransfer change d’état. Il peut prendre les états suivants :
  • treasury.outbound_transfer.posted
  • treasury.outbound_transfer.failed
  • treasury.outbound_transfer.returned
  • treasury.outbound_transfer.canceled
• treasury.outbound_transfer.expected_arrival_date_updated en cas de modification de la date expected_arrival_date d’un OutboundTransfer.
• treasury.outbound_transfer.tracking_details_updated lorsque les informations de suivi d’un OutboundTransfer sont mis à jour.