Accepting Payments

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

Step 1: Connect a Payment Processor

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

1
Open the Hyperswitch Dashboard
Navigate to localhost:8081 in your browser.
2
Go to Settings → Connectors
Click + Add Connector and select your processor.
3
Enter API credentials
Paste your secret key from the processor dashboard.
4
Enable the connector
Toggle it on and save. Test the connection with the built-in test button.

Step 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.

Step 3: Create a Payment (API)

Create a payment intent on your backend server:

// 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.

Step 4: 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 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 →

Step 5: Test in Sandbox

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

Card Number	Result	Use Case
4084 0840 8408 4081	Success	Happy path
4084 0840 8408 4040	Insufficient funds	Failure handling
5060 6666 6666 6666	Success (Verve)	Local card support

Step 6: 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