@paykit-sdk/monnify 1.2.0 → 1.3.1

package/README.md

@@ -0,0 +1,149 @@
+# @paykit-sdk/monnify
+
+Monnify provider for PayKit.
+
+## Installation
+
+```bash
+npm install @paykit-sdk/monnify
+# or
+pnpm add @paykit-sdk/monnify
+```
+
+## Quick Start
+
+```typescript
+import { createEndpointHandlers, PayKit } from '@paykit-sdk/core';
+import { monnify } from '@paykit-sdk/monnify';
+
+export const paykit = new PayKit(monnify());
+export const endpoints = createEndpointHandlers(paykit);
+```
+
+Or with direct config:
+
+```typescript
+import { PayKit } from '@paykit-sdk/core';
+import { createMonnify } from '@paykit-sdk/monnify';
+
+export const paykit = new PayKit(
+  createMonnify({
+    apiKey: 'MK_TEST_...',
+    secretKey: 'your-secret-key',
+    isSandbox: true,
+  }),
+);
+```
+
+## Environment Variables
+
+```bash
+MONNIFY_API_KEY=MK_TEST_...
+MONNIFY_SECRET_KEY=your-secret-key
+MONNIFY_SANDBOX=true
+```
+
+## Next.js API Route
+
+```typescript
+// app/api/paykit/[...endpoint]/route.ts
+import { endpoints } from '@/lib/paykit';
+import { EndpointPath } from '@paykit-sdk/core';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: Promise<{ endpoint: string[] }> },
+) {
+  const { endpoint: endpointArray } = await params;
+  const endpoint = ('/' + endpointArray.join('/')) as EndpointPath;
+  const handler = endpoints[endpoint];
+
+  if (!handler) {
+    return NextResponse.json(
+      { message: 'Not found' },
+      { status: 404 },
+    );
+  }
+
+  const { args } = await request.json();
+  const result = await handler(...args);
+  return NextResponse.json({ result });
+}
+```
+
+## Webhooks
+
+Monnify sends signed POST requests with an HMAC-SHA512 signature.
+
+```typescript
+// app/api/paykit/webhooks/route.ts
+import { paykit } from '@/lib/paykit';
+import { NextRequest, NextResponse } from 'next/server';
+
+export async function POST(request: NextRequest) {
+  const body = await request.text();
+
+  const webhook = paykit.webhooks
+    .setup({ webhookSecret: process.env.MONNIFY_SECRET_KEY! })
+    .on('payment.created', async event => {
+      /* SUCCESSFUL_TRANSACTION or SUCCESSFUL_TRANSACTION_OFFLINE */
+    })
+    .on('payment.updated', async event => {
+      /* SETTLEMENT */
+    })
+    .on('payment.failed', async event => {
+      /* REJECTED_PAYMENT */
+    });
+
+  await webhook.handle({
+    body,
+    headersAsObject: Object.fromEntries(request.headers),
+    fullUrl: request.url,
+  });
+
+  return NextResponse.json({ received: true });
+}
+```
+
+Monnify event mappings:
+
+| Monnify event                    | PayKit event emitted |
+| -------------------------------- | -------------------- |
+| `SUCCESSFUL_TRANSACTION`         | `payment.created`    |
+| `SUCCESSFUL_TRANSACTION_OFFLINE` | `payment.created`    |
+| `REJECTED_PAYMENT`               | `payment.failed`     |
+| `SETTLEMENT`                     | `payment.updated`    |
+
+## Checkout
+
+Monnify requires an email customer and amount/currency in `provider_metadata`:
+
+```typescript
+const checkout = await paykit.checkouts.create({
+  customer: { email: 'user@example.com' },
+  item_id: 'prod_123',
+  session_type: 'one_time',
+  quantity: 1,
+  success_url: 'https://example.com/success',
+  provider_metadata: {
+    amount: 5000,
+    currency: 'NGN',
+  },
+});
+
+// Redirect user to checkout.payment_url
+```
+
+## Documentation
+
+Full docs at [docs.usepaykit.com/providers/monnify](https://docs.usepaykit.com/providers/monnify).
+
+## Support
+
+- [Monnify Documentation](https://developers.monnify.com)
+- [PayKit Issues](https://github.com/usepaykit/paykit-sdk/issues)
+
+## License
+
+ISC

package/dist/index.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var core = require('@paykit-sdk/core');
+var crypto$1 = require('crypto');
 var jsSha512 = require('js-sha512');
 
 // src/index.ts
@@ -210,6 +211,48 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
     }
     return altResponse.value.responseBody;
   }
+  /**
+   * Monnify only has one way to move money: a hosted redirect
+   * transaction. createCheckout and createPayment both boil down to
+   * this same call - only the input validation and the response
+   * mapper differ between the two.
+   */
+  async initializeTransaction(params) {
+    const paymentReference = crypto.randomUUID();
+    const body = {
+      amount: params.amount,
+      paymentReference,
+      paymentDescription: params.description,
+      currencyCode: params.currency,
+      redirectUrl: params.redirectUrl,
+      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      metadata: params.metadata,
+      customerEmail: params.email
+    };
+    const response = await this._client.post(
+      "/v1/merchant/transactions/init-transaction",
+      {
+        body: JSON.stringify(body),
+        headers: await this.tokenManager.getAuthHeaders()
+      }
+    );
+    const responseBody = this.ensureResponse(
+      response,
+      "initializeTransaction"
+    );
+    const transactionReference = responseBody.transactionReference;
+    const checkoutUrl = responseBody.checkoutUrl;
+    const transactionResponse = await this._client.get(
+      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
+      { headers: await this.tokenManager.getAuthHeaders() }
+    );
+    const transactionData = this.ensureResponse(
+      transactionResponse,
+      "initializeTransaction",
+      "Failed to retrieve transaction details"
+    );
+    return { ...transactionData, checkoutUrl, transactionReference };
+  }
   createCheckout = async (params) => {
     const data = this.validateSchema(
       core.createCheckoutSchema,
@@ -232,50 +275,21 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
       data.provider_metadata ?? { currency: "NGN" },
       "The following fields must be present in the provider_metadata of createCheckout: {keys}"
     );
-    const paymentReference = crypto.randomUUID();
-    const body = {
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
       amount,
-      paymentReference,
-      paymentDescription: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
-      currencyCode: currency,
+      currency,
       redirectUrl: data.success_url,
-      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      description: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
       metadata: {
         ...params.metadata,
         [core.PAYKIT_METADATA_KEY]: JSON.stringify({
           item: data.item_id,
           qty: data.quantity
         })
-      },
-      customerEmail: data.customer.email
-    };
-    const response = await this._client.post(
-      "/v1/merchant/transactions/init-transaction",
-      {
-        body: JSON.stringify(body),
-        headers: await this.tokenManager.getAuthHeaders()
       }
-    );
-    const responseBody = this.ensureResponse(
-      response,
-      "createCheckout"
-    );
-    const transactionReference = responseBody.transactionReference;
-    const checkoutUrl = responseBody.checkoutUrl;
-    const checkoutResponse = await this._client.get(
-      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
-      { headers: await this.tokenManager.getAuthHeaders() }
-    );
-    const checkoutData = this.ensureResponse(
-      checkoutResponse,
-      "createCheckout",
-      "Failed to retrieve checkout details"
-    );
-    return Checkout$inboundSchema({
-      ...checkoutData,
-      checkoutUrl,
-      transactionReference
     });
+    return Checkout$inboundSchema(transactionData);
   };
   retrieveCheckout = async (id) => {
     const transactionData = await this.queryTransaction(
@@ -394,14 +408,39 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
     );
   };
   createPayment = async (params) => {
-    throw new core.ProviderNotSupportedError(
-      "createPayment",
-      "Moniepoint",
-      {
-        reason: "Moniepoint doesn't support creating payments",
-        alternative: "Use the createPayment method instead"
-      }
+    const data = this.validateSchema(
+      core.createPaymentSchema,
+      params,
+      "createPayment"
     );
+    if (!core.isEmailCustomer(data.customer)) {
+      throw new core.InvalidTypeError(
+        "customer",
+        "object (customer) with email",
+        "string (customer ID)",
+        {
+          provider: this.providerName,
+          method: "createPayment"
+        }
+      );
+    }
+    const { success_url } = core.validateRequiredKeys(
+      ["success_url"],
+      data.provider_metadata ?? {},
+      "The following fields must be present in the provider_metadata of createPayment: {keys}"
+    );
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
+      amount: data.amount.toString(),
+      currency: data.currency,
+      redirectUrl: success_url,
+      description: `Payment for ${data.item_id}`,
+      metadata: {
+        ...data.metadata,
+        [core.PAYKIT_METADATA_KEY]: JSON.stringify({ item: data.item_id })
+      }
+    });
+    return Payment$inboundSchema(transactionData);
   };
   retrievePayment = async (id) => {
     try {
@@ -503,11 +542,10 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
         provider: this.providerName
       });
     }
