Transfert indépendant

1. Créer un transfert (Create a Transfer)

La fonction Create a Transfer permet aux marchands mandataires (Agents ou DME) de transférer des fonds entre deux comptes de leurs marchands participants. Ce transfert peut être initié :

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

1.1. Cas d’usage

Ce mécanisme permet par exemple :

• À un Agent d’orchestrer des débits et des crédits de fonds entre lui et ses marchands participants, ou vers des comptes destinataires définis
• À un DME d’opérer des transferts de monnaie électronique entre ses marchands participants (par exemple dans le cadre d’une place de marché C2C)

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

1.2. Paramètres requis

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

1.3. Paramètres optionnels

Champ	Type	Description
emissionWalletId	UUID	Compte émetteur si différent du compte principal du marchand mandataire.
currency	Code ISO	Devise du transfert (si différente de celle du compte).
fee	Integer	Montant de la commission prélevée par le marchand mandataire, 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 marchand mandataire (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.

1.4. Règles de validation

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

2. Fonctions complémentaires liées aux transferts

Les marchands mandataires disposent de plusieurs fonctions de gestion post-création d’un transfert, leur permettant d’ajuster, consulter ou annuler une opération, sous conditions.

2.1. 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	✅ Oui	Identifiant du transfert à modifier.
merchantTransferId	String	❌ Non	Référence marchand mandataire.
escrowDate	Date ISO	❌ Non	Nouvelle date d’exécution différée.
transferGroup	String	❌ Non	Regroupement de transferts.
description	String	❌ Non	Description libre (max 256 caractères).
additionalData	Key/Value	❌ Non	Données complémentaires.
metaData	JSON	❌ Non	Métadonnées structurées.

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

2.2. 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 compte.

Paramètres :

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

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

2.3. 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	✅ Oui	Identifiant du transfert.

2.4. 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 marchand mandataire.
destinationWalletId	UUID	Compte 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.

3. Retourner un transfert exécuté (Transfer Reversal)

Une fois un transfert exécuté (statut 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 marchands mandataires (Agent pour les comptes de paiement, DME pour les comptes de monnaie électronique), et doit respecter les règles de disponibilité des fonds.

3.1. Conditions d’utilisation

Le transfert initial doit :

• Être dans le statut TRANSFERRED
• Avoir des fonds disponibles dans le compte 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 compte destinataire
• Inférieur ou égal à la somme initialement transférée
• Diminué des éventuels reversals déjà effectués sur le transfert concerné

3.2. Créer un TransferReversal

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

Champ	Type	Obligatoire	Description
transferId	UUID	✅ Oui	Identifiant du transfert d’origine.
amount	Integer	✅ Oui	Montant à rembourser (en centimes).
merchantTransferReversalId	String	❌ Non	Référence marchand mandataire pour le suivi.
refundFee	Boolean	❌ Non	Indique si les frais du transfert initial sont remboursés (par défaut : true).
fee	Integer	❌ Non	Montant des frais associés au reversal.
description	String	❌ Non	Texte libre explicatif (max. 256 caractères).
escrowDate	Date ISO	❌ Non	Date d’exécution différée si applicable.
additionalData	Key/Value	❌ Non	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 compte source.

Règles importantes :

• L’opération est visible dans les mouvements du compte (débit du compte destinataire, crédit du compte 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é)

4. 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.

4.1. Modifier un TransferReversal (Update)

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

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

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

4.2. Consulter un TransferReversal (Retrieve)

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

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

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

4.3. Rechercher des TransferReversals (List)

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

Paramètre	Type	Obligatoire	Description
merchantTransferReversalId	String	❌ Non	Référence marchand mandataire
after	Date ISO	❌ Non	Retourne les éléments créés après cette date
before	Date ISO	❌ Non	Retourne les éléments créés avant cette date
limit	Integer	❌ Non	Nombre d’éléments à retourner (par défaut : 10)
page	Integer	❌ Non	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.