Transfert indépendant

Estimated reading: 6 minutes

🧾 Créer un transfert (Create a Transfer)

La fonction Create a Transfer permet aux partenaires régulés (Agents ou DME, selon le type de compte) de transférer des fonds entre deux comptes de leurs sous-marchands (Participants). Ce transfert peut être initié :

Par un Agent lorsque les wallets sont des comptes de paiement.
Par un DME lorsque les wallets sont des comptes de monnaie électronique.

Cas d’usage

Ce mécanisme permet, par exemple :

à un Agent d’orchestrer des reversements de fonds entre sous-marchands, ou vers des comptes destinataires définis ;
à un DME d’opérer des transferts de monnaie électronique entre utilisateurs d’une place de marché.

CentralPay reste en charge de l’exécution effective des opérations, dans le cadre de la relation contractuelle avec les sous-marchands.

📥 Paramètres requis

Champ	Type	Obligatoire	Description
`destinationWalletId`	UUID	✅	Identifiant du wallet destinataire (appartenant à un sous-marchand).
`amount`	Integer (en cents)	✅	Montant du transfert. Doit être strictement supérieur à 0.
`sourceId`	UUID	✅ si `sourceType` est renseigné	Identifiant de la source de fonds (ex. : transaction, virement, crédit, SDD).
`sourceType`	Enum	✅ si `sourceId` est renseigné	Source du transfert : `TRANSACTION`, `SCT_TRANSACTION`, `CREDIT`, `SDD`.

🔧 Paramètres optionnels

Champ	Type	Description
`emissionWalletId`	UUID	Wallet émetteur si différent du wallet principal du partenaire.
`currency`	Code ISO	Devise du transfert (si différente de celle du wallet).
`fee`	Integer	Montant de la commission prélevée par le partenaire, déduite du montant. Par défaut : 0.
`escrowDate`	Date ISO	Date à partir de laquelle le transfert devient effectif. Peut être utilisée pour définir une période de blocage temporaire.
`merchantTransferId`	String	Référence métier du partenaire (max 100 caractères).
`transferGroup`	String	Groupe de rattachement pour regrouper plusieurs transferts.
`description`	String	Description libre (max 256 caractères).
`additionalData`	Key/Value	Données complémentaires sous forme de paires clé/valeur (max 256 caractères par valeur).
`metaData`	JSON	Métadonnées complémentaires structurées.
`purposeCode` / `purposeMessage`	Enum / String	Finalité du transfert, selon une nomenclature standard. Voir la liste des codes.

🔒 Règles de validation

Le destinationWalletId doit correspondre à un wallet valide d’un sous-marchand du partenaire.
Le sourceId ne peut être utilisé que si l’objet lié est dans un statut accepté (CAPTURED, CLEARED, etc.).
Le montant autorisé dépend du solde disponible ou des fonds liés à la source (transaction, virement, etc.).

🔄 Fonctions complémentaires liées aux transferts

Les partenaires régulés (Agent ou DME) disposent de plusieurs fonctions de gestion post-création d’un transfert, leur permettant d’ajuster, consulter ou annuler une opération, sous conditions.

🛠 Modifier un transfert (Update a Transfer)

Cette fonction permet de modifier certains paramètres d’un transfert existant, à condition qu’il ne soit pas encore exécuté (statut PENDING).

Paramètres disponibles :

Champ	Type	Obligatoire	Description
`transferId`	UUID	✅	Identifiant du transfert à modifier.
`merchantTransferId`	String	❌	Référence partenaire.
`escrowDate`	Date ISO	❌	Nouvelle date d’exécution différée.
`transferGroup`	String	❌	Regroupement de transferts.
`description`	String	❌	Description libre (max 256 caractères).
`additionalData`	Key/Value	❌	Données complémentaires.
`metaData`	JSON	❌	Métadonnées structurées.

💡 La modification de la date d’escrow est notamment utile dans les flux conditionnés (e.g. : marketplace, délais de rétractation…).

❌ Annuler un transfert (Cancel a Transfer)

Un transfert peut être annulé tant qu’il n’a pas encore été exécuté (statut PENDING). Cette annulation est irréversible : l’opération apparaîtra comme CANCEL dans les historiques du wallet.

Paramètres :

Champ	Type	Obligatoire	Description
`transferId`	UUID	✅	Identifiant du transfert à annuler.

⚠️ Une fois que les fonds sont disponibles (TRANSFERRED), cette fonction n’est plus accessible. Il faudra alors utiliser un TransferReversal.

🔍 Consulter un transfert (Retrieve a Transfer)

Permet d’obtenir l’ensemble des détails d’un transfert via son identifiant CentralPay.

Champ	Type	Obligatoire	Description
`transferId`	UUID	✅	Identifiant du transfert.

📂 Rechercher plusieurs transferts (List Transfers)

