cinetpay-seamless 0.1.2 → 0.1.3

package/README.md

@@ -152,6 +152,9 @@ Ouvre la popup de paiement CinetPay.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `paymentToken` | `string` | **requis** | Token obtenu via votre backend (`POST /v1/payment`) |
+| `statusUrl` | `string \| (ctx) => string` | - | Endpoint de votre backend pour vérifier le statut canonique |
+| `checkStatus` | `(ctx) => Promise<object>` | - | Fonction personnalisée de vérification statut |
+| `statusPollInterval` | `number` | `3000` | Intervalle de vérification statut en ms |
 | `debug` | `boolean` | `false` | Logs console `[CinetPay Seamless]` |
 | `onReady` | `() => void` | - | Iframe chargée |
 | `onPaymentSuccess` | `(data) => void` | - | Paiement accepté |
@@ -190,6 +193,8 @@ Ferme la popup et l'overlay.
   amount: number
   currency: string
   status: 'ACCEPTED' | 'REFUSED' | 'PENDING' | 'INITIATED' | 'EXPIRED' | 'UNKNOWN'
+  rawStatus?: string
+  apiCode?: number
   paymentMethod: string
   description: string
   transactionId: string
@@ -199,6 +204,46 @@ Ferme la popup et l'overlay.
 }
 ```
 
+### Vérification statut recommandée
+
+Le checkout CinetPay peut finaliser le paiement sans envoyer de `postMessage`
+au parent navigateur. Pour fiabiliser `onPaymentSuccess` et `onPaymentFailed`,
+fournissez un endpoint backend qui vérifie le statut canonique auprès de CinetPay.
+
+```typescript
+CinetPaySeamless.open({
+  paymentToken,
+  statusUrl: `/api/cinetpay/status?transactionId=${merchantTransactionId}`,
+  statusPollInterval: 3000,
+  onPaymentSuccess: (data) => {
+    console.log('Paiement accepté', data.transactionId)
+  },
+  onPaymentFailed: (data) => {
+    console.log('Paiement refusé', data.rawStatus)
+  },
+})
+```
+
+Votre endpoint backend doit appeler `GET /v1/payment/{merchant_transaction_id}`
+avec vos clés CinetPay, puis renvoyer la réponse JSON au frontend :
+
+```json
+{
+  "code": 100,
+  "status": "SUCCESS",
+  "merchant_transaction_id": "ORDER-123",
+  "transaction_id": "27ba5590f3ae4c6f9585ae1e4f5265dd"
+}
+```
+
+Le SDK normalise automatiquement :
+
+| Statut CinetPay | Event Seamless |
+|---|---|
+| `SUCCESS` / code `100` | `payment.success` |
+| `FAILED` / `INSUFFICIENT_BALANCE` / code `2010` / `2005` | `payment.failed` |
+| `INITIATED` / `PENDING` / `EXPIRED` | `payment.pending` |
+
 ## Exemples d'intégration
 
 > Le Seamless a besoin d'un `paymentToken` obtenu côté serveur. Les exemples ci-dessous
@@ -639,12 +684,15 @@ flowchart LR
     B -->|"paymentToken"| F
     F -->|"popup"| D["CinetPay Checkout"]
     D -->|"webhook"| B
-    D -->|"postMessage"| F
+    D -->|"postMessage si disponible"| F
+    F -->|"GET /api/cinetpay/status"| B
+    B -->|"GET /v1/payment/{id}"| C
 ```
 
 ### Autres protections
 
 - **postMessage** : whitelist stricte des domaines CinetPay (bloque les domaines lookalike)
+- **statusUrl recommandé** : vérification canonique via votre backend si `postMessage` final absent
 - **paymentToken validé** : regex `[a-zA-Z0-9_-]{10,128}` avant injection dans l'URL
 - **Popup bloquée** : détection et callback `onError` avec code `POPUP_BLOCKED`
 - **Zero dépendance** runtime — aucun risque supply chain

package/dist/checkout.d.ts

@@ -1,6 +1,7 @@
 import type { PaymentResponse, PaymentError } from './types';
 import { Logger } from './logger';
 import { EventEmitter } from './emitter';
+type StatusChecker = () => Promise<unknown>;
 /** @internal Options du constructeur Checkout */
 export interface CheckoutOptions {
     onReady?: () => void;
@@ -11,6 +12,8 @@ export interface CheckoutOptions {
         status: string;
     }) => void;
     onError?: (error: PaymentError) => void;
+    statusChecker?: StatusChecker;
+    statusPollInterval?: number;
     logger: Logger;
     emitter: EventEmitter;
 }
