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

Comment et dans quels scénarios restituer des fonds issus de crédits reçus sur votre compte financier Treasury.

L’annulation d’un ReceivedCredit entraîne la création d’une CreditReversal. Vous ne pouvez annuler des ReceivedCredits que sous certaines conditions (détaillées dans le tableau suivant). Pour savoir si vous pouvez annuler un ReceivedCredit, vous devez tenir compte du réseau utilisé et du flux source.

Le sous-hachage reversal_details de l’objet ReceivedCredit peut présenter les combinaisons de valeurs suivantes, qui permettent de déterminer si vous pouvez annuler ou non le ReceivedCredit.

MOTIF DE LA RESTRICTION	DATE LIMITE (HORODATAGE EPOCH)	EXEMPLE DE SCÉNARIO
`source_flow_restricted`	`null`	Un `ReceivedCredit` du réseau Stripe qui est le résultat d’un flux autre qu’un `OutboundPayment`. Stripe ne permet pas aux utilisateurs d’annuler ces `ReceivedCredits`.
`network_restricted`	`null`	Les contraintes du réseau empêchent Stripe d’autoriser l’annulation de certains `ReceivedCredits`, notamment les `ReceivedCredit` provenant de virements bancaires.
`null`	`{{TIMESTAMP}}`	Un `ReceivedCredit`, qui est annulable, mais uniquement jusqu’à l’horodatage indiqué dans `deadline`. Les `ReceivedCredits` ACH ne peuvent être annulés que pendant un certain délai.
`deadline_passed`	`{{TIMESTAMP}}`	Un `ReceivedCredit` qui était annulable jusqu’à l’horodatage spécifié dans `deadline`, mais qui n’est plus annulable car la `deadline`est échue. Après leur création, les `ReceivedCredits` ACH ne peuvent être annulés que pendant une durée limitée.
`already_reversed`	`null`	Un `ReceivedCredit`qui est déjà annulé possède cette `restricted_reason`. Dans certains cas, sa valeur `deadline` peut être non nulle.
`null`	`null`	Vous pouvez annuler des `ReceivedCredits` à tout moment si `restricted_reason` et `deadline` ont la valeur `null`.

Créer un CreditReversal

Utilisez POST /v1/treasury/credit_reversals pour créer un CreditReversal. Définissez le paramètre received_credit dans le corps de la requête sur la valeur de l’ID du ReceivedCredit à annuler.

Remarque

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

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

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

{
    "id": "{{CREDIT_REVERSAL_ID}}",
    "object": "credit_reversal",
    "amount": 1000,
    "currency": "usd",
    "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
    "hosted_regulatory_receipt_url": "https://payments.stripe.com/regulatory-receipt/{{URL_ID}}",
    "livemode": false,
    "metadata": {
        "csr_id": "CSR-12"

Récupérer un CreditReversal

Utilisez GET /v1/treasury/credit_reversals/{{CREDIT_REVERSAL_ID}} pour récupérer le CreditReversal avec l’ID associé.

La réponse renvoie l’objet CreditReversal spécifique.

JSON (commenté)
{
  "id": "{{CREDIT_REVERSAL_ID}}",
  "object": "credit_reversal",
  "livemode": "{{Boolean}}",
  "created": "{{Timestamp}}",
  "financial_account": "{{FINANCIAL_ACCOUNT_ID}}",
  "amount": 1000,
  "currency": "usd",
  // The ReceivedCredit that was reversed
  "received_credit": "{{RECEIVED_CREDIT_ID}}",
  // The rails used to reversed. Always the same as that of the ReceivedCredit
  "network": "ach",
  "status": "processing" | "posted",
  "status_transitions": {
    "posted_at": null | "{{Timestamp}}",
  },
  // Transaction representing balance impact of the CreditReversal
  "transaction": "{{TRANSACTION_ID}}",
  // A unique, Stripe-hosted direct link to the regulatory receipt for the CreditReversal
  "hosted_regulatory_receipt_url": "{{Url}}",
  // A map of String-String intended for users to use custom data
  "metadata": {},
}

Répertorier les CreditReversals

Utilisez GET /v1/treasury/credit_reversals pour récupérer la liste des CreditReversals 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 ReceivedCredit à l’aide du paramètre received_credit.

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

La requête suivante renvoie les trois annulations de crédits les plus récentes avec un état posted pour le compte financier spécifié.

Sauf échec de l’opération, la réponse renvoie la liste pertinente des objets CreditReversal.

Tester les CreditReversals

Pour tester les CreditReversals, vous devez d’abord créer des ReceivedCredits de test. Ensuite, utilisez POST /v1/treasury/credit_reversals et spécifiez l’ID du ReceivedCredit de test dans le paramètre received_credit pour créer un CreditReversal de test.

Webhooks CreditReversal

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

treasury.credit_reversal.created à la création du CreditReversal.
treasury.credit_reversal.posted lors de la comptabilisation du CreditReversal.