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

Comment et dans quels scénarios récupérer des fonds prélevés d'un compte financier Treasury par un titulaire de compte externe.

La restitution des fonds d’un ReceivedDebit entraîne la création d’un DebitReversal. Vous ne pouvez récupérer les fonds des ReceivedDebit que sous certaines conditions (détaillées dans le tableau suivant). Pour savoir si vous pouvez restituer les fonds d’un ReceivedDebit, vous devez tenir compte du réseau utilisé et du flux source.

Le sous-hachage reversal_details de la ressource ReceivedDebit peut présenter la combinaison de valeurs suivante, qui détermine si vous pouvez restituer ou non le ReceivedDebit.

MOTIF DE LA RESTRICTION	DATE LIMITE (HORODATAGE EPOCH)	EXEMPLE DE SCÉNARIO
`null`	7940828047	Un `ReceivedDebit` dont vous pouvez restituer les fonds, mais uniquement jusqu’à l’horodatage indiqué dans `deadline`. Les `ReceivedDebits` ACH ne peuvent être restitués que pendant un certain délai.
`deadline_passed`	1629480538	Un `ReceivedDebit` dont les fonds pouvaient être restitués jusqu’à l’horodatage spécifié dans `deadline`, mais qui ne peut plus être restitué via l’API car la `deadline` est échue. Après leur création, les `ReceivedDebits` ACH ne peuvent être restitués que pendant une durée limitée.
`already_reversed`	aucun	Un `ReceivedDebit` qui a déjà été restitué. Dans certains cas, sa valeur `deadline` peut être non nulle.
`source_flow_restricted`	aucun	Un `ReceivedDebit` qui ne peut pas être restitué car son `source_flow` n’est pas annulable.

Délai de restitution

Vous disposez d’environ 1 jour ouvrable pour restituer des prélèvements ACH via l’API après leur réception. Passé ce délai, les fonds du prélèvement ACH pourront peut-être encore être restitués, mais sans aucune garantie. Si le délai est écoulé et que vous souhaitez demander une restitution des fonds, contactez le service de support.

Pour restituer des fonds ReceivedDebit générés par des cartes Issuing, consultez le guide Litiges Issuing.

Créer un DebitReversal

Utilisez POST /v1/treasury/debit_reversals pour créer un DebitReversal. Spécifiez l’ID du ReceivedDebit à annuler avec le paramètre received_debit dans le corps de la requête.

Remarque

Vous ne pouvez pas mettre à jour des objets DebitReversals ; vous devez donc définir les métadonnées facultatives lors de leur création.

La requête suivante permet de créer un DebitReversal à partir de la valeur de l’ID du ReceivedDebit du paramètre obligatoire received_debit. Elle définit également la valeur des métadonnées (facultatif).

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

{
  "id": "{{DEBIT_REVERSAL_ID}}",
  "object": "debit_reversal",
  "amount": 1000,
  "currency": "usd",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{URL_ID}}",
  "linked_flows": null,
  "livemode": false,
  "metadata": {},
  "network": "ach",
  "received_debit": "{{RECEIVED_DEBIT_ID}}",
  "resolution": null,
  "status": "processing",
  "status_transitions": {
    "completed_at": null
  },
  "transaction": "{{TRANSACTION_ID}}"
}

Récupérer un DebitReversal

Utilisez GET /v1/treasury/debit_reversals/{{DEBIT_REVERSAL_ID}} pour récupérer le DebitReversal avec l’ID associé.

Sauf échec de l’opération, la réponse renvoie l’objet DebitReversal identifié.

JSON (commenté)
{
  "id": "{{DEBIT_REVERSAL_ID}}",
  "object": "debit_reversal",
  "livemode": true | false,
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  // the ReceivedDebit being returned
  "received_debit": "{{RECEIVED_DEBIT_ID}}",

Lister les DebitReversals

Utilisez GET /v1/treasury/debit_reversals pour récupérer la liste des DebitReversals du compte financier avec l’ID fourni dans le paramètre obligatoire financial_account. Vous pouvez filtrer la liste en utilisant les paramètres de liste standard, par status ou par ID ReceivedDebit à l’aide du paramètre received_debit.

{
  // Standard list parameters
  "limit", "starting_after", "ending_before",
  // Filter by financial account (Required)
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  // Filter by `status`
  "status": "processing" | "canceled" | "completed"
  // Filter by ReceivedDebit
  "received_debit": "{{RECEIVED_DEBIT_ID}}",
}

La requête suivante permet de récupérer les trois derniers objets DebitReversal du compte financier identifié.

Tester les DebitReversals

Pour tester des DebitReversals, vous devez d’abord créer un ReceivedDebit de test. Ensuite, utilisez POST /v1/treasury/debit_reversals et spécifiez l’ID du ReceivedDebit dans le paramètre received_debit pour créer un DebitReversal de test.

Webhooks DebitReversal

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

treasury.debit_reversal.created à la création d’un DebitReversal.
treasury.debit_reversal.completed lorsque le DebitReversal a été effectué.