Monnify

npm install @paykit-sdk/monnify

const checkout = await paykit.checkouts.create({
  customer: { email: 'user@example.com' },
  item_id: 'my-product',
  session_type: 'one_time',
  quantity: 1,
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  provider_metadata: {
    amount: 5000, // in the standard currency unit (e.g. Naira)
    currency: 'NGN',
  },
});

// Redirect the customer to checkout.payment_url

// Once they're back, confirm the payment
const payment = await paykit.payments.retrieve(checkout.id);

const webhook = paykit.webhooks
  .setup({ webhookSecret: process.env.MONNIFY_WEBHOOK_SECRET! })
  .on('payment.created', async event => {
    /* SUCCESSFUL_TRANSACTION */
  })
  .on('payment.failed', async event => {
    /* REJECTED_PAYMENT */
  })
  .on('payment.updated', async event => {
    /* SETTLEMENT */
  })
  .on('refund.created', async event => {
    /* refund succeeded or failed */
  });

await webhook.handle({
  body: rawBody,
  headersAsObject: Object.fromEntries(request.headers),
  fullUrl: request.url,
});

paykit.webhooks
  .setup({ webhookSecret: process.env.MONNIFY_WEBHOOK_SECRET! })
  .on('monnify.SUCCESSFUL_TRANSACTION', async event => {
    // event.data is the raw Monnify transaction payload
  })
  .on('monnify.MANDATE_UPDATE', async event => {
    // event.data is the raw Monnify mandate payload
  });

// checkout.provider_metadata requires amount and currency
await paykit.checkouts.create({
  customer: { email: 'user@example.com' },
  item_id: 'my-product',
  session_type: 'one_time',
  quantity: 1,
  success_url: 'https://example.com/success',
  cancel_url: 'https://example.com/cancel',
  provider_metadata: {
    amount: 5000, // in the standard currency unit (e.g. Naira)
    currency: 'NGN',
  },
});

// payment.provider_metadata requires success_url — Monnify still redirects
// the customer even for a "direct" payment
await paykit.payments.create({
  customer: { email: 'user@example.com' },
  item_id: 'my-product',
  amount: 5000,
  currency: 'NGN',
  provider_metadata: {
    success_url: 'https://example.com/success', // required
  },
});

// refund.provider_metadata — any extra fields are forwarded to Monnify's refund endpoint
await paykit.refunds.create({
  payment_id: 'MNFY|...',
  amount: 1000,
  reason: 'Customer request',
});