awesome-node-checkout 1.3.0 → 2.1.0

package/dist/providers/nexi/nexi.provider.d.ts

@@ -1,6 +1,8 @@
 import { BasePaymentProvider } from '../../abstract/base-payment-provider.abstract';
 import { PaymentRequest } from '../../models/payment-request.model';
 import { PaymentResult, WebhookResult } from '../../models/payment-result.model';
+import { IMandateProvider } from '../../interfaces/mandate-provider.interface';
+import { ChargeRequest, ChargeResult, Mandate, MandateCallbackInput, MandatePendingState, MandateRevokeResult, MandateSetupOutcome, MandateSetupRequest, MandateSetupStart, MandateStatusResult } from '../../models/mandate.model';
 export interface NexiProviderConfig {
     merchantId: string;
     macKey: string;
@@ -8,20 +10,37 @@ export interface NexiProviderConfig {
     group?: string;
     /** @default 'sandbox' */
     environment?: 'sandbox' | 'production';
+    /**
+     * Timeout of the recurring-payment and contract API calls (`pagamentoRicorrente`,
+     * `situazioneOrdine` replay guard, `dettagliContratto`, `cancellaContratto`), in ms.
+     * @default 30000
+     */
+    timeoutMs?: number;
+    /**
+     * Mandates: contract type sent as `tipo_contratto` at setup (`S` scheduled, `U` unscheduled) and
+     * included in the setup MAC. Only needed when the terminal is enabled for both kinds.
+     */
+    contractType?: 'S' | 'U';
 }
 /**
  * Nexi eCommerce provider.
  * Flow: `redirect` — builds a signed checkout URL, redirects the user to Nexi,
  * then handles the POST-back via `handleRedirect`.
  *
+ * Recurring payments (`IMandateProvider`): the setup is a hosted-page first payment that
+ * registers a contract (`num_contratto` = `mandateRef`, `tipo_servizio=paga_multi`,
+ * `tipo_richiesta=PP`); later charges use `pagamentoRicorrente`; `cancellaContratto` revokes.
+ * EUR only. See "Specifiche tecniche di integrazione con il gateway di pagamento XPay" v20.4.
+ *
  * Note: Nexi XPay mandates SHA-1 for MAC computation. This is a requirement of
  * the Nexi API and cannot be changed on the client side.
  */
-export declare class NexiProvider extends BasePaymentProvider {
+export declare class NexiProvider extends BasePaymentProvider implements IMandateProvider {
     private readonly config;
     readonly name = "nexi";
     readonly flow: "redirect";
     private readonly apiUrl;
+    private readonly timeoutMs;
     constructor(config: NexiProviderConfig);
     /**
      * Computes the SHA-1 MAC required by Nexi to authenticate the payment request.
@@ -58,6 +77,57 @@ export declare class NexiProvider extends BasePaymentProvider {
      */
     private verifyResponseMac;
     private safeVerifyResponseMac;
+    /**
+     * Extracts the fields of a hosted-page outcome (redirect query or `urlpost` form). Missing
+     * fields are `''`; `codTrans` falls back to `fallbackCodTrans` when given. `mac` is returned as
+     * is, to be checked with `isValidHexMac`.
+     */
+    private extractOutcomeFields;
+    /** True when the 7-field outcome MAC of `fields` is present and valid (constant time). */
+    private outcomeMacValid;
+    /** Constant-time comparison of a hex MAC against the expected SHA-1 hex digest. */
+    private hexMacEquals;
+    /**
+     * Verifies the standard XPay REST response MAC:
+     * `esito={esito}idOperazione={idOperazione}timeStamp={timeStamp}{macKey}`.
+     */
+    private responseMacValid;
+    /**
+     * MAC policy of the recurring and contract APIs: a present `mac` must be valid whatever the
+     * `esito`; a missing one is tolerated only on `KO` (an error answer may carry none).
+     */
+    private responseAuthentic;
+    /**
+     * Classifies a "Tabella Codici errore API Restful" code (pp. 883-885). A missing or
+     * non-numeric code is `merchant`: without a code nothing says the customer is at fault.
+     */
+    private classifyApiError;
+    /** `errore.codice` / `errore.messaggio` of a response, when present. */
+    private apiError;
+    /**
+     * Computes the MAC of `pagamentoRicorrente` (p. 191). `scadenza` is not sent, so it is in the
+     * string with an empty value, as the manual requires:
+     * `apiKey=…numeroContratto=…codiceTransazione=…importo=…divisa=978scadenza=timeStamp=…{macKey}`.
+     */
+    private generateRecurringMac;
+    /**
+     * POSTs a JSON body to an XPay REST endpoint with the configured timeout. Never throws; the
+     * error never contains the response body.
+     */
+    private postApi;
+    /**
+     * Reads `situazioneOrdine` for `codTrans` (same request as `getPaymentDetails`) and classifies
+     * the raw response, over every report entry for `codTrans`:
+     * - `paid`: some entry shows the money was taken (`NEXI_CHARGED_STATUSES`: paid, partly captured,
+     *   refunded or partly refunded);
+     * - `pending`: otherwise, some entry is in progress (`In Corso`), has an unrecognised `stato`, or
+     *   has none. Fail safe: such a code may still be charged, so it is never reported as refused;
+     * - `refused`: every entry is a clear refusal (`Negato`, `Annullato`, `Non Creato`);
+     * - `absent`: OK with no matching report entry, or KO "not found" 2/13;
+     * - `error`: anything else (HTTP, network, timeout, non-JSON, bad MAC, a missing MAC on OK, no
+     *   `report` array, any other KO).
+     */
+    private lookupTransaction;
     createPayment(request: PaymentRequest): Promise<PaymentResult>;
     /**
      * Validates the POST-back data from Nexi.
@@ -81,5 +151,59 @@ export declare class NexiProvider extends BasePaymentProvider {
      * The outcome MAC is mandatory and verified over all 7 fields to ensure authenticity.
      */
     handleRedirect(query: Record<string, string>): Promise<PaymentResult>;
+    /**
+     * Starts a contract registration: a hosted-page first payment with `num_contratto` =
+     * `mandateRef`, `tipo_servizio=paga_multi`, `tipo_richiesta=PP` (pp. 59-65), charging the first
+     * period. `codTrans` is `orderId`. EUR only. `mandate_ref` is appended to `url`, `url_back` and
+     * `urlpost`.
+     */
+    createMandate(request: MandateSetupRequest): Promise<MandateSetupStart>;
+    /**
+     * Confirms a setup from the hosted-page outcome: the redirect on `url` (GET query) or the
+     * `urlpost` notification (form POST). Pure function of its inputs, hence idempotent.
+     *
+     * - The 7-field outcome MAC must be valid, and the MAC-covered `codTrans`, `importo` and
+     *   `divisa` must match `pending`; otherwise the outcome is unverified and non-terminal (a forged
+     *   callback never consumes the pending state). The unsigned `num_contratto`, when present, must
+     *   be `pending.mandateRef` (and `tipo_servizio` / `tipo_richiesta`, when present, `paga_multi` /
+     *   `PP`); the contract number used is always `pending.mandateRef`.
+     * - `esito=OK` with `num_contratto`: active mandate, first charge `succeeded` (terminal). An OK
+     *   without `num_contratto` is unverified and non-terminal (no contract may exist).
+     * - `esito` `KO`, `ANNULLO` or `ERRORE`: no mandate, first charge `failed` (terminal). Start a
+     *   new setup with a fresh `mandateRef` and `orderId`: a `codTrans` is never reused. This
+     *   requires a terminal that allows a single payment attempt per `codTrans`: on a terminal
+     *   configured for up to 3 attempts (manual, pp. 32-33), a KO then an OK arrive for the same
+     *   `codTrans`, and the OK finds the pending state already consumed.
+     * - Any other `esito` (e.g. a pending one) is unverified and non-terminal: it may still turn OK.
+     *
+     * An empty input (`{}`) has no MAC, so a re-confirm is unverified and non-terminal: Nexi never
+     * reports a terminal outcome with an `unknown` first charge.
+     */
+    confirmMandate(pending: MandatePendingState, input: MandateCallbackInput): Promise<MandateSetupOutcome>;
+    /**
+     * Merchant-initiated charge with `pagamentoRicorrente` (pp. 188-193), EUR only.
+     * `codiceTransazione` is `charge.chargeRef`, so `refundPayment(chargeRef, amount)` refunds it.
+     *
+     * Replay guard: `situazioneOrdine` is read first. A transaction that took the money (paid,
+     * partly captured, refunded or partly refunded) is returned as `succeeded` without charging
+     * again, with its `stato` in `raw`; one that only Nexi refused (`Negato`, `Annullato`,
+     * `Non Creato`) is `failed` (a dunning retry needs a new `chargeRef`: Nexi's own retries of a
+     * code after a KO are not used); one still in progress (`In Corso`) or with an unrecognised
+     * `stato` is `unknown`, and so is a lookup error: nothing is charged. A Nexi "transaction
+     * already present" (9) is re-read.
+     * Merchant-side errors (credentials, MAC, technical) are `unknown`, never `failed`.
+     */
+    chargeMandate(mandate: Mandate, charge: ChargeRequest): Promise<ChargeResult>;
+    /**
+     * Re-reads the contract with `dettagliContratto` (pp. 851-853). `active` when it is listed and
+     * its first payment is not KO; `revoked` when its first payment is KO or Nexi answers "not
+     * found" or "invalid contract"; otherwise `unknown` (unverified).
+     */
+    getMandate(mandate: Mandate): Promise<MandateStatusResult>;
+    /**
+     * Cancels the contract with `cancellaContratto` (pp. 838-840). "Not found" and "invalid
+     * contract" count as revoked: the contract is already gone.
+     */
+    revokeMandate(mandate: Mandate): Promise<MandateRevokeResult>;
 }
 //# sourceMappingURL=nexi.provider.d.ts.map

package/dist/providers/nexi/nexi.provider.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"nexi.provider.d.ts","sourceRoot":"","sources":["../../../src/providers/nexi/nexi.provider.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,+CAA+C,CAAC;AACpF,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAGjF,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,WAAW,CAAC,EAAE,SAAS,GAAG,YAAY,CAAC;CACxC;AAED;;;;;;;GAOG;AACH,qBAAa,YAAa,SAAQ,mBAAmB;IAMvC,OAAO,CAAC,QAAQ,CAAC,MAAM;IALnC,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,IAAI,EAAG,UAAU,CAAU;IAEpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,MAAM,EAAE,kBAAkB;IAQvD;;;;;OAKG;IACH,OAAO,CAAC,IAAI;IAIZ;;;;;OAKG;IACH,OAAO,CAAC,WAAW;IAInB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAIzB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IASzB;;;OAGG;IACH,OAAO,CAAC,aAAa;IAIrB;;;OAGG;IACH,OAAO,CAAC,iBAAiB;IAwBzB,OAAO,CAAC,qBAAqB;IAiBvB,aAAa,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC;IAqCpE;;;;;;;OAOG;IACG,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;IAuE9F;;;OAGG;IACG,aAAa,CACjB,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,QAAQ,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACpC,OAAO,CAAC,aAAa,CAAC;IAqDnB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA6G5D,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IAuC/E;;;;OAIG;IACG,cAAc,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,aAAa,CAAC;CAG5E"}
+{"version":3,"file":"nexi.provider.d.ts","sourceRoot":"","sources":["../../../src/providers/nexi/nexi.provider.ts"],"names":[],"mappings":"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"}