Overview

E-commerce platforms need a payment experience that is fast, familiar, and resilient. Customers expect to pay by card, bank transfer, or USSD without friction, and merchants need real-time confirmation of payment before fulfilling orders. Novac covers all of this, from initiating a checkout session and presenting a payment UI, to verifying the result server-side and issuing refunds when needed.

How It Works

Prerequisites

See details

Create an account with completed KYC
Obtain your API keys Public key for checkout, Secret key for verification and refunds
A publicly accessible callbackURL where Novac will redirect customers after payment
A webhookURL registered in your Novac dashboard for server-to-server event notifications

Create a Checkout Payment

When a customer clicks “Pay”, your server initiates a checkout payment with Novac. This returns a checkoutUrl to redirect the customer and a transactionReference to track the payment.

Prebuilt Checkout
Custom Checkout

Use Novac’s hosted checkout page to complete payment, all payment methods included based on your preference settings.

Request

curl --request POST \
  --url https://api.novacpayment.com/api/v1/checkout \
  --header 'Authorization: Bearer <your-public-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 25000,
    "currency": "NGN",
    "email": "customer@example.com",
    "reference": "ORDER-00123",
    "callbackUrl": "https://yourstore.com/payment/callback",
    "redirectUrl": "https://yourstore.com/order/confirm"
  }'

Redirect the customer to the checkoutUrl returned in the response.Full guide > Prebuilt Checkout

Handle the Callback

After payment, Novac redirects the customer back to your callbackURL with query parameters:

GET {your-callback-url}?reference=<string>&status=<string>

Never trust the status parameter in the callback URL alone. Always verify the transaction server-side before fulfilling an order.

Verify the Transaction

Make a server-side GET request to confirm the actual payment status from Novac’s API.

Request

curl --request GET \
  --url https://api.novacpayment.com/api/v1/checkout/ORDER-00123/verify \
  --header 'Authorization: Bearer <your-secret-key>'

Response

{
  "status": true,
  "message": "Transaction details retrieved successfully",
  "data": {
    "status": "successful",
    "transactionReference": "ORDER-00123",
    "amount": 25000,
    "chargedAmount": 25000,
    "currency": "NGN",
    "channel": "card",
    "customer": {
      "email": "customer@example.com",
      "name": "Ada Obi"
    }
  }
}

Only fulfill the order when data.status is "successful". Full guide → Verify a Transaction

Listen for Webhooks

In addition to the callback, configure a webhook so your server receives real-time event notifications — even if the customer closes the browser before being redirected.

Webhook Payload (example)

{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "transactionReference": "ORDER-00123",
    "amount": 25000,
    "status": "successful",
    "currency": "NGN",
    "customer": {
      "email": "customer@example.com",
      "name": "Ada Obi"
    }
  }
}

Always verify the transaction via the API after receiving a webhook. Do not rely solely on the webhook payload for order fulfilment.

Full guide → Webhooks

Handle Refunds

If a customer requests a refund, use Novac’s Refund API. You can issue a full or partial refund.

Full Refund

curl --request POST \
  --url https://api.novacpayment.com/api/v1/refund \
  --header 'Authorization: Bearer <your-secret-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "reference": "ORDER-00123"
  }'

Full guide → Refund a Transaction

What’s Next?

Best Practices - Security and reliability guidelines for production integrations.
Common Errors - Troubleshoot failed requests and API error codes.
Testing - Simulate payment flows in the test environment before going live.

​Overview

​How It Works

​Prerequisites

​Create a Checkout Payment

​Handle the Callback

​Verify the Transaction

​Listen for Webhooks

​Handle Refunds

​What’s Next?

Overview

How It Works

Prerequisites

Create a Checkout Payment

Handle the Callback

Verify the Transaction

Listen for Webhooks

Handle Refunds

What’s Next?