-    const computedHash = jsSha512.sha512.hmac(
-      webhookSecret,
-      JSON.stringify(body)
-    );
-    if (computedHash !== receivedHash)
+    const computedHash = jsSha512.sha512.hmac(webhookSecret, body);
+    const computedBuf = Buffer.from(computedHash, "hex");
+    const receivedBuf = Buffer.from(receivedHash, "hex");
+    if (computedBuf.length !== receivedBuf.length || !crypto$1.timingSafeEqual(computedBuf, receivedBuf))
       throw new core.WebhookError("Invalid Monnify signature", {
         provider: this.providerName
       });
@@ -527,35 +565,31 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
       );
     }
     const { eventType, eventData } = parsedBody;
+    const created = Math.floor(Date.now() / 1e3);
+    const results = [];
+    results.push({
+      id: `monnify:${eventType}:${crypto.randomUUID()}`,
+      type: `monnify.${eventType}`,
+      created,
+      data: eventData,
+      is_raw: true
+    });
     const eventMapper = monnifyToPaykitEventMap[eventType];
-    if (!eventMapper) {
-      throw new core.WebhookError("Unknown Monnify event type", {
-        provider: this.providerName
+    const standardType = typeof eventMapper === "function" ? eventMapper(eventData) : eventMapper;
+    if (standardType) {
+      results.push({
+        id: `paykit:${eventType}:${crypto.randomUUID()}`,
+        type: standardType,
+        created,
+        data: eventData
+        // todo: add mapper for event data
       });
+    } else if (this.opts.debug) {
+      console.info(
+        `[Monnify] No standard mapping for event: ${eventType}. Available as raw event.`
+      );
     }
-    if (typeof eventMapper === "function") {
-      const event = eventMapper(eventData);
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    } else {
-      const event = eventMapper;
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    }
+    return results;
   };
 };
 

package/dist/index.mjs

@@ -1,4 +1,5 @@
-import { schema, Schema, validateRequiredKeys, AbstractPayKitProvider, HTTPClient, OAuth2TokenManager, ValidationError, OperationFailedError, createCheckoutSchema, isEmailCustomer, InvalidTypeError, PAYKIT_METADATA_KEY, ProviderNotSupportedError, createRefundSchema, WebhookError, parseJSON, omitInternalMetadata } from '@paykit-sdk/core';
+import { schema, Schema, validateRequiredKeys, AbstractPayKitProvider, HTTPClient, OAuth2TokenManager, ValidationError, OperationFailedError, createCheckoutSchema, isEmailCustomer, InvalidTypeError, PAYKIT_METADATA_KEY, ProviderNotSupportedError, createPaymentSchema, createRefundSchema, WebhookError, parseJSON, omitInternalMetadata } from '@paykit-sdk/core';
+import { timingSafeEqual } from 'crypto';
 import { sha512 } from 'js-sha512';
 
 // src/index.ts
@@ -208,6 +209,48 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
     }
     return altResponse.value.responseBody;
   }
