Hooks utilisés

Hook	Rôle
`paymentOptions`	Option « Payer avec mon avoir » (client connecté, avoir utilisable sur le panier).
`actionOrderStatusPostUpdate`	État payé (`paid` = 1) : émission des avoirs des produits (`CreditIssuer::issueForOrder`) et rapprochement d'un règlement de solde. État « Annulé » : restitution de l'avoir utilisé, retrait des avoirs émis non dépensés, annulation du solde dû.
`displayAdminOrderSide`	Encart « Solde à régler » de la commande.
`displayAdminProductsExtra`, `actionProductUpdate`, `actionProductSave`	Règle d'avoir dans la fiche produit (onglet « Modules »).
`displayCustomerAccount`	Lien « Mes avoirs (solde) » du compte client.
`displayOrderDetail`	Rappel du solde à régler dans le détail d'une commande.

Un incident dans le module ne bloque jamais un changement d'état : l'erreur est écrite dans les logs (gravité 3).

Contrôleurs

Contrôleur	Rôle
front `wallet`	Page « Mes avoirs » : `index.php?fc=module&module=websourcecredit&controller=wallet`.
front `validation`	Validation de la commande payée par avoir.
front `pay`	Page du lien de paiement : `…&controller=pay&token=<jeton>`. Le client doit être connecté avec le compte de la commande.
admin `AdminWebsourceCredit`	Page Clients > Avoirs, onglets `tab=wallets`, `customer` (`id_customer`), `rules`, `dues`, `movements`.
admin `AdminWebsourceCreditAjax`	Actions de l'encart de commande.

Actions de l'encart de commande

POST ajax=1 sur AdminWebsourceCreditAjax, paramètres wsc_do et id_order :

`wsc_do`	Paramètres	Réponse JSON
`copy_link`	—	`{"success": true, "url": "…", "message": "Lien créé. Il est valable jusqu'au … et ne sert qu'une fois."}`
`send_link`	—	Idem, avec « E-mail envoyé à … » ou « Le lien est créé mais l'e-mail n'a pas pu partir… ».
`mark_paid`	`method`, `reference`	`{"success": true, "message": "Solde marqué comme payé. La commande passe en « Paiement accepté »."}`

Erreur : {"success": false, "message": "…"}.

Formulaires de la page Avoirs

POST wsc_form=1 + wsc_do :

`wsc_do`	Champs
`save_rule`	`product`, `kind` (`fixed`, `percent`), `amount`, `validity_days`, `usable_on` (`any`, `product`), `enabled`
`toggle_rule`	`id_product`, `active`
`delete_rule`	`id_product`
`adjust`	`customer`, `direction` (`credit`, `debit`), `amount`, `currency`, `validity_days`, `reason`

Services

Websource\Credit\Service\Services (fabrique statique) :

use Websource\Credit\Service\Services;

$balances = Services::wallet()->balances($idCustomer, $idShop);   // soldes par devise, en centimes
$usable   = Services::wallet()->usable($idCustomer, $idShop, $productCaps, $idCurrency);
$count    = Services::issuer()->issueForOrder($order);            // idempotent
$link     = Services::payLinks();                                 // création et résolution des liens

Service	Rôle
`wallet()WalletService`	`balances`, `usable`, `grant`, `debit`, `manualDebit`, `rollback`, `restoreOrder`, `cancelIssued`, `expireOverdue`.
`issuer()CreditIssuer`	Émission des avoirs d'une commande payée.
`checkout()CreditCheckout`	Paiement par avoir (débit atomique, verrou par panier).
`payLinks()PayLinkService`	Liens de paiement (jeton aléatoire, empreinte stockée, expiration, usage unique, révocation du précédent).
`settlement()SettlementService`, `cartBuilder()`	Règlement en ligne du solde par une commande de règlement (produit technique).
`rules()`, `lots()`, `ledger()`, `dues()`, `links()`	Dépôts des tables.
`mailer()MailSender`	E-mails `wscredit_paylink`, `wscredit_paid` (fr, en).

Les montants sont stockés en centimes de la devise (Money\Cents). Un avoir reste dans sa devise d'émission ; il est converti au taux du jour lors de son utilisation (Money\Exchange).

Règles d'émission

Une règle par produit et par boutique.
Avoir fixe : par unité achetée, plafonné au prix payé pour la ligne. Avoir en pourcentage : sur le prix TTC de la ligne.
Une commande réglée avec un avoir, même en partie, n'émet pas d'avoir.
Émission idempotente : une fois par produit et par commande (origin_key).
Expiration appliquée à la lecture du solde, sans tâche planifiée. Les lots les plus proches de l'expiration sont consommés en premier (Wallet\LotAllocator).

Tables

Préfixe {prefix}websourcecredit_ :

Table	Colonnes principales
`rule`	`id_rule`, `id_product`, `id_shop`, `kind`, `value`, `validity_days`, `usable_on`, `active`, `date_add`, `date_upd`
`lot`	`id_lot`, `id_customer`, `id_shop`, `id_currency`, `id_rule`, `id_product`, `id_order`, `amount_initial`, `amount_remaining`, `origin_key`, `date_add`, `date_expire`
`ledger`	`id_entry`, `id_customer`, `id_shop`, `id_lot`, `type` (`credit`, `debit`, `manual_plus`, …), `amount`, `id_currency`, `used_amount`, `used_currency`, `rate`, `rounding`, `id_order`, `note`, `id_employee`, `date_add`
`due`	Solde dû par commande et son statut (ouvert, payé, annulé).
`paylink`	Liens de paiement : commande, empreinte du jeton, montant, expiration, statut.

Les notes générées par le module sont des codes traduits à l'affichage (@product:…, @checkout:…) ; un motif saisi à la main est conservé tel quel.

Réglages

Clé	Défaut	Rôle
`WSCREDIT_ALLOW_PARTIAL`	1	Commande possible avec un solde à payer.
`WSCREDIT_LINK_DAYS`	7	Validité d'un lien (1 à 90 jours).
`WSCREDIT_DEFAULT_VALIDITY`	365	Validité proposée pour un avoir.
`WSCREDIT_ONLINE_SETTLEMENT`	1	Règlement du solde en ligne.
`WSCREDIT_OFFLINE_TEXT`	vide	Instructions hors ligne, par langue.
`WSCREDIT_KEEP_DATA`	1	Conservation des données à la désinstallation.
`WSCREDIT_OS_PARTIAL`	—	Identifiant de l'état « Paiement partiel – solde à régler » (non « logable »).
`WSCREDIT_SETTLE_PRODUCT`	—	Identifiant du produit technique de règlement.

Templates

views/templates/front/wallet.tpl, pay.tpl, views/templates/hook/payment_info.tpl, customer_account.tpl, order_detail.tpl, order_side.tpl, surchargeables dans themes/<theme>/modules/websourcecredit/…. Chaînes de la boutique : domaine Modules.Websourcecredit.Shop. Classes CSS : .wsc-card, .wsc-balance, .wsc-table, .wsc-lines, .wsc-sum.

Limites connues

Le règlement en ligne du solde crée une seconde commande (produit technique) : doublon à traiter dans les exports.
Un panier réparti en plusieurs commandes ne peut pas être payé par avoir.
Seule l'annulation rend l'avoir utilisé ; un remboursement ne reprend pas automatiquement les avoirs émis.
L'état « Paiement partiel – solde à régler » ne compte la vente dans les statistiques qu'au passage en « Paiement accepté » ; le stock est décompté dès la création de la commande.

Tests

php tests/run.php (logique pure), php tests/integration_ps.php (instance PrestaShop).

Websource Avoirs pour PrestaShop — référence développeur