Permet de rechercher une liste de transferts selon plusieurs critères. Tous les paramètres sont optionnels.

Paramètre	Type	Description
`merchantTransferId`	String (100)	Référence partenaire.
`destinationWalletId`	UUID	Wallet destinataire.
`transferGroup`	String	Groupe de transferts.
`status`	Enum	`PENDING`, `TRANSFERRED`, `CANCEL`.
`after` / `before`	Date ISO	Filtrer par date de création.
`limit`	Integer	Nombre de résultats par page.
`page`	Integer	Index de la page de résultats.

🔁 Retourner un transfert exécuté (`TransferReversal`)

Une fois un transfert exécuté (status = TRANSFERRED), il ne peut plus être annulé via la fonction Cancel. Il est alors nécessaire de passer par une opération dédiée appelée TransferReversal. Elle ne supprime pas le transfert d’origine : celui-ci reste visible, historisé et traçable.

Cette fonction est accessible uniquement aux partenaires régulés (Agent pour les comptes de paiement, DME pour les comptes de monnaie électronique), et doit respecter les règles de disponibilité des fonds.

✅ Conditions d’utilisation

Le transfert initial doit :

Être dans le statut TRANSFERRED
Avoir des fonds disponibles dans le wallet destinataire
Ne pas avoir déjà été remboursé dans sa totalité via des opérations de reversal

Le montant retourné doit être :

Inférieur ou égal au solde disponible du wallet destinataire
Inférieur ou égal à la somme initialement transférée
Diminué des éventuels reversals déjà effectués sur le transfert concerné

▶️ Créer un `TransferReversal`

Permet de retourner un montant vers le wallet émetteur d’origine.

Champ	Type	Obligatoire	Description
`transferId`	UUID	✅	Identifiant du transfert d’origine.
`amount`	Integer	✅	Montant à rembourser (en centimes).
`merchantTransferReversalId`	String	❌	Référence partenaire pour le suivi.
`refundFee`	Boolean	❌	Indique si les frais du transfert initial sont remboursés (par défaut : `true`).
`fee`	Integer	❌	Montant des frais associés au reversal.
`description`	String	❌	Texte libre explicatif (max. 256 caractères).
`escrowDate`	Date ISO	❌	Date d’exécution différée si applicable.
`additionalData`	Key/Value	❌	Paires clé/valeur pour les besoins métier.

💡 Si le champ refundFee est défini à false, le montant des frais initiaux reste acquis et n’est pas restitué au Wallet source.

⚠️ Règles importantes

L’opération est visible dans les mouvements du wallet (débit du wallet destinataire, crédit du wallet d’origine).
Plusieurs reversals peuvent être effectués sur un même transfert, dans la limite du montant total initial.
Si les fonds ne sont pas disponibles, l’appel est rejeté avec une erreur explicite (insuffisance de solde ou montant trop élevé).

🧩 Fonctions complémentaires (TransferReversal)

Ces fonctions permettent de gérer et consulter les opérations de retour de transfert exécuté (TransferReversal), une fois créées.

✏️ Modifier un TransferReversal (Update)

Permet de modifier certaines informations sur un TransferReversal déjà créé.

Champ	Type	Obligatoire	Description
`transferReversalId`	UUID	✅	Identifiant du `TransferReversal` à modifier
`merchantTransferReversalId`	String	❌	Référence partenaire pour le suivi
`description`	String	❌	Texte explicatif libre (256 caractères max)
`escrowDate`	Date (ISO)	❌	Nouvelle date différée d’exécution, si applicable
`additionalData`	Key/Value	❌	Paires clé/valeur pour usage métier spécifique

🔒 Cette fonction est accessible uniquement au niveau PARTNER ou supérieur.

🔍 Consulter un TransferReversal (Retrieve)

Permet de consulter les détails d’un TransferReversal à partir de son identifiant.

Champ	Type	Obligatoire	Description
`transferReversalId`	UUID	✅	Identifiant du `TransferReversal` à consulter

🛈 L’objet retourné contient l’intégralité des informations métier, y compris : montant, date, statut, wallet concerné, et historique de l’opération.

📄 Rechercher des TransferReversals (List)

Permet d’interroger l’historique des TransferReversal selon plusieurs critères.

Paramètre	Type	Obligatoire	Description
`merchantTransferReversalId`	String	❌	Référence partenaire
`after`	Date ISO	❌	Retourne les éléments créés après cette date
`before`	Date ISO	❌	Retourne les éléments créés avant cette date
`limit`	Integer	❌	Nombre d’éléments à retourner (par défaut : 10)
`page`	Integer	❌	Index de la page à retourner (par défaut : 1)

Cette fonction permet un suivi complet des opérations de reversal liées à une activité donnée, y compris les cas de multiples retours partiels.