+  /**
+   * Monnify only has one way to move money: a hosted redirect
+   * transaction. createCheckout and createPayment both boil down to
+   * this same call - only the input validation and the response
+   * mapper differ between the two.
+   */
+  async initializeTransaction(params) {
+    const paymentReference = crypto.randomUUID();
+    const body = {
+      amount: params.amount,
+      paymentReference,
+      paymentDescription: params.description,
+      currencyCode: params.currency,
+      redirectUrl: params.redirectUrl,
+      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      metadata: params.metadata,
+      customerEmail: params.email
+    };
+    const response = await this._client.post(
+      "/v1/merchant/transactions/init-transaction",
+      {
+        body: JSON.stringify(body),
+        headers: await this.tokenManager.getAuthHeaders()
+      }
+    );
+    const responseBody = this.ensureResponse(
+      response,
+      "initializeTransaction"
+    );
+    const transactionReference = responseBody.transactionReference;
+    const checkoutUrl = responseBody.checkoutUrl;
+    const transactionResponse = await this._client.get(
+      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
+      { headers: await this.tokenManager.getAuthHeaders() }
+    );
+    const transactionData = this.ensureResponse(
+      transactionResponse,
+      "initializeTransaction",
+      "Failed to retrieve transaction details"
+    );
+    return { ...transactionData, checkoutUrl, transactionReference };
+  }
   createCheckout = async (params) => {
     const data = this.validateSchema(
       createCheckoutSchema,
@@ -230,50 +273,21 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
       data.provider_metadata ?? { currency: "NGN" },
       "The following fields must be present in the provider_metadata of createCheckout: {keys}"
     );
-    const paymentReference = crypto.randomUUID();
-    const body = {
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
       amount,
-      paymentReference,
-      paymentDescription: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
-      currencyCode: currency,
+      currency,
       redirectUrl: data.success_url,
-      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      description: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
       metadata: {
         ...params.metadata,
         [PAYKIT_METADATA_KEY]: JSON.stringify({
           item: data.item_id,
           qty: data.quantity
         })
-      },
-      customerEmail: data.customer.email
-    };
-    const response = await this._client.post(
-      "/v1/merchant/transactions/init-transaction",
-      {
-        body: JSON.stringify(body),
-        headers: await this.tokenManager.getAuthHeaders()
       }
-    );
-    const responseBody = this.ensureResponse(
-      response,
-      "createCheckout"
-    );
-    const transactionReference = responseBody.transactionReference;
-    const checkoutUrl = responseBody.checkoutUrl;
-    const checkoutResponse = await this._client.get(
-      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
-      { headers: await this.tokenManager.getAuthHeaders() }
-    );
-    const checkoutData = this.ensureResponse(
-      checkoutResponse,
-      "createCheckout",
-      "Failed to retrieve checkout details"
-    );
-    return Checkout$inboundSchema({
-      ...checkoutData,
-      checkoutUrl,
-      transactionReference
     });
+    return Checkout$inboundSchema(transactionData);
   };
   retrieveCheckout = async (id) => {
     const transactionData = await this.queryTransaction(
@@ -392,14 +406,39 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
     );
   };
   createPayment = async (params) => {
-    throw new ProviderNotSupportedError(
-      "createPayment",
-      "Moniepoint",
-      {
-        reason: "Moniepoint doesn't support creating payments",
-        alternative: "Use the createPayment method instead"
-      }
+    const data = this.validateSchema(
+      createPaymentSchema,
+      params,
+      "createPayment"
     );
+    if (!isEmailCustomer(data.customer)) {
+      throw new InvalidTypeError(
+        "customer",
+        "object (customer) with email",
+        "string (customer ID)",
+        {
+          provider: this.providerName,
+          method: "createPayment"
+        }
+      );
+    }
+    const { success_url } = validateRequiredKeys(
+      ["success_url"],
+      data.provider_metadata ?? {},
+      "The following fields must be present in the provider_metadata of createPayment: {keys}"
+    );
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
+      amount: data.amount.toString(),
+      currency: data.currency,
+      redirectUrl: success_url,
+      description: `Payment for ${data.item_id}`,
+      metadata: {
+        ...data.metadata,
+        [PAYKIT_METADATA_KEY]: JSON.stringify({ item: data.item_id })
+      }
+    });
+    return Payment$inboundSchema(transactionData);
   };
   retrievePayment = async (id) => {
     try {
@@ -501,11 +540,10 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
         provider: this.providerName
       });
     }