@@ -30,9 +33,14 @@ export declare class Checkout {
     private overlay;
     private popup;
     private pollTimer;
+    private statusTimer;
     private closeTimer;
     private messageHandler;
     private lastStatus;
+    private lastDispatchKey;
+    private finalStatusDispatched;
+    private statusCheckInFlight;
+    private isClosing;
     private previousBodyOverflow;
     private onReadyCallback?;
     private onPaymentSuccessCallback?;
@@ -40,6 +48,8 @@ export declare class Checkout {
     private onPaymentPendingCallback?;
     private onCloseCallback?;
     private onErrorCallback?;
+    private statusChecker?;
+    private statusPollInterval;
     private logger;
     private emitter;
     constructor(options: CheckoutOptions);
@@ -53,6 +63,7 @@ export declare class Checkout {
      * Ferme la popup et l'overlay.
      */
     close(): void;
+    private finishClose;
     private static isRecord;
     private static childRecords;
     private static findValue;
@@ -60,6 +71,7 @@ export declare class Checkout {
     private static asNumber;
     private static asOptionalNumber;
     private static normalizeStatus;
+    private static isFinalStatus;
     private static buildPaymentResponse;
     /** Dispatche la réponse vers le bon callback selon le statut. */
     private dispatchResponse;
@@ -75,9 +87,13 @@ export declare class Checkout {
      */
     private startPolling;
     private stopPolling;
+    private startStatusPolling;
+    private stopStatusPolling;
+    private checkStatus;
     /** Origines autorisées pour les messages postMessage */
     private static readonly ALLOWED_ORIGINS;
     /** Écoute les messages postMessage de la popup CinetPay. */
     private listenForMessages;
 }
+export {};
 //# sourceMappingURL=checkout.d.ts.map

package/dist/checkout.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,YAAY,EAAiB,MAAM,SAAS,CAAA;AAC3E,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAA;AAExC,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,OAAO,CAAC,EAAE,MAAM,IAAI,CAAA;IACpB,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IAClD,eAAe,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IACjD,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,eAAe,KAAK,IAAI,CAAA;IAClD,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,CAAA;IAC5C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;IACvC,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,YAAY,CAAA;CACtB;AAKD;;;;;;;;;;;GAWG;AACH,qBAAa,QAAQ;IACnB,OAAO,CAAC,OAAO,CAA8B;IAC7C,OAAO,CAAC,KAAK,CAAsB;IACnC,OAAO,CAAC,SAAS,CAA8C;IAC/D,OAAO,CAAC,UAAU,CAA6C;IAC/D,OAAO,CAAC,cAAc,CAA+C;IACrE,OAAO,CAAC,UAAU,CAAY;IAC9B,OAAO,CAAC,oBAAoB,CAAK;IAEjC,OAAO,CAAC,eAAe,CAAC,CAAY;IACpC,OAAO,CAAC,wBAAwB,CAAC,CAAiC;IAClE,OAAO,CAAC,uBAAuB,CAAC,CAAiC;IACjE,OAAO,CAAC,wBAAwB,CAAC,CAAiC;IAClE,OAAO,CAAC,eAAe,CAAC,CAAoC;IAC5D,OAAO,CAAC,eAAe,CAAC,CAA+B;IACvD,OAAO,CAAC,MAAM,CAAQ;IACtB,OAAO,CAAC,OAAO,CAAc;gBAEjB,OAAO,EAAE,eAAe;IAWpC;;;;OAIG;IACH,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI;IAkB9B;;OAEG;IACH,KAAK,IAAI,IAAI;IAkCb,OAAO,CAAC,MAAM,CAAC,QAAQ;IAIvB,OAAO,CAAC,MAAM,CAAC,YAAY;IAU3B,OAAO,CAAC,MAAM,CAAC,SAAS;IASxB,OAAO,CAAC,MAAM,CAAC,QAAQ;IAKvB,OAAO,CAAC,MAAM,CAAC,QAAQ;IASvB,OAAO,CAAC,MAAM,CAAC,gBAAgB;IAU/B,OAAO,CAAC,MAAM,CAAC,eAAe;IA+C9B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAyBnC,iEAAiE;IACjE,OAAO,CAAC,gBAAgB;IAgCxB,OAAO,CAAC,YAAY;IAQpB,OAAO,CAAC,aAAa;IAqCrB;;OAEG;IACH,OAAO,CAAC,SAAS;IA6BjB;;;OAGG;IACH,OAAO,CAAC,YAAY;IAgBpB,OAAO,CAAC,WAAW;IAOnB,wDAAwD;IACxD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAOtC;IAED,4DAA4D;IAC5D,OAAO,CAAC,iBAAiB;CAsC1B"}
+{"version":3,"file":"checkout.d.ts","sourceRoot":"","sources":["../src/checkout.ts"],"names":[],"mappings":"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"}