> ## Documentation Index
> Fetch the complete documentation index at: https://developer.novacpayment.com/llms.txt
> Use this file to discover all available pages before exploring further.

# E-Commerce Platforms

> Learn how to integrate Novac into an e-commerce store to accept payments, handle post-payment callbacks, and process refunds.

# 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

```mermaid theme={null}
sequenceDiagram
  participant C as Customer
  participant S as Your Server
  participant N as Novac

  C->>S: Proceeds to checkout
  S->>N: POST /checkout (creates transaction)
  N-->>S: Returns checkoutUrl + transactionRef
  S-->>C: Redirects to checkoutUrl
  C->>N: Completes payment (card / transfer / USSD)
  N-->>C: Redirects to your callbackURL
  C->>S: Lands on /payment/callback?reference=...
  S->>N: GET /checkout/{ref}/verify
  N-->>S: Returns confirmed transaction status
  S-->>C: Order confirmed
```

***

### Prerequisites

<Accordion title="See details" defaultOpen={true}>
  * [Create an account](/docs/getting-started/create-merchant-account) with completed KYC
  * [Obtain your API keys](/docs/getting-started/obtain-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
</Accordion>

***

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

<Tabs>
  <Tab title="Prebuilt Checkout">
    Use Novac's hosted checkout page to complete payment, all payment methods included based on your [preference settings](/docs/getting-started/payment-preference).

    ```bash Request theme={null}
    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](/docs/accept-payment/complete-payment/prebuilt-checkout)
  </Tab>

  <Tab title="Custom Checkout">
    Build your own checkout UI and call Novac APIs to process each payment method.

    [Full guide > Custom Checkout](/docs/accept-payment/complete-payment/custom-checkout)
  </Tab>
</Tabs>

***

### Handle the Callback

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

```http theme={null}
GET {your-callback-url}?reference=<string>&status=<string>
```

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

***

### Verify the Transaction

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

```bash Request theme={null}
curl --request GET \
  --url https://api.novacpayment.com/api/v1/checkout/ORDER-00123/verify \
  --header 'Authorization: Bearer <your-secret-key>'
```

```json Response theme={null}
{
  "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](/docs/accept-payment/manage-payment/verify-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.

```json Webhook Payload (example) theme={null}
{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "transactionReference": "ORDER-00123",
    "amount": 25000,
    "status": "successful",
    "currency": "NGN",
    "customer": {
      "email": "customer@example.com",
      "name": "Ada Obi"
    }
  }
}
```

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

[Full guide → Webhooks](/docs/api-basics/webhooks)

***

### Handle Refunds

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

```bash Full Refund theme={null}
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](/docs/accept-payment/manage-payment/refund-transaction)

***

## What's Next?

* **Best Practices** - [Security and reliability guidelines](/docs/api-basics/best-practices) for production integrations.
* **Common Errors** - [Troubleshoot failed requests](/docs/api-basics/errors) and API error codes.
* **Testing** - [Simulate payment flows in the test environment](/docs/api-basics/testing) before going live.