-    const computedHash = sha512.hmac(
-      webhookSecret,
-      JSON.stringify(body)
-    );
-    if (computedHash !== receivedHash)
+    const computedHash = sha512.hmac(webhookSecret, body);
+    const computedBuf = Buffer.from(computedHash, "hex");
+    const receivedBuf = Buffer.from(receivedHash, "hex");
+    if (computedBuf.length !== receivedBuf.length || !timingSafeEqual(computedBuf, receivedBuf))
       throw new WebhookError("Invalid Monnify signature", {
         provider: this.providerName
       });
@@ -525,35 +563,31 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
       );
     }
     const { eventType, eventData } = parsedBody;
+    const created = Math.floor(Date.now() / 1e3);
+    const results = [];
+    results.push({
+      id: `monnify:${eventType}:${crypto.randomUUID()}`,
+      type: `monnify.${eventType}`,
+      created,
+      data: eventData,
+      is_raw: true
+    });
     const eventMapper = monnifyToPaykitEventMap[eventType];
-    if (!eventMapper) {
-      throw new WebhookError("Unknown Monnify event type", {
-        provider: this.providerName
+    const standardType = typeof eventMapper === "function" ? eventMapper(eventData) : eventMapper;
+    if (standardType) {
+      results.push({
+        id: `paykit:${eventType}:${crypto.randomUUID()}`,
+        type: standardType,
+        created,
+        data: eventData
+        // todo: add mapper for event data
       });
+    } else if (this.opts.debug) {
+      console.info(
+        `[Monnify] No standard mapping for event: ${eventType}. Available as raw event.`
+      );
     }
-    if (typeof eventMapper === "function") {
-      const event = eventMapper(eventData);
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    } else {
-      const event = eventMapper;
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    }
+    return results;
   };
 };
 

package/dist/monnify-provider.d.mts

@@ -1,6 +1,18 @@
 import { PaykitProviderOptions, AbstractPayKitProvider, PayKitProvider, ProviderMetadataRegistry, CreateCheckoutSchema, Checkout, UpdateCheckoutSchema, CreateCustomerParams, Customer, UpdateCustomerParams, CreateSubscriptionSchema, Subscription, UpdateSubscriptionSchema, CreatePaymentSchema, Payment, UpdatePaymentSchema, CapturePaymentSchema, CreateRefundSchema, Refund, WebhookHandlerConfig, WebhookEventPayload } from '@paykit-sdk/core';
 
 interface MonnifyMetadata extends ProviderMetadataRegistry {
+    checkout?: {
+        amount?: string;
+        currency?: string;
+    };
+    payment?: {
+        /**
+         * Monnify only supports hosted/redirect transactions - a
+         * direct createPayment call still needs somewhere to send the
+         * customer, same as createCheckout's success_url.
+         */
+        success_url?: string;
+    };
 }
 interface MonnifyRawEvents extends Record<string, any> {
 }
@@ -39,6 +51,13 @@ declare class MonnifyProvider extends AbstractPayKitProvider implements PayKitPr
      * Queries transaction by transactionReference or paymentReference (with fallback)
      */
     private queryTransaction;
+    /**
+     * Monnify only has one way to move money: a hosted redirect
+     * transaction. createCheckout and createPayment both boil down to
+     * this same call - only the input validation and the response
+     * mapper differ between the two.
+     */
+    private initializeTransaction;
     createCheckout: (params: CreateCheckoutSchema) => Promise<Checkout>;
     retrieveCheckout: (id: string) => Promise<Checkout>;
     updateCheckout: (id: string, params: UpdateCheckoutSchema) => Promise<Checkout>;
@@ -52,7 +71,7 @@ declare class MonnifyProvider extends AbstractPayKitProvider implements PayKitPr
     cancelSubscription: (id: string) => Promise<Subscription>;
     deleteSubscription: (id: string) => Promise<null>;
     retrieveSubscription: (id: string) => Promise<Subscription | null>;
-    createPayment: (params: CreatePaymentSchema) => Promise<Payment>;
+    createPayment: (params: CreatePaymentSchema<MonnifyMetadata["payment"]>) => Promise<Payment>;
     retrievePayment: (id: string) => Promise<Payment | null>;
     updatePayment: (id: string, params: UpdatePaymentSchema) => Promise<Payment>;
     deletePayment: (id: string) => Promise<null>;

package/dist/monnify-provider.d.ts

@@ -1,6 +1,18 @@
 import { PaykitProviderOptions, AbstractPayKitProvider, PayKitProvider, ProviderMetadataRegistry, CreateCheckoutSchema, Checkout, UpdateCheckoutSchema, CreateCustomerParams, Customer, UpdateCustomerParams, CreateSubscriptionSchema, Subscription, UpdateSubscriptionSchema, CreatePaymentSchema, Payment, UpdatePaymentSchema, CapturePaymentSchema, CreateRefundSchema, Refund, WebhookHandlerConfig, WebhookEventPayload } from '@paykit-sdk/core';
 
 interface MonnifyMetadata extends ProviderMetadataRegistry {
+    checkout?: {
+        amount?: string;
+        currency?: string;
+    };
+    payment?: {
+        /**
+         * Monnify only supports hosted/redirect transactions - a
+         * direct createPayment call still needs somewhere to send the
+         * customer, same as createCheckout's success_url.
+         */
+        success_url?: string;
+    };
 }
 interface MonnifyRawEvents extends Record<string, any> {
 }
@@ -39,6 +51,13 @@ declare class MonnifyProvider extends AbstractPayKitProvider implements PayKitPr
      * Queries transaction by transactionReference or paymentReference (with fallback)
      */
     private queryTransaction;
+    /**
+     * Monnify only has one way to move money: a hosted redirect
+     * transaction. createCheckout and createPayment both boil down to
+     * this same call - only the input validation and the response
+     * mapper differ between the two.
+     */
+    private initializeTransaction;
     createCheckout: (params: CreateCheckoutSchema) => Promise<Checkout>;
     retrieveCheckout: (id: string) => Promise<Checkout>;
     updateCheckout: (id: string, params: UpdateCheckoutSchema) => Promise<Checkout>;
@@ -52,7 +71,7 @@ declare class MonnifyProvider extends AbstractPayKitProvider implements PayKitPr
     cancelSubscription: (id: string) => Promise<Subscription>;
     deleteSubscription: (id: string) => Promise<null>;
     retrieveSubscription: (id: string) => Promise<Subscription | null>;
-    createPayment: (params: CreatePaymentSchema) => Promise<Payment>;
+    createPayment: (params: CreatePaymentSchema<MonnifyMetadata["payment"]>) => Promise<Payment>;
     retrievePayment: (id: string) => Promise<Payment | null>;
     updatePayment: (id: string, params: UpdatePaymentSchema) => Promise<Payment>;
     deletePayment: (id: string) => Promise<null>;

package/dist/monnify-provider.js

@@ -1,6 +1,7 @@
 'use strict';
 
 var core = require('@paykit-sdk/core');
+var crypto$1 = require('crypto');
 var jsSha512 = require('js-sha512');
 
 // src/monnify-provider.ts
@@ -210,6 +211,48 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
     }
     return altResponse.value.responseBody;
   }
