DocsGuidesAccepting Payments
Back to docs

Accepting Payments

A step-by-step guide to accepting card payments with OpenPay — from connecting a processor to capturing funds.

1

Connect a Payment Processor

Before accepting payments, connect at least one payment processor (connector) like Paystack.

  1. 1

    Open the Hyperswitch Dashboard

    Navigate to localhost:8081 in your browser.

  2. 2

    Go to Settings → Connectors

    Click + Add Connector and select your processor.

  3. 3

    Enter API credentials

    Paste your secret key from the processor dashboard.

  4. 4

    Enable the connector

    Toggle it on and save. Test the connection with the built-in test button.

2

Choose Your Integration Method

Recommended
🌐

Hosted Checkout

Redirect or iframe a payment page hosted by Hyperswitch. Simplest integration — customers enter card details on a secure page.

⚡

API Only

Build your own checkout UI. Collect card details on your frontend and send them to Hyperswitch via API. Full control over the UI.

📊

Dashboard

Create payments manually from the merchant dashboard. Best for phone orders, invoicing, or one-time payments.

Create a Payment (API)

Create a payment intent on your backend server:

Node.js / Express
// Node.js / Express example
const response = await fetch("http://localhost:8081/payments", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "api-key": "YOUR_HYPERSWITCH_API_KEY",
  },
  body: JSON.stringify({
    amount: 5000,       // Amount in smallest currency unit (kobo for NGN)
    currency: "NGN",
    confirm: true,      // Process immediately
    description: "Order #42",
    email: "customer@example.com",
  }),
});

const payment = await response.json();
console.log(payment.payment_id);  // pay_xyz789
console.log(payment.status);       // Succeeded

For a full code walkthrough, see the First Payment guide.

Handle Webhooks

Webhooks notify your application about payment status changes. Even if you use confirm: true, always verify payment status via webhook to prevent race conditions.

Webhook Endpoint
// Webhook endpoint example (Node.js / Express)
app.post("/webhooks/openpay", async (req, res) => {
  const event = req.body;

  switch (event.event_type) {
    case "payments.payment_intent.succeeded":
      // Fulfill the order
      await fulfillOrder(event.data);
      break;

    case "payments.payment_intent.failed":
      // Notify the customer, update order status
      await notifyCustomer(event.data);
      break;
  }

  res.status(200).json({ received: true });
});
Full Webhook Guide →

Test in Sandbox

Use Paystack test cards to verify your integration end-to-end before going live:

Card NumberResultUse Case
4084 0840 8408 4081SuccessHappy path
4084 0840 8408 4040Insufficient fundsFailure handling
5060 6666 6666 6666Success (Verve)Local card support

Go Live

Production Checklist

  • ✓Switch connector credentials to live API keys
  • ✓Set up webhook endpoint with HTTPS in production
  • ✓Configure webhook signing secret for signature verification
  • ✓Enable rate limiting on public-facing endpoints
  • ✓Set up monitoring and alerting
  • ✓Review fraud detection rules for your risk tolerance