cinetpay-seamless 0.1.2 → 0.1.4

package/README.md

@@ -36,7 +36,7 @@ npm install cinetpay-seamless
 ### CDN
 
 ```html
-<script src="https://unpkg.com/cinetpay-seamless@0.1.2/dist/cinetpay-seamless.umd.cjs"></script>
+<script src="https://unpkg.com/cinetpay-seamless@0.1.4/dist/cinetpay-seamless.umd.cjs"></script>
 ```
 
 ## Démarrage rapide
@@ -45,7 +45,7 @@ npm install cinetpay-seamless
 import { CinetPaySeamless } from 'cinetpay-seamless'
 
 // 1. Obtenir le paymentToken depuis votre backend
-const { paymentToken } = await fetch('/api/pay', {
+const { paymentToken, paymentUrl } = await fetch('/api/pay', {
   method: 'POST',
   headers: { 'Content-Type': 'application/json' },
   body: JSON.stringify({ amount: 5000, orderId: 'ORDER-001' }),
@@ -54,6 +54,7 @@ const { paymentToken } = await fetch('/api/pay', {
 // 2. Ouvrir la popup
 CinetPaySeamless.open({
   paymentToken,
+  paymentUrl, // recommandé si votre backend renvoie l'URL CinetPay exacte
   onPaymentSuccess: (data) => {
     console.log('Paiement réussi !', data.amount, data.currency)
   },
@@ -68,7 +69,7 @@ CinetPaySeamless.open({
 ```html
 <button id="pay-btn">Payer 5 000 XOF</button>
 
-<script src="https://unpkg.com/cinetpay-seamless@0.1.2/dist/cinetpay-seamless.umd.cjs"></script>
+<script src="https://unpkg.com/cinetpay-seamless@0.1.4/dist/cinetpay-seamless.umd.cjs"></script>
 <script>
   document.getElementById('pay-btn').addEventListener('click', function() {
     // Appeler votre backend pour obtenir le paymentToken
@@ -81,6 +82,7 @@ CinetPaySeamless.open({
     .then(function(data) {
       CinetPaySeamless.open({
         paymentToken: data.paymentToken,
+        paymentUrl: data.paymentUrl,
         onPaymentSuccess: function(result) {
           alert('Merci ! ' + result.amount + ' ' + result.currency)
         },
@@ -152,6 +154,12 @@ Ouvre la popup de paiement CinetPay.
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `paymentToken` | `string` | **requis** | Token obtenu via votre backend (`POST /v1/payment`) |
+| `environment` | `'sandbox' \| 'production'` | `'sandbox'` | Environnement utilisé si `paymentUrl` n'est pas fourni |
+| `paymentUrl` | `string` | - | URL complète renvoyée par CinetPay, prioritaire sur `environment` |
+| `checkoutBaseUrl` | `string` | selon `environment` | Host checkout personnalisé |
+| `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 +198,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 +209,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
@@ -244,7 +294,10 @@ app.post('/api/pay', async (req, res) => {
     channel: 'PUSH',
   }, 'CI')
 
-  res.json({ paymentToken: payment.paymentToken })
+  res.json({
+    paymentToken: payment.paymentToken,
+    paymentUrl: payment.paymentUrl,
+  })
 })
 ```
 
@@ -265,9 +318,9 @@ async function pay(amount: number) {
       phone: '+2250707000000',
     }),
   })
-  const { paymentToken } = await res.json()
+  const { paymentToken, paymentUrl } = await res.json()
 
-  CinetPaySeamless.open({ paymentToken, debug: true })
+  CinetPaySeamless.open({ paymentToken, paymentUrl, debug: true })
 }
 ```
 
@@ -491,7 +544,7 @@ async function pay() {
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Paiement</title>
-  <script src="https://unpkg.com/cinetpay-seamless@0.1.2/dist/cinetpay-seamless.umd.cjs"></script>
+  <script src="https://unpkg.com/cinetpay-seamless@0.1.4/dist/cinetpay-seamless.umd.cjs"></script>
 </head>
 <body>
   <form id="payment-form">
@@ -592,7 +645,7 @@ CinetPaySeamless.open({ paymentToken: 'abc...', debug: true })
 
 ```
 [CinetPay Seamless] CinetPaySeamless.open() called
-[CinetPay Seamless] Opening popup { paymentUrl: 'https://secure.cinetpay.net/checkout/abc...' }
+[CinetPay Seamless] Opening popup { paymentUrl: 'https://secure.cinetpay.co/checkout/abc...' }
 [CinetPay Seamless] Iframe loaded — checkout ready
 [CinetPay Seamless] Payment response: ACCEPTED { amount: 5000, currency: 'XOF', ... }
 [CinetPay Seamless] Payment accepted
@@ -620,8 +673,8 @@ Commiter le .env dans git                  Ajouter .env dans .gitignore
 
 | Préfixe de clé | Environnement | Usage |
 |---|---|---|
-| `sk_test_...` | Sandbox (`api.cinetpay.net`) | Développement et tests |
-| `sk_live_...` | Production (`api.cinetpay.co`) | Transactions réelles |
+| `sk_test_...` | Sandbox API `api.cinetpay.net`, checkout `secure.cinetpay.net` | Développement et tests |
+| `sk_live_...` | Production API `api.cinetpay.co`, checkout `secure.cinetpay.co` | Transactions réelles |
 
 **Règles importantes :**
 - Ne **jamais** utiliser des clés `sk_live_` en développement
@@ -639,12 +692,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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"}