+  /**
+   * Monnify only has one way to move money: a hosted redirect
+   * transaction. createCheckout and createPayment both boil down to
+   * this same call - only the input validation and the response
+   * mapper differ between the two.
+   */
+  async initializeTransaction(params) {
+    const paymentReference = crypto.randomUUID();
+    const body = {
+      amount: params.amount,
+      paymentReference,
+      paymentDescription: params.description,
+      currencyCode: params.currency,
+      redirectUrl: params.redirectUrl,
+      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      metadata: params.metadata,
+      customerEmail: params.email
+    };
+    const response = await this._client.post(
+      "/v1/merchant/transactions/init-transaction",
+      {
+        body: JSON.stringify(body),
+        headers: await this.tokenManager.getAuthHeaders()
+      }
+    );
+    const responseBody = this.ensureResponse(
+      response,
+      "initializeTransaction"
+    );
+    const transactionReference = responseBody.transactionReference;
+    const checkoutUrl = responseBody.checkoutUrl;
+    const transactionResponse = await this._client.get(
+      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
+      { headers: await this.tokenManager.getAuthHeaders() }
+    );
+    const transactionData = this.ensureResponse(
+      transactionResponse,
+      "initializeTransaction",
+      "Failed to retrieve transaction details"
+    );
+    return { ...transactionData, checkoutUrl, transactionReference };
+  }
   createCheckout = async (params) => {
     const data = this.validateSchema(
       core.createCheckoutSchema,
@@ -232,50 +275,21 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
       data.provider_metadata ?? { currency: "NGN" },
       "The following fields must be present in the provider_metadata of createCheckout: {keys}"
     );
-    const paymentReference = crypto.randomUUID();
-    const body = {
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
       amount,
-      paymentReference,
-      paymentDescription: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
-      currencyCode: currency,
+      currency,
       redirectUrl: data.success_url,
-      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      description: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
       metadata: {
         ...params.metadata,
         [core.PAYKIT_METADATA_KEY]: JSON.stringify({
           item: data.item_id,
           qty: data.quantity
         })
-      },
-      customerEmail: data.customer.email
-    };
-    const response = await this._client.post(
-      "/v1/merchant/transactions/init-transaction",
-      {
-        body: JSON.stringify(body),
-        headers: await this.tokenManager.getAuthHeaders()
       }
-    );
-    const responseBody = this.ensureResponse(
-      response,
-      "createCheckout"
-    );
-    const transactionReference = responseBody.transactionReference;
-    const checkoutUrl = responseBody.checkoutUrl;
-    const checkoutResponse = await this._client.get(
-      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
-      { headers: await this.tokenManager.getAuthHeaders() }
-    );
-    const checkoutData = this.ensureResponse(
-      checkoutResponse,
-      "createCheckout",
-      "Failed to retrieve checkout details"
-    );
-    return Checkout$inboundSchema({
-      ...checkoutData,
-      checkoutUrl,
-      transactionReference
     });
+    return Checkout$inboundSchema(transactionData);
   };
   retrieveCheckout = async (id) => {
     const transactionData = await this.queryTransaction(
@@ -394,14 +408,39 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
     );
   };
   createPayment = async (params) => {
-    throw new core.ProviderNotSupportedError(
-      "createPayment",
-      "Moniepoint",
-      {
-        reason: "Moniepoint doesn't support creating payments",
-        alternative: "Use the createPayment method instead"
-      }
+    const data = this.validateSchema(
+      core.createPaymentSchema,
+      params,
+      "createPayment"
     );
+    if (!core.isEmailCustomer(data.customer)) {
+      throw new core.InvalidTypeError(
+        "customer",
+        "object (customer) with email",
+        "string (customer ID)",
+        {
+          provider: this.providerName,
+          method: "createPayment"
+        }
+      );
+    }
+    const { success_url } = core.validateRequiredKeys(
+      ["success_url"],
+      data.provider_metadata ?? {},
+      "The following fields must be present in the provider_metadata of createPayment: {keys}"
+    );
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
+      amount: data.amount.toString(),
+      currency: data.currency,
+      redirectUrl: success_url,
+      description: `Payment for ${data.item_id}`,
+      metadata: {
+        ...data.metadata,
+        [core.PAYKIT_METADATA_KEY]: JSON.stringify({ item: data.item_id })
+      }
+    });
+    return Payment$inboundSchema(transactionData);
   };
   retrievePayment = async (id) => {
     try {
@@ -503,11 +542,10 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
         provider: this.providerName
       });
     }
-    const computedHash = jsSha512.sha512.hmac(
-      webhookSecret,
-      JSON.stringify(body)
-    );
-    if (computedHash !== receivedHash)
+    const computedHash = jsSha512.sha512.hmac(webhookSecret, body);
+    const computedBuf = Buffer.from(computedHash, "hex");
+    const receivedBuf = Buffer.from(receivedHash, "hex");
+    if (computedBuf.length !== receivedBuf.length || !crypto$1.timingSafeEqual(computedBuf, receivedBuf))
       throw new core.WebhookError("Invalid Monnify signature", {
         provider: this.providerName
       });
@@ -527,35 +565,31 @@ var MonnifyProvider = class extends core.AbstractPayKitProvider {
       );
     }
     const { eventType, eventData } = parsedBody;
+    const created = Math.floor(Date.now() / 1e3);
+    const results = [];
+    results.push({
+      id: `monnify:${eventType}:${crypto.randomUUID()}`,
+      type: `monnify.${eventType}`,
+      created,
+      data: eventData,
+      is_raw: true
+    });
     const eventMapper = monnifyToPaykitEventMap[eventType];
-    if (!eventMapper) {
-      throw new core.WebhookError("Unknown Monnify event type", {
-        provider: this.providerName
+    const standardType = typeof eventMapper === "function" ? eventMapper(eventData) : eventMapper;
+    if (standardType) {
+      results.push({
+        id: `paykit:${eventType}:${crypto.randomUUID()}`,
+        type: standardType,
+        created,
+        data: eventData
+        // todo: add mapper for event data
       });
+    } else if (this.opts.debug) {
+      console.info(
+        `[Monnify] No standard mapping for event: ${eventType}. Available as raw event.`
+      );
     }
-    if (typeof eventMapper === "function") {
-      const event = eventMapper(eventData);
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    } else {
-      const event = eventMapper;
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    }
+    return results;
   };
 };
 

package/dist/monnify-provider.mjs

@@ -1,4 +1,5 @@
-import { schema, Schema, AbstractPayKitProvider, HTTPClient, OAuth2TokenManager, ValidationError, OperationFailedError, createCheckoutSchema, isEmailCustomer, InvalidTypeError, validateRequiredKeys, PAYKIT_METADATA_KEY, ProviderNotSupportedError, createRefundSchema, WebhookError, parseJSON, omitInternalMetadata } from '@paykit-sdk/core';
+import { schema, Schema, AbstractPayKitProvider, HTTPClient, OAuth2TokenManager, ValidationError, OperationFailedError, createCheckoutSchema, isEmailCustomer, InvalidTypeError, validateRequiredKeys, PAYKIT_METADATA_KEY, ProviderNotSupportedError, createPaymentSchema, createRefundSchema, WebhookError, parseJSON, omitInternalMetadata } from '@paykit-sdk/core';
+import { timingSafeEqual } from 'crypto';
 import { sha512 } from 'js-sha512';
 
 // src/monnify-provider.ts
@@ -208,6 +209,48 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
     }
     return altResponse.value.responseBody;
   }
+  /**
+   * Monnify only has one way to move money: a hosted redirect
+   * transaction. createCheckout and createPayment both boil down to
+   * this same call - only the input validation and the response
+   * mapper differ between the two.
+   */
+  async initializeTransaction(params) {
+    const paymentReference = crypto.randomUUID();
+    const body = {
+      amount: params.amount,
+      paymentReference,
+      paymentDescription: params.description,
+      currencyCode: params.currency,
+      redirectUrl: params.redirectUrl,
+      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      metadata: params.metadata,
+      customerEmail: params.email
+    };
+    const response = await this._client.post(
+      "/v1/merchant/transactions/init-transaction",
+      {
+        body: JSON.stringify(body),
+        headers: await this.tokenManager.getAuthHeaders()
+      }
+    );
+    const responseBody = this.ensureResponse(
+      response,
+      "initializeTransaction"
+    );
+    const transactionReference = responseBody.transactionReference;
+    const checkoutUrl = responseBody.checkoutUrl;
+    const transactionResponse = await this._client.get(
+      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
+      { headers: await this.tokenManager.getAuthHeaders() }
+    );
+    const transactionData = this.ensureResponse(
+      transactionResponse,
+      "initializeTransaction",
+      "Failed to retrieve transaction details"
+    );
+    return { ...transactionData, checkoutUrl, transactionReference };
+  }
   createCheckout = async (params) => {
     const data = this.validateSchema(
       createCheckoutSchema,
@@ -230,50 +273,21 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
       data.provider_metadata ?? { currency: "NGN" },
       "The following fields must be present in the provider_metadata of createCheckout: {keys}"
     );
-    const paymentReference = crypto.randomUUID();
-    const body = {
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
       amount,
-      paymentReference,
-      paymentDescription: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
-      currencyCode: currency,
+      currency,
       redirectUrl: data.success_url,
-      paymentMethods: ["CARD", "ACCOUNT_TRANSFER"],
+      description: `Checkout for ${data.item_id} x ${data.quantity} item${data.quantity > 1 ? "s" : ""}`,
       metadata: {
         ...params.metadata,
         [PAYKIT_METADATA_KEY]: JSON.stringify({
           item: data.item_id,
           qty: data.quantity
         })
-      },
-      customerEmail: data.customer.email
-    };
-    const response = await this._client.post(
-      "/v1/merchant/transactions/init-transaction",
-      {
-        body: JSON.stringify(body),
-        headers: await this.tokenManager.getAuthHeaders()
       }
-    );
-    const responseBody = this.ensureResponse(
-      response,
-      "createCheckout"
-    );
-    const transactionReference = responseBody.transactionReference;
-    const checkoutUrl = responseBody.checkoutUrl;
-    const checkoutResponse = await this._client.get(
-      `/v2/merchant/transactions/query?paymentReference=${paymentReference}`,
-      { headers: await this.tokenManager.getAuthHeaders() }
-    );
-    const checkoutData = this.ensureResponse(
-      checkoutResponse,
-      "createCheckout",
-      "Failed to retrieve checkout details"
-    );
-    return Checkout$inboundSchema({
-      ...checkoutData,
-      checkoutUrl,
-      transactionReference
     });
+    return Checkout$inboundSchema(transactionData);
   };
   retrieveCheckout = async (id) => {
     const transactionData = await this.queryTransaction(
@@ -392,14 +406,39 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
     );
   };
   createPayment = async (params) => {
-    throw new ProviderNotSupportedError(
-      "createPayment",
-      "Moniepoint",
-      {
-        reason: "Moniepoint doesn't support creating payments",
-        alternative: "Use the createPayment method instead"
-      }
+    const data = this.validateSchema(
+      createPaymentSchema,
+      params,
+      "createPayment"
     );
+    if (!isEmailCustomer(data.customer)) {
+      throw new InvalidTypeError(
+        "customer",
+        "object (customer) with email",
+        "string (customer ID)",
+        {
+          provider: this.providerName,
+          method: "createPayment"
+        }
+      );
+    }
+    const { success_url } = validateRequiredKeys(
+      ["success_url"],
+      data.provider_metadata ?? {},
+      "The following fields must be present in the provider_metadata of createPayment: {keys}"
+    );
+    const transactionData = await this.initializeTransaction({
+      email: data.customer.email,
+      amount: data.amount.toString(),
+      currency: data.currency,
+      redirectUrl: success_url,
+      description: `Payment for ${data.item_id}`,
+      metadata: {
+        ...data.metadata,
+        [PAYKIT_METADATA_KEY]: JSON.stringify({ item: data.item_id })
+      }
+    });
+    return Payment$inboundSchema(transactionData);
   };
   retrievePayment = async (id) => {
     try {
@@ -501,11 +540,10 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
         provider: this.providerName
       });
     }
-    const computedHash = sha512.hmac(
-      webhookSecret,
-      JSON.stringify(body)
-    );
-    if (computedHash !== receivedHash)
+    const computedHash = sha512.hmac(webhookSecret, body);
+    const computedBuf = Buffer.from(computedHash, "hex");
+    const receivedBuf = Buffer.from(receivedHash, "hex");
+    if (computedBuf.length !== receivedBuf.length || !timingSafeEqual(computedBuf, receivedBuf))
       throw new WebhookError("Invalid Monnify signature", {
         provider: this.providerName
       });
@@ -525,35 +563,31 @@ var MonnifyProvider = class extends AbstractPayKitProvider {
       );
     }
     const { eventType, eventData } = parsedBody;
+    const created = Math.floor(Date.now() / 1e3);
+    const results = [];
+    results.push({
+      id: `monnify:${eventType}:${crypto.randomUUID()}`,
+      type: `monnify.${eventType}`,
+      created,
+      data: eventData,
+      is_raw: true
+    });
     const eventMapper = monnifyToPaykitEventMap[eventType];
-    if (!eventMapper) {
-      throw new WebhookError("Unknown Monnify event type", {
-        provider: this.providerName
+    const standardType = typeof eventMapper === "function" ? eventMapper(eventData) : eventMapper;
+    if (standardType) {
+      results.push({
+        id: `paykit:${eventType}:${crypto.randomUUID()}`,
+        type: standardType,
+        created,
+        data: eventData
+        // todo: add mapper for event data
       });
+    } else if (this.opts.debug) {
+      console.info(
+        `[Monnify] No standard mapping for event: ${eventType}. Available as raw event.`
+      );
     }
-    if (typeof eventMapper === "function") {
-      const event = eventMapper(eventData);
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    } else {
-      const event = eventMapper;
-      return [
-        {
-          type: event,
-          created: (/* @__PURE__ */ new Date()).getTime(),
-          id: `paykit:webhook:${Math.random().toString(36).substring(2, 15)}`,
-          data: eventData
-          // todo: add mapper for event data
-        }
-      ];
-    }
+    return results;
   };
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paykit-sdk/monnify",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "description": "Moniepoint provider for PayKit",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -18,19 +18,16 @@
   "paykit": {
     "type": "provider"
   },
-  "scripts": {
-    "build": "tsup"
-  },
   "keywords": [],
   "license": "ISC",
   "author": "Emmanuel Odii",
   "peerDependencies": {
-    "@paykit-sdk/core": ">=1.2.0"
+    "@paykit-sdk/core": "^1.2.3"
   },
   "devDependencies": {
-    "@paykit-sdk/core": "workspace:*",
     "tsup": "^8.5.0",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "@paykit-sdk/core": "1.3.1"
   },
   "dependencies": {
     "js-sha512": "^0.9.0"
@@ -44,5 +41,10 @@
   },
   "bugs": {
     "url": "https://github.com/usepaykit/paykit-sdk/issues"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run --config ../../vitest.config.ts packages/monnify/src",
+    "typecheck": "tsc --noEmit"
   }
-}
+}