# Create a checkout payment with payment link reference Source: https://developer.novacpayment.com/api-reference/checkout/create-checkout-payment-with-payment-link post /api/v1/paymentlink/initiate # Create a checkout payment with transaction reference Source: https://developer.novacpayment.com/api-reference/checkout/initiate-checkout post /api/v1/initiate # Introduction Source: https://developer.novacpayment.com/api-reference/checkout/introduction Collect payments via Card, Bank Transfer, or USSD using Novac Checkout. ## Overview Checkout allows you to collect payments seamlessly through three main channels.\ This gives your customers the flexibility to choose the method most convenient to them. *** ## Quick Actions Quickly generate a secure checkout payment that is tied to a payment link created vi the dashboard. Start a new checkout session with just one request.\ Perfect for accepting payments in your app or website. Confirm the status of a transaction in real-time.\ Essential for order fulfillment and fraud checks. Double-check the outcome of a checkout session.\ Use it to reconcile records and trigger post-payment workflows. # Retrieve a checkout payment transaction Source: https://developer.novacpayment.com/api-reference/checkout/verify-checkout-transaction get /api/v1/checkout/transaction/{transactionRef} # Verify a transaction Source: https://developer.novacpayment.com/api-reference/checkout/verify-transaction get /api/v1/checkout/{transactionRef}/verify # Decrypt customer's card details Source: https://developer.novacpayment.com/api-reference/collections/decrypt-data post /api/v1/decrypt-data # Direct Card Charge Source: https://developer.novacpayment.com/api-reference/collections/direct-card-charge post /api/v1/direct-card-charge # Direct Card Charge Authentication Source: https://developer.novacpayment.com/api-reference/collections/direct-card-charge-auth post /api/v1/direct-card-charge-auth # Encrypt customer's card details Source: https://developer.novacpayment.com/api-reference/collections/encrypt-data post /api/v1/encrypt-data # Introduction Source: https://developer.novacpayment.com/api-reference/collections/introduction Learn how to initiate and manage card collections with Novac. ## Overview Collections allow you to accept payments directly via cards, verify transactions, and securely handle encryption, authentication, and 3DS challenges. This section provides endpoints to initiate charges, manage authentication, verify and void transactions, and handle tokenized flows. *** ## Quick Actions Initiate a direct charge on a customer’s card. Charge a previously tokenized card securely. Encrypt sensitive card or payment data. Decrypt encrypted payment data securely. Authenticate a direct card charge request. # Charge Tokenized Card Source: https://developer.novacpayment.com/api-reference/collections/tokenized-card-charge post /api/v1/tokenized-card-charge # Complete a Bank Transfer Payment Source: https://developer.novacpayment.com/api-reference/custom-checkout/complete-bank-transfer post /api/v1/bank-transfer # Complete a Card Payment Source: https://developer.novacpayment.com/api-reference/custom-checkout/complete-card-payment post /api/v1/card-payment # Complete Payment with Opay Source: https://developer.novacpayment.com/api-reference/custom-checkout/complete-payment-with-opay post /api/v1/opay-payment?transactionReference={transactionRef} # Complete Payment with Palmpay Source: https://developer.novacpayment.com/api-reference/custom-checkout/complete-payment-with-palmpay post /api/v1/palmpay-payment?transactionReference={transactionRef} # Complete a USSD Payment Source: https://developer.novacpayment.com/api-reference/custom-checkout/complete-ussd-payment post /api/v1/ussd-payment # Retrieve Banks USSD Code Source: https://developer.novacpayment.com/api-reference/custom-checkout/get-bank-ussd get /api/v1/ussd-getbanks # Introduction Source: https://developer.novacpayment.com/api-reference/custom-checkout/introduction Build custom checkout experience with APIs that power Novac hosted checkout. ## Overview Checkout allows you to collect payments seamlessly through different channels. While the existing features are sufficient, we also provide access to the API that powers the hosted checkout, allowing merchants to create a custom and tailored payment experience. *** ## Quick Actions Accept payments from customers using USSD codes.\ Includes endpoints for creating USSD requests and fetching bank-specific codes. Calculate transaction fees before charging your customer.\ Ensure transparency and better pricing control. Secure payments with OTP validation.\ Protects against fraud and ensures compliance with 2FA regulations. Allow customers to pay via direct bank transfer.\ Ideal for markets where bank transfers are widely used. Use this API to complete a card payment when it's initiated. useful for when using a custom checkout # Retrieve Transaction Fees Source: https://developer.novacpayment.com/api-reference/custom-checkout/transaction-fee post /api/v1/transaction-fee # Validate Customer's Card Details Source: https://developer.novacpayment.com/api-reference/custom-checkout/validate-card-otp post /api/v1/card/validate-otp # Initiate a transfer Source: https://developer.novacpayment.com/api-reference/payouts/initiate-transfer post /api/v1/transfers # Introduction Source: https://developer.novacpayment.com/api-reference/payouts/introduction Learn how to send payouts and manage bank transfers with Novac. ## Overview Payouts allow you to transfer funds seamlessly to bank accounts. You can retrieve supported banks, verify recipient accounts, initiate transfers, track transactions, and check available balances. This section provides all endpoints required for managing outgoing payments. *** ## Quick Actions Fetch a list of all supported banks for payouts. Confirm the validity of a recipient’s bank account. Send money to a verified recipient’s bank account. Fetch details of a payout transaction. Check your Novac account balance before payouts. # Retrieve account balance Source: https://developer.novacpayment.com/api-reference/payouts/retrieve-balance get /api/v1/balance/{currency} # Retrieve a bank transaction Source: https://developer.novacpayment.com/api-reference/payouts/retrieve-bank-transaction get /api/v1/transfers/{reference} # Retrieve payout banks Source: https://developer.novacpayment.com/api-reference/payouts/retrieve-payout-banks get /api/v1/banks/{countryCode} # Verify a bank account Source: https://developer.novacpayment.com/api-reference/payouts/verify-bank-account post /api/v1/banks/account/verify # Initiate a partial refund Source: https://developer.novacpayment.com/api-reference/refunds/create-partial-refund post /api/v1/partial-refund # Initiate a full refund Source: https://developer.novacpayment.com/api-reference/refunds/create-refund post /api/v1/refund # Introduction Source: https://developer.novacpayment.com/api-reference/refunds/introduction Learn how to manage refunds with Novac. ## Overview Refunds let you return money to your customers, either fully or partially. With Novac, you can create refunds, track their status, and retrieve refund history to ensure transparency and smooth customer experiences. *** ## Quick Actions Initiate a full refund for a completed transaction. Refund a portion of a transaction amount.\ Useful for partial order cancellations or adjustments. Get details of a specific refund request. Fetch a list of all refunds initiated from your account. # Filter a list of refunds Source: https://developer.novacpayment.com/api-reference/refunds/retrieve-refund-lists get /api/v1/refund/{startDate}/{endDate} # Retrieve a single refund Source: https://developer.novacpayment.com/api-reference/refunds/retrieve-single-refund get /api/v1/refund/{reference} # Create Sub-settlement Accounts Source: https://developer.novacpayment.com/api-reference/split-payment/create-sub-settlement-account post /api/v1/split-payment # Retrieve Sub-settlement Accounts Source: https://developer.novacpayment.com/api-reference/split-payment/get-sub-settlement-accounts get /api/v1/split-payment # Introduction Source: https://developer.novacpayment.com/api-reference/split-payment/introduction Learn how to set up and manage split payments with Novac. ## Overview Split Payment lets you automatically divide a single transaction's settlement between your primary account and one or more sub-settlement accounts. Useful for marketplaces, platforms, and any business that needs to share revenue with vendors or partners without manual reconciliation. ## Quick Actions Register a new sub-settlement account and define how its share of a transaction is split (flat amount or percentage). Fetch your current split payment settings, including all configured sub-settlement accounts. Modify an existing sub-settlement account's split type, value, or account details. # Update a Sub-settlement Account Source: https://developer.novacpayment.com/api-reference/split-payment/update-sub-settlement-account put /api/v1/split-payment # Introduction Source: https://developer.novacpayment.com/api-reference/transaction/introduction Manage Transaction with Novac. ## Overview Verify that all payment collections are successful, abandon or rejected. Collections allow you to accept payments directly via cards. This section provides an API to verify and void transactions. *** ## Quick Actions Verify the status of a transaction. Verify a transaction by reference ID. Cancel or void a pending transaction. # Verify Transaction (by Payload) Source: https://developer.novacpayment.com/api-reference/transaction/transaction-verify post /api/v1/transaction/verify # Verify Transaction (by Ref) Source: https://developer.novacpayment.com/api-reference/transaction/transaction-verify-ref get /api/v1/transaction/{transactionRef}/verify # Void Transaction Source: https://developer.novacpayment.com/api-reference/transaction/void-transaction post /api/v1/void-transaction # Retrieve virtual account bank list Source: https://developer.novacpayment.com/api-reference/virtual-account/bank-list get /api/v1/virtual-accounts/bank-list?currency={currency} # Create a virtual account Source: https://developer.novacpayment.com/api-reference/virtual-account/create-virtual-account post /api/v1/virtual-account # Introduction Source: https://developer.novacpayment.com/api-reference/virtual-account/introduction Learn how to create and manage virtual accounts with Novac. ## Overview Virtual Accounts make it easy to collect payments and reconcile transactions. With Novac, you can create unique accounts for your customers, retrieve account details, and track payments securely without manual effort. *** ## Quick Actions Get the list of supported banks available for creating virtual accounts. Generate a new virtual account for your customer to receive payments seamlessly. Fetch virtual account details using a transaction or request reference. Retrieve account details directly using a virtual account number. # Get virtual account by reference Source: https://developer.novacpayment.com/api-reference/virtual-account/retrieve-virtual-account-by-account-number get /api/v1/virtual-account/{reference} # Get virtual account by account number Source: https://developer.novacpayment.com/api-reference/virtual-account/retrieve-virtual-account-by-reference get /api/v1/virtual-accounts/{accountNumber} # Direct Card Charge Source: https://developer.novacpayment.com/docs/accept-payment/accept-payment-with-direct-card-charge Server-to-server card charge API for fintechs who want to bypass Novac's checkout entirely and process card payments directly from their backend. ## Overview The Direct Card Charge API lets you process card payments entirely from your backend, no redirect to Novac's checkout page, no hosted UI. This is a server-to-server integration designed for fintechs and platforms that need full control over the payment experience. You must be **PCI DSS Level 1 certified** to use this API. If you are not PCI-compliant, use one of these alternatives instead: * [Hosted Checkout](/docs/accept-payment/accept-payment-with-payment-links) fully managed by Novac * [Custom Checkout for USSD and Bank Transfer](/docs/accept-payment/complete-payment/custom-checkout) partial control without handling card data *** ## Prerequisites * [Create a merchant account](/docs/getting-started/create-merchant-account) with KYC completed. * [Obtain your secret API keys](/docs/getting-started/obtain-api-keys). * Set your **Webhook URL** and **Redirect URL** on the dashboard. You can also pass a **Redirect URL** directly in the charge request. *** ## Two Ways to Initialize a Charge Depending on your security posture, you can integrate in one of two ways. Both achieve the same result, the difference is whether you encrypt card data before sending it. Encrypt card details on your server before sending. Recommended for teams that want an extra layer of security beyond HTTPS. Send card details over HTTPS without pre-encrypting. Suitable for compliant integrations on secure infrastructure. *** ### With Card Encryption Use this approach if you want to encrypt card data before transmitting it, even over HTTPS. Novac provides a utility to encrypt card details, you don't need to implement your own encryption algorithm. See [how to encrypt with Novac](/docs/api-basics/encryption) before proceeding. The `reference` you use to encrypt the card data **must be the same reference** passed when initiating the charge. Mismatched references will cause the request to fail. Amount to charge, in the smallest currency unit (e.g. kobo for NGN). ISO 4217 currency code, e.g. `NGN`, `USD`. Unique transaction reference, **at least 16 alphanumeric characters**. Must match the reference used to encrypt the card data. Customer's email address. Novac-encrypted card string. Must be `sale`. Controls 3DS authentication. Set to `true` to enforce 3DS, or `false` for No-Auth (2D) if enabled on your account. URL to redirect the customer to after payment. If omitted, Novac displays a default confirmation page. A JSON string of key-value pairs to associate with this transaction. ```bash theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/direct-card-charge \ --header 'Authorization: Bearer YOUR_SECRET_KEY' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "currency": "NGN", "reference": "TXN-REF-20240101-001", "email": "customer@example.com", "card": "NOVAC_ENCRYPTED_CARD_STRING", "transactionType": "sale", "enforceSecureAuth": true, "redirectUrl": "https://yoursite.com/payment/callback", "metaData": "" }' ``` **Why 16 characters for `reference`?** The minimum length is enforced for cryptographic integrity, it ensures the reference is sufficiently unique and safe to use as part of the card data encryption process. *** ### Without Card Encryption Use this approach if you prefer to send raw card data over HTTPS. This is acceptable for compliant integrations running on secure infrastructure. `cardData.pin` is only required if the currency is NGN. `transactionType` must still be `sale`. ```bash theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/card-charge \ --header 'Authorization: Bearer YOUR_SECRET_KEY' \ --header 'Content-Type: application/json' \ --data '{ "amount": 1000, "currency": "NGN", "reference": "TXN-REF-20240101-002", "email": "customer@example.com", "transactionType": "sale", "enforceSecureAuth": true, "redirectUrl": "https://yoursite.com/payment/callback", "cardData": { "number": "5399830000000008", "expiryMonth": "07", "expiryYear": "2026", "cvv": "289", "pin": "1234" } }' ``` *** ## Handling 3DS and No-Auth (2D) Responses ### 3DS Authentication When `enforceSecureAuth` is `true`, the charge triggers a 3DS challenge and returns a response like the one below. Redirect the customer to the `redirectUrl` in the response to complete the challenge. ```json Response theme={null} { "status": true, "message": "Proceed with 3DS authentication", "data": { "authMode": "3ds", "authAction": "redirect", "authEndpoint": "v1/threedschallenge", "authMessage": "Redirect to the redirect url ", "friendlyMessage": "Proceed with user 3DS2 authentication", "redirectUrl": "https://api.novacpayment.com/payer/auth/{reference}/initiate" } } ``` Once payment is complete, Novac redirects the customer back to the URL provided at transaction initiation. ### No-Auth (2D) Approved Directly If `enforceSecureAuth` is `false` and your account supports No-Auth processing, the charge may be approved without further customer interaction. ```json Response Approved (No-Auth) theme={null} { "status": true, "message": "Transaction Approved", "data": { "responseCode": "00", "responseDescription": "Transaction Approved" } } ``` A `status: true` on the charge response does **not** mean funds have been captured, it only means the charge was submitted successfully. You **must** call the [verification endpoint](/docs/accept-payment/manage-payment/verify-transaction) to confirm the final transaction status before giving value to the customer. The charge endpoint intentionally returns only `status` and `message`. All transaction details amount, card info, customer data and fees are returned by the verification endpoint. *** ## PIN Authentication Scenarios (NGN Cards Only) ### PIN Required If a PIN is required but wasn't included in the initial request, the API returns the response below. Add the `pin` field to the card data and resubmit to the same endpoint. ```json Response theme={null} { "status": false, "message": "Please enter your PIN to continue", "data": { "authMode": "PIN", "authAction": "verify", "authEndpoint": "v1/direct-card-charge", "authMessage": "PIN validation required, add customer 4-digit PIN to encrypted card data and resubmit", "fields": ["pin"] } } ``` ### PIN Not Supported If the card is not enrolled for PIN authentication: ```json Response theme={null} { "status": false, "message": "Card is not enrolled for PIN authorization", "data": { "authMode": "PIN", "authAction": "card_not_enrolled", "friendlyMessage": "Card is not enrolled for PIN authorization" } } ``` *** ## What’s Next? * **Using Webhooks:** Automatically receive payment status updates from Novac when a transaction is completed.\ [Learn how to verify a transaction via webhooks](/docs/api-basics/webhooks) * **Using the Transaction Reference:** Manually verify the payment using the `reference` used during the custom checkout session.\ [Learn how to verify a transaction using a callback reference](/api-reference/transaction/introduction) * **Recurring Payment:** Learn how to [save and charge customer's card](/docs/accept-payment/manage-payment/recurring-billing) for subscriptions based services. * **Request Refund:** Initiate a [full or partial](/docs/accept-payment/manage-payment/refund-transaction) refund. # Create a Payment Link Source: https://developer.novacpayment.com/docs/accept-payment/accept-payment-with-payment-links Learn how to create and use Payment Links when integrating with Novac. ## Overview Payment Links extend the functionality of Checkouts, offering a powerful and flexible way to receive payments from your customers. They support multiple payment methods and can be accessed from anywhere, on any device, ensuring a seamless payment experience for your customers. Merchants can use Novac Payment Links for a variety of purposes, including online sales on social media, service subscriptions, loan repayments, and even donations or fundraising campaigns. This is due to the reusability nature. You can create a payment link on Novac dashboard. When you create from your dashboard they are mostly reusable, this means that you can receive inflows from a single created payment link by sending to multiple customers. However, if you want to create a checkout payment that is uniquely tied to a specific payment link for example, for a one-time or customer-specific transaction, you should create it via the API. In this tutorial, we will explain step-by-step how you can create a payment link from the dashboard. ## Prerequisite To get started you must have complete all the following item on the list below: * [Create a merchant account](/docs/getting-started/create-merchant-account) - Ensure that you have created an account and completed KYC. * [Obtain API keys](/docs/getting-started/obtain-api-keys) - Required to authenticate with the Novac API. ## Payment Methods Your clients can choose to pay via : 1. Card Payment - Available in checkout payment. 2. Bank transfer - Available in checkout payment. 3. USSD payment - Available in checkout payment. 4. Opay - Available in checkout payment. 5. Palmpay - Available in checkout payment. *** ## Create a Reusable Payment Link via Dashboard Sign in to your [**Novac Dashboard**](https://app.novacpayment.com) using your account credentials. On the side menu, navigate to the **Payments** tab and click on **Payment Links**. Navigate to Payment Links on Novac Dashboard Click the **New Payment Link** button to create a new link. Create a new payment link on Novac Select the preferred payment link type that suits your business needs. Choose **Single Payment Link** or **Recurring Payment Link** and click **Proceed**. The **Recurring Payment Link** option can be used to collect inflows periodically. See [recurring payment link for NGN cards](/docs/accept-payment/manage-payment/ngn-recurring-billing) for more details. Select payment link type on Novac Fill in the required details for your new payment link in the form and click **Create Link** to complete the process. Fill single payment link form To allow payers to enter their own amount, simply leave the "Amount" field empty. This enables multiple people to pay any amount they choose through the link. Perfect for receiving donations or flexible payments. For a **recurring payment link**, there's an additional field that you can use to set payment frequency. Please note that this feature is only available for business accounts only. *** ## What's Next? Now that your payment link is ready, you can go beyond simply sharing the URL, you can use it programmatically to create checkout sessions that are uniquely tied to this link. This is useful when you need to: * Charge a specific customer a defined amount via the link. * Pre-fill customer details like name and email for a smoother experience. * Generate a one-time checkout URL that you can track individually. * [Create a checkout with a payment link reference](/docs/accept-payment/checkout/create-checkout-with-payment-link-reference) Learn how to tie a checkout payment to your payment link and redirect your customer to complete the payment. # Create Checkout for Mobile Money Payments Source: https://developer.novacpayment.com/docs/accept-payment/checkout/create-checkout-for-mobile-money-payment Learn how to collect GHS and KES mobile money payments using the Novac API. ## Overview Novac supports mobile money (MoMo) payment collection for Ghana cedis (GHS) and Kenya shillings (KES), allowing your customers to pay via MTN Ghana and Telecel Ghana for Ghana, or M-Pesa, Airtel Money, and T-Kash for Kenya mobile money wallets. Mobile money collection is currently available for GHS and KES transactions only. Ensure your checkout is created with `currency` set to `GHS` or `KES` before proceeding with this flow. The MoMo flow uses Novac's hosted checkout page. After creating a checkout, redirect your customer to the returned `paymentRedirectUrl` where they will select their MoMo provider and enter their phone number. Novac then sends a payment approval prompt to their mobile money app. Once approved, the customer confirms on the checkout page and the transaction is settled. ## Prerequisites Before initiating a MoMo checkout, you must have: * [Create a merchant account](/docs/getting-started/create-merchant-account) — Ensure you have an active account with KYC completed. * [Obtain API keys](/docs/getting-started/obtain-api-keys) — Required to authenticate all requests. *** ## Create MoMo Checkout Payment Create a checkout payment using either a [payment link reference](/docs/accept-payment/checkout/create-checkout-with-payment-link-reference) or a [transaction reference](/docs/accept-payment/checkout/create-checkout-with-transaction-reference). You must set `currency` to `GHS` or `KES` when creating the checkout. This ensures the hosted payment page presents Mobile Money as a payment option to your customer. When the payment has been created, you may redirect your customer to the hosted Novac checkout for them to complete the payment, or build a custom UI with the API that powers the MoMo checkout for a custom experience. *** ## Complete the Payment Redirect your customer to the `paymentRedirectUrl` returned when you initiated a MoMo checkout. On this page, the customer selects **Mobile Money** as their payment method, chooses their provider, and enters their phone number. Novac hosted checkout showing mobile money provider selection and phone number entry Once the customer clicks **Pay**, Novac sends a payment approval prompt to their mobile money app. You can also build a custom checkout experience that matches your brand using the API that powers the MoMo checkout page. [Learn more about custom checkout](/docs/accept-payment/complete-payment/custom-checkout#momo-custom-checkout-flow). *** ## Customer Approves the Payment After submitting their details, the checkout page transitions to a confirmation screen instructing the customer to open their MoMo app and approve the pending payment prompt. Novac checkout showing Complete Your Payment screen with I Have Made Payment button Once the customer has approved the payment in their MoMo app, they return to the checkout page and click **I Have Made Payment** to confirm. The transaction is then settled. *** ## What's Next? After initiating the MoMo payment, there are two ways to confirm the final transaction status: * **Webhooks**: Novac will send a webhook notification to your configured endpoint once the customer approves or declines the payment prompt. This is the recommended approach. See [Webhook Events](/docs/api-basics/webhooks) to learn how to set up and handle incoming events. * **Verify the transaction**: You can also poll the verify endpoint to check the transaction status. See [Verify a Transaction](/docs/accept-payment/manage-payment/verify-transaction). # Create Checkout with Payment Link Reference Source: https://developer.novacpayment.com/docs/accept-payment/checkout/create-checkout-with-payment-link-reference Learn how to create a checkout transaction using a payment link reference. ## Overview Payment links created on the Novac dashboard are reusable by default, you can share a single link with multiple customers and receive funds from each of them. This works well for general-purpose payment pages, but there are scenarios where you need more control. When you want to tie a checkout payment to a specific payment link, for example, to handle a one-time purchase, pre-fill customer details, or customize the checkout experience per transaction, you should initiate the checkout via the API instead. In this guide, you'll learn how to retrieve the payment URL `paymentLinkReference` from your dashboard and use it to create a checkout payment via the API. ## Prerequisite To get started you must have completed all the following item on the list below: * [Create a merchant account](/docs/getting-started/create-merchant-account) - Ensure that you have created an account and completed KYC. * [Obtain API keys](/docs/getting-started/obtain-api-keys) - Required to authenticate with the Novac API. * [Create a payment link](/docs/accept-payment/accept-payment-with-payment-links) - You need an existing payment link to reference when initiating the checkout. *** ## Create a Checkout Payment with Payment Link Reference Creating a checkout payment with payment link reference via API allows you to further customize the experience for your customer. Every single payment link created on the dashboard comes with a unique Payment Link Reference, also known as the `paymentURL`. You can also see this as initiating a transaction via a payment link reference, and it can be used for a one-time payment. ### Finding your Payment Link Reference You can find this reference by viewing the details of any payment link on your dashboard. Click on a single payment link from the list to view its details: View payment link reference on Novac Dashboard The `paymentURL` you use should correspond to a link that accepts **varying amounts**.\ This enables you to specify any amount dynamically via the API.\ However, if an amount was set when creating the link, that **exact amount** must be provided in the request object. ```bash expandable Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/paymentlink/initiate \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "paymentLinkReference": "oeXQckL", "amount": 123, "currency": "", "metaData": "", "redirectUrl": "", "allowedPaymentOptions":"", "checkoutCustomerData": { "email": "", "firstName": "", "lastName": "", "phoneNumber": "" }, "checkoutCustomizationData": { "logoUrl": "", "paymentDescription": "", "checkoutModalTitle": "" } }' ``` You can control which payment channels appear at checkout by passing `allowedPaymentOptions` in your request. Accepts a single value or multiple comma-separated values, e.g. `"CARD"` or `"CARD,PWBT,OPAY,USSD,PALMPAY,MOMO"`. [Learn more about setting payment preferences](/docs/getting-started/payment-preference) ```json expandable Response theme={null} { "status": true, "message": "Transaction initialized successfully", "data": { "transactionReference": "string", "amount": 100, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "string", "paymentRedirectUrl": "string" } } ``` This is a created checkout payment response; the `paymentRedirectUrl` is used to redirect your customer to where they will complete the payment. It's important to know that we expose the API that powers our checkout for a custom checkout experience. *** ## What's next? Now that you've created a checkout payment, here are a few directions to explore: * **Split payments**: Add a [split configuration](/docs/accept-payment/split-payment/setup-primary-settlement-account) to your request to automatically distribute incoming funds across multiple settlement accounts, either by flat amount or percentage. * **Complete the payment**: Route your customer to the [Novac prebuilt checkout](/docs/accept-payment/complete-payment/prebuilt-checkout) to complete the payment, or use the [custom checkout](/docs/accept-payment/complete-payment/custom-checkout) to build your own UI on top of our API. # Create Checkout with Transaction Reference Source: https://developer.novacpayment.com/docs/accept-payment/checkout/create-checkout-with-transaction-reference Learn how to initiate a checkout transaction with a unique reference. ## Overview Checkout payments are transactions initiated via the Novac API. They allow your customers to complete payments through our secure prebuilt checkout or your own custom interface.\ When you create a checkout payment, typically you should expect a `paymentRedirectUrl` in the response object that is returned. You you can open this redirect url on a new tab for your customers to complete the payment via a prebuilt Novac checkout. In this guide you will learn how to create a checkout payment with a unique transaction reference. We offer two ways to create a checkout payment. * Create a checkout payment with payment link reference * Create a checkout payment with a unique transaction reference When creating a checkout payment with payment link reference, the payment completed are usually tied to the payment link that was created on the dashboard and you can view the transactions completed by viewing the single transaction associated with the payment link on the dashboard. Please see how to [create a checkout payment with payment link reference](/docs/accept-payment/accept-payment-with-payment-links). The guide should help you get set up quickly. *** In this tutorial, we will explain step-by-step how you can create a checkout payment with a unique transaction reference. ## Prerequisite Before you begin, ensure that you’ve completed the following steps: * [Create a merchant account](/docs/getting-started/create-merchant-account): make sure your account is created and KYC is completed. * [Obtain your public API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls. * [Understand how to create a checkout payment with payment link reference](/docs/accept-payment/accept-payment-with-payment-links): helps you choose between a payment link reference and a transaction reference. * [Understand how to complete payments](/docs/accept-payment/checkout/create-checkout-with-transaction-reference#how-to-complete-payment): essential to know how to finalize payments after creation. * [Set up a primary settlement account on the dashboard](/docs/accept-payment/split-payment/setup-primary-settlement-account): this is needed if you want to use split payment when creating a checkout payment. ## Payment Methods Your clients can choose to pay via : 1. Card Payment 2. Bank transfer 3. USSD payment 4. OPAY 5. Palmpay *** ## Create a Checkout Payment with a Transaction Reference To create a checkout transaction: 1. Generate a **unique transaction reference** (minimum of 16 characters).\ This reference must be unique per transaction. 2. Make a [POST request]() to the `/api/v1/initiate` endpoint. The `currency` field accepts `USD`, `NGN`, or `EUR`. You can set your `redirectUrl` in the API request or from your dashboard under the **API Keys** section. If you don’t pass a `redirectUrl` in your request, Novac will use the default one you configured on your dashboard.\ If no redirect URL is found, you’ll be required to provide one explicitly. ```bash expandable Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/initiate \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "transactionReference": "", "amount": 123, "currency": "", "metaData": "", "redirectUrl": "", "allowedPaymentOptions":"", "checkoutCustomerData": { "email": "", "firstName": "", "lastName": "", "phoneNumber": "" }, "checkoutCustomizationData": { "logoUrl": "", "paymentDescription": "", "checkoutModalTitle": "" } }' ``` You can control which payment channels appear at checkout by passing `allowedPaymentOptions` in your request. Accepts a single value or multiple comma-separated values,e.g. `"CARD"` or `"CARD,PWBT,OPAY,USSD,PALMPAY,MOMO"`. [Learn more about setting payment preferences](/docs/getting-started/payment-preference) Once the checkout transaction is created successfully, Novac will return a response similar to the example below. You can redirect your customer to the `paymentRedirectUrl` to complete the payment using our prebuilt checkout, or use the `transactionReference` to handle a custom checkout experience. ```json expandable Response theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "1oWbJQQHLyQqqf1SwxjSpudeA01XX", "amount": 1000, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc_testpk_a0kuivx6lst100haeqo2eyoXXXXXXXeyyslr", "paymentRedirectUrl": "https://www.app.novacpayment.com/pay/payments?reference=1oWbJQQHLyQqqf1SwxjSpudeA01XX", "collectionPaymentOptions": "CARD,PWBT,USSD,NQR" } } ``` *** ## Create Checkout Payment with Split Payment After configuring your split settlement accounts, you can initiate a checkout transaction and control how the split should be applied. Split behavior during transaction initialization supports two modes: 1. **Use preconfigured split settings** (default account-level configuration): To Learn more on how to set up split accounts, [see here](docs/accept-payment/split-payment/manage-sub-settlement-accounts). 2. **Override split configuration per transaction** This endpoint uses your **Public Key** for production and sandbox environment. #### Use Preconfigured Split Settings (No Override) ```bash expandable Request theme={null} curl -X 'POST' \ 'https://api.novacpayment.com/api/v1/initiate' \ -H 'accept: */*' \ -H 'Authorization: Bearer nc_livepk_******' \ -H 'Content-Type: application/json' \ -d '{ "transactionReference": "13202602160000000000000001", "amount": 100, "currency": "NGN", "metaData": "", "redirectUrl": "", "allowedPaymentOptions": "", "checkoutCustomerData": { "email": "sayhitoaz@gmail.com", "firstName": "AZ", "lastName": "Oluwafemi", "phoneNumber": "" }, "checkoutCustomizationData": { "logoUrl": "", "paymentDescription": "", "checkoutModalTitle": "" }, "splitPaymentTransactionInfo": { "use_preconguration": true, "splitDetails": [ { "split_reference_code": "", "split_type": "", "split_value": 0 } ] } }' ``` ```json expandable response theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "13202602160000000000000001", "amount": 100, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc_livepk_b9jbze8pkcnxwlrhon896oax9nex0dx1x3j0", "paymentRedirectUrl": "https://checkout.novacpayment.com/pay/payments?reference=13202602160000000000000002", "collectionPaymentOptions": "CARD,PWBT,USSD,OPAY,PALMPAY" } } ``` *** #### Override Preconfigured Split If you need a different split logic for a specific transaction, you can override your preconfigure by setting `use_preconguration` to false. in this case you must provide new split information This override applies only to the current transaction. Your saved split configuration remains unchanged. ```bash expandable Request theme={null} curl -X 'POST' \ 'https://api.novacpayment.com/api/v1/initiate' \ -H 'accept: */*' \ -H 'Authorization: Bearer nc_livepk_******' \ -H 'Content-Type: application/json' \ -d '{ "transactionReference": "13202602160000000000000002", "amount": 100, "currency": "NGN", "metaData": "", "redirectUrl": "", "allowedPaymentOptions": "", "checkoutCustomerData": { "email": "sayhitoaz@gmail.com", "firstName": "AZ", "lastName": "Oluwafemi", "phoneNumber": "" }, "checkoutCustomizationData": { "logoUrl": "", "paymentDescription": "", "checkoutModalTitle": "" }, "splitPaymentTransactionInfo": { "use_preconguration": false, "splitDetails": [ { "split_reference_code": "31SPLIT0000130004498921", "split_type": "flat", "split_value": 200 }, { "split_reference_code": "31SPLIT0000140709310134", "split_type": "flat", "split_value": 200 } ] } }' ``` ```json expandable response theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "13202602160000000000000002", "amount": 100, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc_livepk_*************", "paymentRedirectUrl": "https://checkout.novacpayment.com/pay/payments?reference=13202602160000000000000002", "collectionPaymentOptions": "CARD,PWBT,USSD,OPAY,PALMPAY" } } ``` *** ## How to Complete Payments We recommend allowing your customers to complete their payments using Novac’s prebuilt checkout for the fastest and most reliable experience. If you prefer to offer a custom checkout experience that matches your brand, you can build your own UI to display available payment options (e.g., Card, USSD, Bank Transfer, NQR). Learn more in the following guides: * [Complete Payment with Prebuilt Checkout](/docs/accept-payment/complete-payment/prebuilt-checkout) * [Complete Payment with Custom Checkout](/docs/accept-payment/complete-payment/custom-checkout) # Overview Source: https://developer.novacpayment.com/docs/accept-payment/checkout/overview Learn how to create a Novac checkout payment using a payment URL and a unique transaction reference. Checkout payments are transactions initiated via the Novac API. They allow your customers to complete payments through Novac's secure prebuilt checkout or your own custom interface. Every Novac payment starts with a checkout session. Your server creates the session with the transaction details amount, currency, customer email, and a unique reference you generate. Novac returns a `paymentRedirectUrl` that the customer uses to complete payment. You can open this URL on a new tab for your customer to complete the payment via the prebuilt Novac checkout. The `transactionReference` you provide is the identifier that ties the entire payment lifecycle together: from session creation, through the customer's callback redirect, to server-side verification before you release value. We offer two ways to create a checkout payment Retrieve the payment Link Reference from your dashboard and use it to initiate a checkout via the API. Generate your own unique reference and pass it when creating a checkout. Best for tying payments directly to orders or records in your system. Novac offers support for GHS and KES inflows via mobile money payment. To get started, create a checkout payment with currency set to "KES" or "GHS" to present mobile money as a payment option," then redirect to the hosted page or build a custom MoMo UI to complete the payment. See [MoMo checkout payment to learn more.](/docs/accept-payment/checkout/create-momo-checkout-payment) # Custom Checkout Source: https://developer.novacpayment.com/docs/accept-payment/complete-payment/custom-checkout Learn how to complete payments with custom checkouts. ## Overview You may want your customers to complete a payment via a custom checkout tailored to your brand aesthitics and user experience. Custom checkout with Novac exposes the API that power our prebuilt checkout to merchant looking at creating an experience of thier own while we still handle the payment processing behind the scene. You only control the payment completion logic while we handle the payment processing. *** ## Prerequisite Before completing a payment via the prebuilt checkout, ensure that you have: * Created a checkout payment with a [transaction reference](/docs/accept-payment/checkout/create-checkout-with-transaction-reference) or [payment link reference](/docs/accept-payment/accept-payment-with-payment-links#create-a-checkout-payment-with-payment-link-reference), this provides the `paymentRedirectUrl` needed for redirection. * Set up your `redirectUrl` either on the dashboard or in the API request to ensure users are properly redirected after payment completion. *** ## Custom Checkout Flows After successfully creating a checkout payment, you can use the `transactionReference` return as part of the response object to start a custom checkout process. this requires that you have built a form in your frontend that shows the amount charged. We exposes an API that also allow you to fetch transaction fees, complete payment with card, ussd or bank transfer. After creating a checkout payment, you’ll receive a response that includes a `paymentRedirectUrl` field: ```json expandable created checkout payment response data theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "1oWbJQQHLyQqqf1SwxjSpudeA01nm", "amount": 1000, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc_testpk_a0kuivx6lst100haeqo2eyoxkcqdmmeyyr", "paymentRedirectUrl": "https://www.app.novacpayment.com/pay/payments?reference=1oWbJQQHLyQqqf1SwxjSpudeA01nm", "collectionPaymentOptions": "CARD,PWBT,USSD,NQR" } } ``` Lets build a simple payment completion logic using Javascript as our frontend, we will build a simple form using HTML, JS *** ### Redirect Customers to your Custom Payment UI On your custom checkout page, you will complete the payment with the `transactionReference` from the created checkout payment. Your customers have the option to use either USSD, card, Opay, Palmpay or transfer. Depending on what they select, you will call any of the APIs below to complete the payment. ```bash Card Payment theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/card-payment \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "cardNumber": "", "expiryMonth": "", "expiryYear": "", "cvv": "", "cardPin": "", "transactionReference": "" }' ``` ```bash Transfer Payment theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/bank-transfer \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "transactionReference": "", "paymentType": "", "cardBin": "" }' ``` ```bash USSD payment theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/ussd-payment \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "transactionReference": "", "bankCode": "" }' ``` #### Opay integration To complete payment with OPay integration, make a `POST` request and pass the transaction ref used when creating the checkout payment. Pass it as a query parameter. Redirect the customer to the `cashierUrl` page to complete the payment. ```bash Opay request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/opay-payment?transactionReference={tranref} \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```bash Opay response theme={null} { "status": true, "message": "Opay transaction initiated.", "data": { "cashierUrl": "https://express.opaycheckout.com/apiCashier/redirect/payment/checkoutHome?orderToken=TOKEN.7a99a4845931441b8607f32a255693eb", "reference": "NCPL20260610084349652371AFXR4P", "orderNo": "260610145662165989858", "status": "INITIAL", "amount": { "total": 30000, "currency": "NGN" }, "vat": { "total": 0, "currency": "NGN" } } } ``` #### Palmpay integration Make a `POST` request to this endpoint, ensure you pass the unique reference used during checkout creation. When the request is successful redirect customer to `checkoutUrl` to complete the payment. ```bash Palmpay request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/palmpay-payment?transactionReference={tranref} \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```bash Palmpay response theme={null} { "status": true, "message": "Palmpay transaction initiated.", "data": { "checkoutUrl": "https://checkout.palmpay.com/h5-checkout/?countryCode=NG&tntCode=PALMPAY&payToken=CA3FE89AA866FF827B66FBCABC3E05E1&orderNo=24260610084630346817&signKey=HAcl9Y-MSLtefSXGqOahZsTK1B5kfVeP7BnkneewFeg&signSession=24260610084630346817&appId=L250813121766924290401&productType=pay_wallet&businessProductType=pay_wallet&businessMode=three_mode&identityType=NEW&callable=%7B%22android%22%3A%22true%22%2C%22ios%22%3A%22true%22%7D", "currency": "NGN", "message": "", "orderAmount": 30000, "orderNo": "24260610084630346817", "orderStatus": 0, "payToken": "CA3FE89AA866FF827B66FBCABC3E05E1", "sdkSessionId": "24260610084630346817", "sdkSignKey": "HAcl9Y-MSLtefSXGqOahZsTK1B5kfVeP7BnkneewFeg" } } ``` You can explore more about the API that powers our checkout page below * [Complete card payments](/api-reference/custom-checkout/complete-card-payment) * [Complete bank transfer payment](/api-reference/custom-checkout/complete-bank-transfer) * [Complete USSD payments](/api-reference/custom-checkout/complete-ussd-payment) * [See List of supported USSD banks](/api-reference/custom-checkout/get-bank-ussd) *** ## MoMo Custom Checkout Flow To build a custom MoMo checkout experience, you must first create a payment intent by initiating a [MoMo checkout payment](/docs/accept-payment/checkout/create-checkout-for-mobile-money-payment). Use the `reference` returned from that step throughout this flow. ### Get Supported MoMo Providers Before collecting the customer's mobile money details, fetch the list of supported providers to populate your UI and retrieve the correct `bank_code` for the next step. ```bash theme={null} curl --request GET \ --url https://integrations.novacpayment.com/api/v1/mobilemoneybanks/GHS \ --header 'Authorization: ' \ --header 'Content-Type: application/json' ``` ```json Response theme={null} { "success": true, "message": "Bank list retrieved", "currency": "GHS", "data": [ { "bank_name": "MTN Ghana", "bank_code": "MTNGH" }, { "bank_name": "Telecel Ghana", "bank_code": "TCELGH" } ] } ``` Two MoMo providers are currently supported — MTN Ghana and Telecel Ghana. This list will be updated as additional providers are added. *** ### Create the MoMo Payment Once the account is validated, submit the payment request using the `reference` from your checkout, along with the customer's account details. Novac will trigger a payment approval prompt on the customer's mobile money app. ```bash theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/momo-payment \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "reference": "{reference}", "accountNumber": "{account_number}", "bankCode": "{bank_code}" }' ``` ```json Response theme={null} { "status": true, "message": "Momo transaction initiated." } ``` A successful response confirms the request was received. The transaction is not yet complete at this point, the customer must approve the payment prompt on their mobile money app to settle the transaction. Once approved, Novac will notify you of the payment status via webhooks. ## What’s Next? Learn how to verify transactions after payment is completed: * Using Webhooks: Automatically receive payment status updates from Novac when a transaction is completed.\ [Learn how to verify a transaction via webhooks](/docs/api-basics/webhooks) * Using the Callback URL: Manually verify the payment using the `reference` parameter sent to your callback URL.\ [Learn how to verify a transaction using a callback reference](/docs/accept-payment/manage-payment/verify-transaction) # Overview Source: https://developer.novacpayment.com/docs/accept-payment/complete-payment/overview Learn how Novac checkout works and choose the integration approach that fits your product. Novac Checkout is how you create a payment session for your customer. Your server creates a checkout with the transaction details, amount, currency, customer email, and reference. Novac returns a session that the customer completes by paying. There are two ways a merchant can choose to handle payment completion. Both methods use the same underlying API to create the session; the difference is in who renders the payment UI. Redirect customers to a Novac-hosted payment page. All payment methods are included out of the box, no UI work required. Build your own payment UI and call Novac APIs directly for each payment method. Full control over the look and feel. *** ## Choosing an Approach | | Prebuilt Checkout | Custom Checkout | | ------------------- | -------------------------- | ---------------------- | | **UI ownership** | Novac-hosted | You build it | | **Setup effort** | Minimal | Higher | | **Payment methods** | All included automatically | Integrated per channel | | **Customisation** | Limited | Full control | *** ## Supported Payment Methods Both checkout approaches support the same set of payment channels. You can control which ones appear using the `allowedPaymentOptions` field on the checkout request. | Code | Channel | | --------- | --------------------------------------------- | | `CARD` | Debit / Credit Card (Visa, Mastercard, Verve) | | `PWBT` | Pay With Bank Transfer | | `USSD` | USSD dial-to-pay | | `OPAY` | OPay Wallet | | `PALMPAY` | PalmPay Wallet | | `MOMO` | MTN / Telecel Mobile Money | You can restrict which channels appear at checkout by passing `allowedPaymentOptions` in your request e.g. `"CARD,PWBT"`. [Learn more about payment preferences →](/docs/getting-started/payment-preference) # Prebuilt Novac Checkout Source: https://developer.novacpayment.com/docs/accept-payment/complete-payment/prebuilt-checkout Learn how to complete payments securely via Novac’s hosted prebuilt checkout. ## Overview Novac provides a prebuilt hosted checkout that allows your customers to complete payments securely and seamlessly.\ We recommend this method because it abstracts away all the complexities of handling payment flows, allowing you to focus solely on initiating and tracking transactions. Once you successfully create a checkout payment using the API, the response will contain a `paymentRedirectUrl`. You can simply redirect your customer to this URL to complete the payment via the prebuilt checkout interface. The prebuilt checkout automatically supports all available payment options — such as Cards, Pay with Bank Transfer and USSD. without requiring you to build additional payment logic. *** ## Prerequisite Before completing a payment via the prebuilt checkout, ensure that you have: * Created a checkout payment with a [transaction reference](/docs/accept-payment/checkout/create-checkout-with-transaction-reference) or [payment link reference](/docs/accept-payment/accept-payment-with-payment-links#create-a-checkout-payment-with-payment-link-reference) — this provides the `paymentRedirectUrl` needed for redirection. * Set up your `redirectUrl` either on the dashboard or in the API request to ensure users are properly redirected after payment completion. *** ## Complete a Payment After creating a checkout payment, you’ll receive a response that includes a `paymentRedirectUrl` field: ```json expandable created checkout payment response data theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "1oWbJQQHLyQqqf1SwxjSpudeA01nm", "amount": 1000, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc_testpk_a0kuivx6lst100haeqo2eyoxkcqdmmeyyr", "paymentRedirectUrl": "https://www.app.novacpayment.com/pay/payments?reference=1oWbJQQHLyQqqf1SwxjSpudeA01nm", "collectionPaymentOptions": "CARD,PWBT,USSD,NQR" } } ``` To complete the payment, simply redirect your customer to the `paymentRedirectUrl`. This URL opens Novac’s prebuilt checkout, where customers can choose a preferred payment methods. You can open the `paymentRedirectUrl` in a new tab. The prebuilt checkout handles all authentication, processing automatically. Pay with Novac prebuilt checkout *** ## What’s Next? Learn how to verify transactions after payment is completed: * Using Webhooks: Automatically receive payment status updates from Novac when a transaction is completed.\ [Learn how to verify a transaction via webhooks](/docs/api-basics/webhooks) * Using the Callback URL: Manually verify the payment using the `reference` parameter sent to your callback URL. [Learn how to verify a transaction using a callback reference](/docs/accept-payment/manage-payment/verify-transaction) # Recurring Payment (NGN Cards) Source: https://developer.novacpayment.com/docs/accept-payment/manage-payment/ngn-recurring-billing Learn how to charge customer's saved NGN card for recurring payments. ## Overview If your customer pays with an **NGN card**, tokenization isn't available, you'll instead use the **Payment Link Recurring** approach, where the customer is charged through a recurring payment link created on the Novac dashboard, with the amount and frequency configured on the link itself. Payment Link Recurring currently supports **NGN transactions only**. Support for USD and other currencies will be added in a future release. *** ## Prerequisites Before creating a recurring payment link * [Create a merchant account](/docs/getting-started/create-merchant-account) — Ensure you have an active account with KYC completed. * Contact support to enable recurring payment link, this feature is enabled based on requests. *** ## To create a recurring payments, follow the steps below. A merchant creates a recurring payment link on the **Novac dashboard**, where the **amount** and charge frequency are configured Novac hosted checkout showing mobile money provider selection and phone number entry Frequency is not set through the API. It's configured when the payment link is created on the Novac dashboard. The `initiate` request below only needs the `paymentLinkReference`. The customer completes an initial checkout using that link **paymentURL**. This is what will be passed as `paymentLinkReference`. [See finding your payment link reference to learn more.](/docs/accept-payment/checkout/create-checkout-with-payment-link-reference#finding-your-payment-link-reference) Novac automatically charges the customer's card again at each interval defined by the frequency set on the link. No additional action required from the developer after the first charge. *** ### Initiate a Recurring Payment Initiates a recurring payment using a recurring payment link reference. ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/recurring/initiate \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "paymentLinkReference": "string", "amount": 100, "metaData": "{\"name\":\"John\"}", "allowedPaymentOptions": "", "redirectUrl": "http://test.com", "checkoutCustomerData"*: { "email": "testingnovac@gmail.com", "firstName": "John", "lastName": "Doe", "phoneNumber": "0908637****" }, "checkoutCustomizationData": { "logoUrl": "", "paymentDescription": "", "checkoutModalTitle": "" } }' ``` ```json title="Response" theme={null} { "status": true, "message": "Transaction Initialized successfully", "data": { "transactionReference": "NVSUB2026080710....", "amount": 10.00, "statusCode": "01", "statusMessage": "Transaction initiated successfully", "publicKey": "nc............", "paymentRedirectUrl": "https://checkout.novacpayment.com/pay/recurring?reference=NVS...", "collectionPaymentOptions": "CARD" } } ``` *** ### Fetch Recurring Payment Details Fetches the details of a recurring payment using its transaction reference. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/recurring/{reference} \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json title="Response" theme={null} { "status": true, "message": "Transaction retrieved successfully", "data": { "imageUrl": "string", "title": "string", "description": "string", "customerEmail": "string", "currency": "NGN", "firstName": "string", "lastName": "string", "amount": 10.00, "phoneNumber": "string", "metadata": "{\"string\": \"string\"}", "domain": "live", "status": "active", "transactionReference": "string", "statusCode": "00", "statusMessage": "Transaction retrieved successfully", "publicKey": "string" } } ``` *** ### Make the First Card Charge Processes the first charge for the recurring payment. Subsequent charges happen automatically based on the frequency configured on the payment link, no further calls to this endpoint are needed for later charges. All fields are required when sending a `POST` request to `api/v1/recurring/card-payment` endpoint ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/recurring/card-payment \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "cardNumber": "string", "expiryMonth": "01", "expiryYear": "30", "cvv": "123", "cardPin": "1234", "transactionReference": "string" }' ``` ```json title="Success Response" theme={null} { "status": true, "message": "Card payment processed successfully", "data": { "authMode": "no-auth", "authAction": "none", "authEndpoint": "none", "authMessage": "Transaction Completed", "friendlyMessage": "Card payment processed successfully", "redirectUrl": "" } } ``` *** ### Verify Charge & Subscription Status Validates the status of a charge and the underlying subscription. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/recurring/{reference}/verify \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json title="Success Response" theme={null} { "status": true, "message": "Recurring transaction details retrieved successfully", "data": { "subscriptionStatus": "active", "status": "successful", "reference": "string", "currency": "NGN", "amount": 10.00, "chargedAmount": 10.00, "transactionFee": 0.15, "gatewayResponseCode": "00", "gatewayResponseMessage": "successful", "domain": "live", "channel": "card", "requestIp": "::1", "transactionType": "transaction", "transactionChannel": "card", "redirectUrl": "http://test.com?reference=string&status=successful", "checkoutMetadata": "{\"name\": \"Test\"}", "paidAt": "2026-08-07T09:27:17", "startDate": "2026-08-07T10:25:32", "endDate": "2036-08-07T10:25:32", "nextPaymentDate": "2026-08-08T10:25:32", "card": { "first6Digits": "123456", "last4Digits": "1234", "issuer": "STERLING BANK PLC (NIGERIA)", "country": "123", "type": "Verve", "token": "" }, "customer": { "id": 1, "customerCode": "string", "email": "string", "name": "string" } } } ``` **Subscription status values** | Status | Meaning | | ----------- | --------------------------------------------------------------------------------- | | `active` | Subscription is active; the next charge will happen automatically at the due date | | `paused` | Subscription is paused; no charge will occur until reactivated | | `failed` | Charge failed | | `pending` | Charge is pending | | `cancelled` | Subscription is cancelled and cannot be reactivated | | `expired` | Subscription has expired | *** ### Update Subscription Status Updates the status of a subscription, the status field accept three different type of status flag, `pause`, `reactivate`, or `cancel`. A `paused` subscription can be reactivated by setting its status back to `active`. Once a subscription is `cancelled`, it **cannot** be reactivated. ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/recurring/updatestatus \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "reference": "string", "status": "active" }' ``` ```json title="Success Response" theme={null} { "status": true, "message": "Subscription status updated successfully" } ``` ## What’s Next? * **Using Webhooks:** Automatically receive payment status updates from Novac when a transaction is completed.\ [Learn how to verify a transaction via webhooks](/docs/api-basics/webhooks) * **Using the Callback URL:** Manually verify the payment using the `reference` parameter sent to your callback URL.\ [Learn how to verify a transaction using a callback reference](/docs/accept-payment/manage-payment/verify-transaction) * **Request Refund:** Initiate a [full or partial](/docs/accept-payment/manage-payment/refund-transaction) refund. # Overview Source: https://developer.novacpayment.com/docs/accept-payment/manage-payment/overview Learn how to manage payments on Novac with recurring billing, card tokenisation, refunds, and transaction verification. # Manage Payments Once you are set up to accept payments, Novac gives you the tools to handle everything that happens after the initial charge, saving cards for repeat billing, verifying transactions before releasing value, and reversing payments when needed. This section covers four core capabilities Charge customers automatically on a schedule suitable for NGN cards only. Tokenize a customer's card on first payment and reuse it for future charges without asking them to re-enter details. Reverse a completed transaction in full or partially via the Refund API. Confirm payment status server-side from your callback URL before releasing value to the customer. *** ## Recurring Billing Novac supports two approaches to recurring payments. The right one depends on the currency your customer pays with. For customers paying with a **dollar (USD) card**, Novac's card tokenisation works as expected. A token is captured on the customer's first payment and reused to charge that card again automatically, no re-entry of card details required. This is ideal for subscription products, memberships, and installment billing where the customer pays in USD. For customers paying with an **NGN card**, tokenisation is not available. Instead, use the **Payment Link Recurring** approach. A recurring payment link created on the Novac dashboard with the amount and frequency configured directly on the link. Payment Link Recurring currently supports **NGN transactions only**. Support for USD and other currencies will be added in a future release. # Refund a Transaction Source: https://developer.novacpayment.com/docs/accept-payment/manage-payment/refund-transaction Learn how to use the Refund API to process full or partial refunds seamlessly. ## Overview The refund API allows you to reverse transactions in part or in full, providing flexibility and control when handling customer requests, errors, or operational reversals. ## How It Works When a transaction is successfully completed, you can initiate a refund by making a request to the refund API. To process the refund efficiently, follow these steps: Include your Secret Key in the `Authorization` header to securely authenticate the refund request. Use the unique `reference` associated with the transaction you want to refund. You may include additional context for the refund using either the `customer_note` or `merchant_note` field. * **Full Refund**: Refunds the entire transaction amount. * **Partial Refund**: Refunds a portion of the total amount, useful when customers return only part of an order or when a service is partially fulfilled. ## Partial Refunds Explained A partial refund allows you to return only a portion of the original payment instead of the full amount. This is ideal for scenarios like: * A customer cancels one item in a multi-item order. * A service was only partially delivered. * You want to retain a processing or cancellation fee. ## Refunds ### Initiate a Refund ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/direct-card-charge \ --header 'Authorization: Bearer YOUR_SECRET_KEY' \ --header 'Content-Type: application/json' \ --data '{ "reference": "TXN-REF-20240101-001", "amount": "1000", "customer_note": "", "merchant_note": "" }' ``` Its important to note that amount cannot be greater than the original transaction amount. | Parameter | Type | Required | Description | | --------------- | ------ | -------- | ----------------------------------------------------------------------------------------------- | | `reference` | string | Yes | Original transaction reference to refund. | | `amount` | string | Yes | Amount to refund. Cannot exceed the original transaction amount. Partial refunds are supported. | | `customer_note` | string | No | Reason shown to the customer. | | `merchant_note` | string | No | Internal note for your records. | ```json Refund Response theme={null} { "status": true, "message": "Refund submitted and in progress", "data": { "id": 19410, "refundReference": "BR85288NQFBGU72BHWSQ", "amount": "1000", "currency": "NGN", "domain": "live", "initiatedBy": "self", "channel": "API", "merchantNote": "Customer requested refund", "customerNote": "Refund for order ORD-123", "status": "pending", "createdAt": "2024-03-14T12:04:05.0000000" } } ``` ### Check Refund Status ```http theme={null} GET https://api.novacpayment.com/api/v1/refund/{refundReference} ``` ```json Response theme={null} { "Status":true, "Message":"Refund submitted and in progress ", "Data":{ "Id":19410, "RefundReference":"BX5X88NXXXGU72BHWSQ", "Amount":"20.8", "Currency":"USD", "Domain":"live", "InitiatedBy":"self", "Channel":"API", "MerchantNote":" refund for transaction M0386-A0650-a12hCnGI", "CustomerNote":" refund for transaction M0386-A0650-a12hCnGI", "Status":"pending", "CreatedAt":"2024-03-14T12:04:05.0000000" } } ``` Use the `refundReference` returned when the refund was initiated, not the original transaction reference. ## What Next ? * [Initiate a full refund](/api-reference/refunds/create-refund) * [Initiate a partial refund](/api-reference/refunds/create-partial-refund) # Recurring Payment (USD Cards) Source: https://developer.novacpayment.com/docs/accept-payment/manage-payment/usd-recurring-billing Learn how to charge customer's USD card for recurring payments. ## Overview Novac allows you to securely save a customer’s card for future transactions, enabling a smooth and reliable experience for recurring or repeat payments. This feature is especially useful for businesses offering subscriptions, memberships, or installment-based billing, as it eliminates the need for customers to re-enter their card details each time. Tokenization only works for dollar cards, use the recurring payment link methods for ngn card subscriptions. ### How Customer Card Tokenization Works When you [verify a transaction](/api-reference/checkout/verify-transaction) using its reference, Novac returns a transaction details that includes the customer’s card information.\ Within this customer’s card object, you’ll find a `token` field. This token serves as a secure representation of the customer’s card, allowing you to charge the card for future payments. ```json title="Sample Transaction Response" theme={null} { "status": true, "message": "Transaction details retrieved successfully", "data": { // transaction information "card": { "first6Digits": "", "last4Digits": "", "issuer": "", "country": "", "type": "", "token": "" }, "customer": { // customer information }, "transferDetail": { // transfer information if payment is transfer } } } ``` In the example above, the `token` field represents the customer’s securely stored card reference. This token is what you’ll use to charge the customer again in the future without requesting their card details. Ensure that the actual card details are never stored on your servers, only secure, tokenized references. *** ### Charge a Customer's Saved Card To charge a customer’s saved card, make a [POST request](api-reference/collections/tokenized-card-charge) to the `/api/v1/tokenized-card-charge endpoint`. This request uses the previously returned token to process the payment securely. Ensure that the email value in the request object matches the one used when the checkout payment was created. ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/tokenized-card-charge \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "token": "", "currency": "", "amount": "123", "email": "", "firstName": "", "lastName": "", "reference": "" }' ``` ## What’s Next? * **Using Webhooks:** Automatically receive payment status updates from Novac when a transaction is completed.\ [Learn how to verify a transaction via webhooks](/docs/api-basics/webhooks) * **Using the Callback URL:** Manually verify the payment using the `reference` parameter sent to your callback URL.\ [Learn how to verify a transaction using a callback reference](/docs/accept-payment/manage-payment/verify-transaction) * **Request Refund:** Initiate a [full or partial](/docs/accept-payment/manage-payment/refund-transaction) refund. # Verify a Transaction Source: https://developer.novacpayment.com/docs/accept-payment/manage-payment/verify-transaction Learn how to verify a transaction with reference attached to its callbackURl. ## Overview When a customer completes a payment on Novac’s checkout, they are redirected to the `callbackURL` you provided during checkout initialization.\ Novac automatically appends query parameters such as the transaction reference and status to this URL. You can then use this reference to verify the transaction directly from your server before confirming payment or giving value to the customer. This approach ensures you are validating each transaction against Novac’s API response, not relying solely on the status parameter in the callback. *** ## Handling Callback URL After Payment Completion When payment is completed, We redirects the user to your callback URL as shown below: ```http theme={null} GET {your-callback-url}?reference=&status= ``` To verify a transaction, make a [GET request](api-reference/checkout/verify-transaction) to `api/v1/checkout/{transactionRef}/verify` by passing the transaction reference as a path parameter. It's important that you don’t rely on the status alone via callbackURL, Always verify a transaction before marking it as complete. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/checkout/{transactionRef}/verify \ --header 'Authorization: ' ``` ```bash expandable Response theme={null} { "status": true, "message": "Transaction details retrieved successfully", "data": { "status": "pending | successful | failed", "id": 0, "transactionReference": "string", "amount": 0, "chargedAmount": 0, "currency": "NGN", "transactionFee": 0, "gatewayResponseCode": "00", "gatewayResponseMessage": "string", "domain": "string", "channel": "string", "requestIp": "string", "paymentDescriptor": "NOVAC", "transactionType": "", "redirectUrl": "", "card": { "first6Digits": "string", "last4Digits": "string", "issuer": "", "country": "string", "type": "string" }, "customer": { "id": 0, "customerCode": "string", "email": "string", "name": "string" }, "transferDetail": { "bankCode": "string", "bankName": "string", "accountNumber": "string", "sessionId": "string", "creditAccountName": "string", "originatorName": "string", "originatorAccountNumber": "string" } } } ``` You can also define a server-side route, for example `/payment/callback` that reads these query parameters, extracts the transaction reference, and calls Novac’s Verify Transaction API to confirm the actual payment status. Below are examples in multiple languages showing how to handle and verify the callback. ```JavaScript NodeJs theme={null} import express from "express"; import axios from "axios"; const app = express(); app.get("/payment/callback", async (req, res) => { const { reference, status } = req.query; try { const response = await axios.get( `https://api.novacpayment.com/api/v1/checkout/${reference}/verify`, { headers: { Authorization: `Bearer ${process.env.NOVAC_API_KEY}`, }, } ); const verifiedTransaction = response.data; console.log("Verified Transaction:", verifiedTransaction); res.send("Payment verified successfully!"); } catch (error) { console.error("Verification failed:", error.message); res.status(500).send("Verification failed."); } }); app.listen(3000, () => console.log("Server listening on http://localhost:3000") ); ``` ```php PHP theme={null} "; if ($reference) { $secretKey = getenv("NOVAC_API_KEY"); $url = "https://api.novacpayment.com/api/v1/checkout/{$reference}/verify"; $ch = curl_init($url); curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); curl_setopt($ch, CURLOPT_HTTPHEADER, [ "Authorization: Bearer $secretKey" ]); $response = curl_exec($ch); curl_close($ch); if ($response) { echo "Verified Transaction: " . $response; } else { echo "Verification failed."; } } ``` ```go Golang theme={null} package main import ( "fmt" "io/ioutil" "net/http" "os" ) func callbackHandler(w http.ResponseWriter, r *http.Request) { reference := r.URL.Query().Get("reference") status := r.URL.Query().Get("status") fmt.Printf("Payment completed. Reference=%s Status=%s\n", reference, status) secretKey := os.Getenv("NOVAC_API_KEY") url := fmt.Sprintf("https://api.novacpayment.com/api/v1/checkout/%s/verify", reference) req, _ := http.NewRequest("GET", url, nil) req.Header.Set("Authorization", "Bearer "+secretKey) client := &http.Client{} resp, err := client.Do(req) if err != nil { fmt.Println("Verification failed:", err) w.WriteHeader(http.StatusInternalServerError) return } defer resp.Body.Close() body, _ := ioutil.ReadAll(resp.Body) fmt.Println("Verified Transaction:", string(body)) w.Write([]byte("Payment verified successfully!")) } func main() { http.HandleFunc("/payment/callback", callbackHandler) fmt.Println("Server listening on :3000") http.ListenAndServe(":3000", nil) } ``` ```py python theme={null} from flask import Flask, request import requests import os app = Flask(__name__) @app.route("/payment/callback", methods=["GET"]) def payment_callback(): reference = request.args.get("reference") status = request.args.get("status") print(f"Payment completed. Reference={reference}, Status={status}") try: url = f"https://api.novacpayment.com/api/v1/checkout/{reference}/verify" headers = {"Authorization": f"Bearer {os.getenv('NOVAC_API_KEY')}"} response = requests.get(url, headers=headers) print("Verified Transaction:", response.json()) return "Payment verified successfully!" except Exception as e: print("Verification failed:", str(e)) return "Verification failed.", 500 if __name__ == "__main__": app.run(port=3000, debug=True) ``` ## What’s Next? * **Request Refund:** Initiate a [full or partial](/docs/accept-payment/manage-payment/refund-transaction) refund. # Manage Sub Settlement Accounts Source: https://developer.novacpayment.com/docs/accept-payment/split-payment/manage-sub-settlement-accounts Learn how to setup and manage sub settlement account. ## Overview Split Payment allows you to automatically distribute funds from a single transaction into multiple bank accounts called sub-settlement accounts using Novac. Instead of receiving the full transaction amount into one account and transferring funds manually, Novac handles the split and settlement automatically based on your configured rules. Instead of receiving the full amount in one account and manually transferring funds, Novac automatically settles the predefined split amounts or percentages at the point of payment. All split configuration requests must be made server-to-server using your **Secret Key**. ## Prerequisite Before you begin, ensure that you’ve completed the following steps: * [Create a merchant account](/docs/getting-started/create-merchant-account): make sure your account is created and KYC is completed. * [Obtain your secret API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls. * [Set up a settlement account](/docs/accept-payment/split-payment/setup-primary-settlement-account) ## Understand Split Types A clear split structure: * **Flat** A fixed amount is assigned to a sub-settlement account. For example, if you set a flat value of ₦1,000, that account will always receive ₦1,000 from every transaction, and the remaining balance will be settled into your primary account. * **Percent** A percentage of the total transaction amount is assigned to a sub-settlement account. For example, if you set 50%, the account will receive half of the total payment, while the remaining percentage is settled into your primary account. `split_type` can be either **flat** or **percent**. *** ## Create a Sub-settlement Account Use this endpoint to define how payments should be split going forward. This creates one or multiple sub-settlement accounts in a single request. We recommend using the [GET payout banks](/api-reference/payouts/retrieve-payout-banks) API to retrieve the list of supported bank codes before creating or updating split settlement accounts. This ensures that the `bank_code` provided is valid and prevents validation errors. ```bash expandable Request theme={null} curl -X 'POST' \ 'https://api.novacpayment.com/api/v1/split-payment' \ -H 'accept: */*' \ -H 'Authorization: Bearer nc_livesk_*******************' \ -H 'Content-Type: application/json' \ -d '[ { "split_name": "vendor_payment", "bank_code": "000013", "account_number": "0004498921", "split_type": "flat", "split_value": 200 }, { "split_name": "it_charges", "bank_code": "000013", "account_number": "0004498938", "split_type": "flat", "split_value": 150 } ]' ``` When you send a request via this API, each account is validated, after which Novac will generate a unique `split_payment_reference`. This reference will be used for future transactions. ```json expandable Response theme={null} { "status": true, "message": "Split Settings saved successfully", "data": [ { "split_type": "flat", "split_payment_reference": "31VENDOR_PAYMENTSPLIT0000130004498921", "processing_message": "Account validated and added to split record successfully", "split_name": "vendor_payment", "bank_code": "000013", "account_number": "0004498921", "split_value": 200 }, { "split_type": "flat", "split_payment_reference": "31IT_CHARGESSPLIT0000130004498938", "processing_message": "Account validated and added to split record successfully", "split_name": "it_charges", "bank_code": "000013", "account_number": "0004498938", "split_value": 150 }, { "split_type": "flat", "split_payment_reference": "31PRIMARY_ACCOUNTSPLIT0000140709310134", "processing_message": "Account validated and added to split record successfully", "split_name": "primary_account", "bank_code": "000014", "account_number": "0709310134", "split_value": 0 } ] } ``` Each object in the data array represent a split object. you can choose to update any of these records in the future, to do this you must store the reference value `split_payment_reference` ## Get Sub-settlement Accounts You can get all split account record tied to your parent settlement account for auditing purposes. Send a `GET request` to this endpoint below. ```bash Request theme={null} curl -X 'GET' \ 'https://api.novacpayment.com/api/v1/split-payment' \ -H 'accept: */*' \ -H 'Authorization: Bearer nc_livesk_************' ``` ```json expandable Response theme={null} { "status": true, "message": "Split Settings retrieved successfully", "data": [ { "split_type": "flat", "split_payment_reference": "31VENDOR_PAYMENTSPLIT0000130004498921", "processing_message": "Account validated and added to split record successfully", "split_name": "vendor_payment", "bank_code": "000013", "account_number": "0004498921", "split_value": 200 }, { "split_type": "flat", "split_payment_reference": "31IT_CHARGESSPLIT0000130004498938", "processing_message": "Account validated and added to split record successfully", "split_name": "it_charges", "bank_code": "000013", "account_number": "0004498938", "split_value": 150 }, { "split_type": "flat", "split_payment_reference": "31PRIMARY_ACCOUNTSPLIT0000140709310134", "processing_message": "Account validated and added to split record successfully", "split_name": "primary_account", "bank_code": "000014", "account_number": "0709310134", "split_value": 0 } ] } ``` This response includes all active split records with associated bank details, split type and values. If no split has been configured, the response will return an empty list. ## Update a Sub-settlement Account Use this endpoint to modify an existing split rule. This will help if bank account number needs correction or vendor payout amount change. ```bash expandable Request theme={null} curl -X 'PUT' \ 'https://api.novacpayment.com/api/v1/split-payment' \ -H 'accept: */*' \ -H 'Authorization: Bearer nc_livesk_***************' \ -H 'Content-Type: application/json' \ -d '{ "split_reference_code": "31VENDOR_PAYMENTSPLIT0000130004498921", "bank_code": "000013", "account_number": "0004498921", "split_type": "flat", "split_value": 500 }' ``` ```json expandable Response theme={null} { "status": true, "message": "The split information has been updated successfully for reference 31VENDOR_PAYMENTSPLIT0000130004498921", "data": { "split_type": "flat", "split_payment_reference": "31VENDOR_PAYMENTSPLIT0000130004498921", "processing_message": "record updated successfully", "split_name": "vendor_payment", "bank_code": "000013", "account_number": "0004498921", "split_value": 500 } } ``` ## What Happens Next? Once your sub-settlement account is configured with pre split rule: * Initiate transactions using split configuration via [create checkout payment](/docs/accept-payment/checkout/create-checkout-with-transaction-reference#create-checkout-payment-with-split-payment). * Automatically distribute funds upon successful payment. # Overview Source: https://developer.novacpayment.com/docs/accept-payment/split-payment/overview Learn how to automatically distribute funds from a single transaction into multiple bank accounts using Novac Split Payment. Novac automates fund distribution by letting you configure how incoming payments are allocated across multiple accounts. To get started, you need to understand two key concepts: the primary settlement account and sub-settlement accounts, and how they work together. ## Primary Settlement Account The primary settlement account is the main bank account linked to your Novac merchant profile. It is the default destination for all incoming payments and acts as the parent account to which all sub-settlement accounts are attached. After any configured splits are distributed, any remaining balance from a transaction stays in this account. It must be set up on the Novac dashboard before you can configure split payments via the API. ## Sub-settlement Account A sub-settlement account is a secondary bank account you configure to automatically receive a portion of each incoming payment. You define how much each sub-settlement account receives, either as a flat fixed amount (e.g. ₦2,000 per transaction) or as a percentage of the total transaction amount (e.g. 15%). Multiple sub-settlement accounts can be linked to a single primary settlement account, and Novac distributes funds to each of them automatically at the point of payment. All split configuration requests must be made server-to-server using your **Secret Key**. *** ## When to Use Split Payment Split Payment is useful across a range of business models where a single incoming payment needs to be distributed to more than one party: Automatically route vendor earnings and platform fees to separate accounts at the point of payment. Distribute revenue between a franchisor and individual franchise locations without manual transfers. Split incoming payments between business partners or affiliates based on predefined percentages. Route portions of each transaction to internal cost centres — e.g. IT charges or service fees. # Setup Primary Settlement Account Source: https://developer.novacpayment.com/docs/accept-payment/split-payment/setup-primary-settlement-account Learn how to setup your settlement account. ## Overview In Novac, every split payment setup starts with configuring a Primary Settlement Account. This account serves as: * The default destination for all incoming payments * The fallback account for any remaining balance after split distribution * The parent account to which all sub-settlement (split) accounts are linked Before you can create and manage split payments via API, your primary settlement account must be configured on the dashboard. ## Prerequisite Before you begin, ensure that you’ve completed the following steps: * [Create a merchant account](/docs/getting-started/create-merchant-account): make sure your account is created and KYC is completed. * [Set up a settlement account](https://www.app.novacpayment.com/login) It's important to add bank details during the KYC process. This can be used as your default settlement bank when configuring split payment. *** ## Understanding Settlement Options Split payment in Novac is built on a parent–child structure that ensures funds are distributed reliably and automatically. At the core is the Primary Settlement Account, which is configured via the dashboard and acts as the main destination for all payments. This account receives the full payment when no split is applied, and also collects any remaining balance after split distribution. Attached to this are Sub-Settlement Accounts, which are created via API and are assigned specific portions of each transaction based on your split configuration (either flat or percentage). These sub-accounts cannot exist independently, they are always tied to a primary account. ## Transaction Flow When a transaction occurs, the customer completes payment as usual. Once the payment is successful, Novac automatically applies the defined split rules: each sub-settlement account receives its allocated share, while the remaining balance is routed to the primary settlement account. Finally, funds are settled according to your configured settlement destination (bank account or wallet), following the applicable settlement cycle. ```mermaid theme={null} flowchart TD A[Customer Initiates Payment] --> B[Payment Completed] B --> C[Novac Processing Engine] C --> D[Apply Split Configuration] D --> E1[Sub-Settlement Account 1] D --> E2[Sub-Settlement Account 2] D --> E3[Sub-Settlement Account N] D --> F[Primary Settlement Account] E1 --> G["Settlement (T+1 or applicable)"] E2 --> G E3 --> G F --> G G --> H[Bank Account or Novac Wallet] ``` This diagram illustrate how Novac handle split payment from the point of creating a transaction to fund settlement. ## Settlement Cycle Settlement timing determines when funds become available Local Transactions: T+1 (settled the next business day) International transaction: T+7 T+1 means the transaction is settled one business day after it is completed. ## Manage a Primary Settlement Account * When you have logged into your dashboard, click on settings on the right pane and select transaction settings. * Click on **Collection Settlement Destination** Novac merchant dashboard overview When you Click on **Collection Settlement Destination** you may select: * Novac Balance: This is your default Novac wallet used as your primary settlement destination. * Bank Account: When you select bank details, we automatically use your default bank your submitted during KYC. Your bank account can be changed if you intend to use another settlement bank details. Novac dashboard settlement account settings showing bank account configuration and wallet options. *** ## What Happens Next? Once your primary settlement account is configured: * You can [create sub-settlement](/docs/accept-payment/split-payment/manage-sub-settlement-accounts) accounts via API. * Define flat or percentage split rules. * Initiate transactions using split configuration via [create checkout payment](/docs/accept-payment/checkout/create-checkout-with-transaction-reference#create-checkout-payment-with-split-payment). * Automatically distribute funds upon successful payment. # Dedicated Virtual Accounts Source: https://developer.novacpayment.com/docs/accounts/create-virtual-account Learn how to create a dedicated or time-based account for payment collection. ## Overview Virtual accounts can also serve as a means of accepting payment. It's a unique account created for a single customer with an `accountName` and bank account number attached to them. This account can be used to receive transfer inflows from banks. Virtual accounts are not a pocket of funds, as they only keep a record of transaction inflow to the owner for reconciliation purposes. All inflow is routed back to the business accounts. ## Fetch supported settlement banks Novac has a list of supported banks you can pick from based on your preference and currency when creating a virtual account. Novac supports NGN and GHS currency virtual account creation. So you can pass either NGN or GHS as a query parameter when fetching the supported bank list. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/virtual-accounts/bank-list?currency=NGN \ --header 'Authorization: ' ``` ```json Response theme={null} { "status": true, "message": "Available Banks retrieved", "data": [ { "bankCode": "000036", "bankName": "Optimus Bank" }, ] } ``` ## Virtual account Types When creating a virtual account, you must specify the account type via the accountType field. Novac supports two types of virtual accounts. ```mermaid theme={null} flowchart TD A["Customer"] -->|Makes Payment| B["Virtual Account"] B -->|If accountType = 'reserved'| C["Dedicated Account (Continuous inflow)"] B -->|If accountType = 'checkout'| D["Checkout Account (One-time payment)"] C --> E["Main Business Account"] D --> E E -->|Funds Settled| F["Merchant Receives Funds"] ``` This flow explain how funds received via a virtual accounts will be routed back to the merchant business account. ### Reserved or dedicated virtual account To create a dedicated virtual account, set `accountType` to "reserved". This type of account is ideal for receiving continuous inflows over time, perfect for use cases such as wallet systems, savings apps, or betting platforms, where each customer has a permanent account number assigned to them. `reserved` accounts do not expire. When using `"reserved"` as the account type, set the `amount` field open. This indicates that the account can accept variable amounts rather than being tied to a fixed amount per transaction. ### Checkout To create a temporary checkout account, set accountType to "checkout". This type of account is used for one-time payments or time-limited checkout sessions. You can define how long the account remains active using the `expiryInMinutes` field. By default `"checkout"` account expires in 20mins. However, you can extend this time by setting your preferred time. ## Create a virtual account Novac allows merchants to generate virtual accounts for customers to receive payments seamlessly. When making the request, keep the following in mind: * `amount` – If supplied, the customer can only pay this exact amount per transaction. * `expiryInMinutes` – Defines how long the virtual account remains active before it expires. ```bash expandable Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/virtual-account \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "reference": "", "amount": 123, "accountType": "", "accountName": "", "bankCode": "", "firstName": "", "lastName": "", "customerEmail": "", "expiryInMinutes": 123 }' ``` ```json expandable Response theme={null} { "status": true, "message": "Virtual account generated", "data": { "accountNumber": "0830706484", "accountName": "Makanju Femi", "bankCode": "000000", "bankName": "Test NOVAC VA", "accountType": "reserved", "accountStatus": "active", "expiryInMinutes": 30, "reference": "1oVaJQQHLyQqqf1SwxjSpudeA069", "createdAt": "2025-10-06T22:46:48.5102348Z", "requestedAmount": 0, "expectedAmount": 0 } } ``` The response payload contains the `requestedAmount` as the original amount passed when you select checkout as your virtual account type. While the `expectedAmount` will be the original amount plus charges, as this is supposed to be a flash checkout account used for one-time payment. ## What next ? You can retrieve details of a virtual account using any of the following endpoints: * [Fetch virtual account by account number](/api-reference/virtual-account/retrieve-virtual-account-by-reference) * [Fetch virtual account by account reference](/api-reference/virtual-account/retrieve-virtual-account-by-account-number) # Balance Report Source: https://developer.novacpayment.com/docs/accounts/fetch-balance-report Fetch your wallet balance history across a date range, returned inline for small datasets or delivered to your email for larger exports. ## Overview The Balance Report API lets merchants retrieve a ledger of all wallet movements i.e **payouts**, **settlement fees**, **credits**, and more. Its filtered by currency and date range. Results under **1,000 records** are returned directly in the API response while results over **1,000 records** are compiled into a CSV and sent to your registered email address automatically. *** ## Fetch Balance Report Retrieve a chronological ledger of wallet movements including payouts, settlement fees, credits, and debits, filtered by currency and date range. This endpoint requires your **Secret Key** for authentication. Never expose your Secret Key in client-side code. ### Path Parameters | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ------------------- | | `currency` | string | ✓ | `NGN`, `GHS`, `USD` | | `startdate` | string | ✓ | Start of date range | | `enddate` | string | ✓ | End of date range | Both dates must follow the `yyyy-MM-dd`. The maximum range between `startdate` and `enddate` is **6 months**. *** ### Get Record ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/balancereport/NGN/2026-06-05/2026-07-01 \ --header 'Authorization: Bearer ' ``` When the result set is **1,000 records or fewer**, the full ledger is returned in the response body. ```json Response theme={null} { "status": true, "message": "Balance report details retrieved successfully", "data": [ { "type": "payout", "isDebit": "yes", "currency": "NGN", "domain": "live", "amount": "1,186.50", "balanceBefore": "2,730.89", "balanceAfter": "1,544.39", "reference": "XXXXXXXXXXXXXXXXXXXXXX", "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "status": "successful", "date": "27/06/2026 00:30" }, { "type": "settlement_fee", "isDebit": "yes", "currency": "NGN", "domain": "live", "amount": "18.00", "balanceBefore": "2,748.89", "balanceAfter": "2,730.89", "reference": "XXXXXXXXXXXXXXXXXXXXX", "note": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "status": "successful", "date": "27/06/2026 00:30" } ] } ``` *** ### Large export sent by email When the result set **exceeds 1,000 records**, the report is compiled into a CSV file and sent to your registered merchant email. The API response confirms the dispatch. ```json theme={null} { "status": true, "message": "Balance report sent to your email address" } ``` Check the email address registered on your Novac merchant account. The CSV is typically delivered within a few minutes. If you don't see it, check your spam folder. *** ### Error Responses | Scenario | Response | | ----------------------------------- | -------------------------------------------------------------------------------- | | No records found for the date range | `"No balance record found for date range : 2026-01-01 to 2026-01-24"` | | Wrong date format | `"End Date format is wrong please use the format :: yyyy-MM-dd (eg 2025-02-09)"` | | Range exceeds 6 months | `"You can only pull a maximum of 6 months No balance report."` | | Start date is after end date | `"Start Date cannot be greater than End Date."` | All error responses follow this structure: ```json theme={null} { "status": false, "message": "" } ``` *** ## What next ? * [Transfer funds from your wallet to a bank account](/docs/make-payment/make-payout) * [Manage Teams](/docs/accounts/manage-teams) # Manage Teams Source: https://developer.novacpayment.com/docs/accounts/manage-teams Learn how to manage roles and permissions to securely add new team members to your Novac Dashboard. ## Overview Roles in the Novac Dashboard help you define and manage the level of access each team member has to your business account.\ By creating custom roles, you can assign specific permissions based on responsibilities ensuring that only authorized users can perform sensitive actions such as initiating payouts, managing transactions, or viewing reports. The Administrator role is automatically created for the business account owner and has full permissions by default.\ If you want to delegate specific responsibilities without granting full access, you can create a new role and assign only the permissions required for that team member’s tasks. ## Create a new Role Follow the steps below to create a new role. Sign in to your [Novac Dashboard](https://app.novacpayment.com) using your registered account credentials. From the side menu, navigate to the Settings tab and click on "Roles and Permissions". Navigate to Roles and Permissions on Novac Dashboard By default, an "Administrator" role is automatically created for the business account owner.\ This role has full permissions and manages all account-level settings.\ To add a new role, proceed to the next step. Click on "Create New Role" to begin creating a custom role for your team member. Create a new role on Novac Dashboard You’ll be redirected to a page where you can enter the **Role Title** and **Description**.\ Once completed, click "Proceed to Permissions" to continue. Proceed to role permissions on Novac Dashboard On this page, select the specific permissions you want to assign to the new role.\ Carefully choose the permissions that align with the team member’s responsibilities. Select permissions for a new role on Novac Dashboard ## Invite a Team Member After successfully creating a team role, click to view the details to manage the role and see its associated permissions. From this page, you can either invite a user via email to assign them to the role or remove an existing member as needed. Invite a team member # Best Practices Source: https://developer.novacpayment.com/docs/api-basics/best-practices Follow these guidelines to securely and efficiently integrate with Novac Payment APIs. ## Overview To get the most out of Novac Payment APIs, it’s important to follow industry-standard best practices.\ These are guidelines that will help you to build a secure, reliable, and maintainable integrations for your business. By following these standards, you are ensuring that your business and customers data are well protected. *** ## Authentication * Keep secret Keys confidential, expose them in frontend code or public repositories could pose serious threat as an hawker can gain auathourize access to your API resources. * Ensure that you store secret keys in an environment variables. * Rotate keys periodically and revoke compromised keys immediately. * Use public keys only for client-side operations like checkout initialization. *** ## Use Test Mode First * Always start integration in test mode to avoid real charges. * Use the provided test cards, PINs, and OTPs to simulate transactions. * Verify edge cases: failed payments, declined transactions, refunds, and OTP validation. *** ## Receiving Payments * Ensure that you verify all transaction before giving value to your customers. * We advice that you listen to payment events via webhook. As its a reliable means of handling transaction updates. *** ## Handling Sensitive Information * Ensure that you encrypt all sensitive data when processing card information. * Follow our [direct card charge API](api-reference/collections/encrypt-data) for encrypting customers data. * Ensure that you reduce the storage of sensitive data if possible. *** ## Handle Errors Gracefully * Implement **retry logic** for transient network or server errors. * Always check the status, `responseCode`, and `responseMessage` in API responses. * Surface clear error messages to users e.g., “Invalid card details”, instead of raw API errors. * Ensure that you store all logs properly and follow [global log retention standard](https://docs.exabeam.com/en/exa-search/all/search-guide/search-overview/log-retention/global-log-retention.html) # Encryption Source: https://developer.novacpayment.com/docs/api-basics/encryption Learn how encryption protects sensitive payment data when using Novac Payment APIs. ## What is Payment Encryption? In payment systems, sensitive data such as card numbers, CVV, and bank details must be protected.\ If exposed, this information could be used by malicious actors to impersonate customers and perform fraudulent transactions. Encryption is the process of converting sensitive data into a secure, unreadable format. Without the correct decryption key, unauthorized parties cannot make sense of the data. This ensures that even if intercepted, the information remains useless to attackers. ## Why It Matters Encrypting customer card details and bank information is a fundamental security requirement when integrating with Novac’s Direct Card Charge API. Instead of asking you to implement and maintain your own encryption algorithms, Novac provides a ready-to-use encryption service. To simplify your integration, Novac offers an encryption endpoint where you can send customer card details. The API will return an encrypted version of the data, which you can safely transmit during transactions. You can also use the provided decryption method when needed. ```json Encryption API theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/encrypt-data \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "data": { "number": "", "expiryMonth": "", "expiryYear": "", "cvv": "", "pin": "" }, "reference": "" }' ``` ```json Decryption API theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/decrypt-data \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "encryptedData": "", "reference": "" }' ``` # Environment Source: https://developer.novacpayment.com/docs/api-basics/environment Learn how to use Test and Production environments when integrating with Novac. ## Overview When working with Novac Payment APIs, you’ll interact with two distinct environments: the test and production environments. The test environment is designed for developers for the purpose of simulating transactions without moving real money. They also get to experiment with API requests and responses while ensuring every detail of implementation works accordingly before going live. The production environment is where the real transaction happens; therefore, it's important to protect your live credential by following the guidelines in [best practices](/docs/api-basics/best-practices). Avoid testing with customer accounts in production; instead, use test mode. ## Switching Between Test and Production Both the production and test environments use the same `baseURL: https://api.novacpayment.com/` The common difference is to authenticate with the appropriate environment keys. Each account in Novac is issued two sets of API keys: * Public and secret keys for test * Public and secret keys for production When moving from development to production: 1. Replace your test keys with the production keys in your application. 2. Update your base URL to point to the Production API. 3. Confirm that all configurations (webhooks, callbacks, etc.) are pointing to production endpoints. # Common Errors Source: https://developer.novacpayment.com/docs/api-basics/errors Learn how to troubleshoot and resolve common errors when interacting with Novac Payment APIs. ## Overview Errors can occur during interactions with the Novac API for different reasons.\ This guide explains the types of errors you might encounter and how to resolve them efficiently. *** ## Authentication Errors Authentication errors happen when there are issues with your API credentials. * Ensure you’re using the correct Public or Secret keys. * Verify that keys are placed in the correct headers. * Check that you’re using the right keys for **Test** vs **Live** environments. *** ## Validation Errors Validation errors occur when your request data does not meet the required format or criteria.\ Common causes include: * Missing required fields. * Invalid data formats for example, wrong date or number format. * Exceeding character or length limits. Fix: Review the API documentation for required parameters and correct formatting. *** ## Server Errors Server errors indicate issues on Novac’s side, such as outages or temporary service interruptions. * If you encounter a server error, wait a few moments and retry the request. * If the issue persists, contact Support. *** ## Common Errors ### 400 Bad Request This happens when the request payload or parameters are invalid.\ Double-check required fields, data types, and formatting. ```json theme={null} { "status": false, "message": "Invalid request parameter.", "data": { "responseCode": "T1", "responseMessage": "Invalid request parameter." } } ``` ### 401 Unauthorized This error indicates that the request lacks proper authentication credentials or the provided credentials are incorrect. Make sure you have provided valid API keys and configured them correctly in your request headers. ```json theme={null} { "status": false, "message": "Invalid Merchant Authorization.", "data": { "responseCode": "B01", "responseDescription": "Invalid Merchant Authorization." } } ``` ### 403 Forbidden This error indicates that the wrong API keys is used to access API resources, Please ensure that you are using public keys for product like checkout and direct charge. while using secret keys for anything related to making payments. ```json theme={null} { "status": false, "message": "Invalid Merchant Authorization..." } ``` # Testing Source: https://developer.novacpayment.com/docs/api-basics/testing Use Novac test credentials to simulate payment flows before going live. ## Overview Novac provides test credentials that allow you to simulate different payment scenarios while integrating with the gateway.\ These credentials help you test successful payments, failed transactions, and OTP validation before switching to the live environment. ## Test Cards Use this card to simulate successful or failed transactions . Make sure you set a valid future date for the expiryMonth and expiryYear. **Card Number:** `5555555555554444`\ **Expiry:** `12/30`\ **CVC:** `123` **Card Pin:** `1234` **Card Number:** `1234567898765432`\ **Expiry:** `12/30`\ **CVC:** `455` **Card Pin:** `567` The successful test card simulates a typical debit/credit card that will result in a “successful” payment response, while the failed test card forces a transaction failure (e.g., insufficient funds, declined transaction). Expected Gateway Response: Payment declined or failure. ## OTP Validation Use this OTP to simulate additional verification (3-D Secure or other form of 2FA). ```json theme={null} { "otp": "Any 6 digits (e.g., 123456)" } ``` When to Use: After initiating a payment with a card and additional verification is requested. Expected Gateway Response: OTP verified or OTP error if incorrect. # Webhooks Source: https://developer.novacpayment.com/docs/api-basics/webhooks Learn how to set up and handle webhook notifications in Novac Payment. ## Overview Webhooks are a communication mechanism that enables event-driven notifications between systems. When an event occurs in Novac system, such as a payment being completed or a payout being initiated. Novac automatically sends a real-time notification to the merchant’s system. This means your system doesn’t have to constantly poll Novac for updates. Instead, you simply provide Novac with a publicly accessible webhook URL, and Novac will send a `POST` request to that endpoint whenever a relevant event occurs. Webhook URLs must be publicly accessible at all times in order to receive notifications. This whole process makes it easier to keep your system in sync with payment statuses when you integrate with Novac. ## Process Flow This sequence diagram illustrates the process flow from initiating a checkout payment to its completion, involving the customer, the merchant system, and Novac. ```mermaid theme={null} sequenceDiagram participant C as Customer participant N as Novac Payment System participant M as Merchant System C->>N: Initiates payment (card/bank/mobile) N->>N: Process & authorize payment N-->>C: Payment status (success/failure) Note over N,M: Webhook event triggered N->>M: HTTP POST request (webhook notification) M->>N: 200 OK (acknowledge receipt) Note over M: Merchant verifies transaction
via Verify Transaction API ``` With Novac payment, you don’t need to manually subscribe to webhook events.\ Once you configure your webhook URLs in the dashboard, Novac automatically sends notifications whenever relevant events occur in your account. *** ## Setting Up Your Webhook Sign in to your [**Novac Dashboard**](https://app.novacpayment.com) using your account credentials. From the sidebar menu, go to Settings, Click on API settings tab.\ This is where you can configure both test and live webhook URLs. Enter the publicly accessible URLs where you want to receive webhook notifications. * Add a test webhook URL for test transactions. * Add a live webhook URL for real payments in production. * Ensure the URLs are always available and accept `POST` requests. Novac will send an HTTP `POST` request to these URLs after a transaction is completed. *** ## Notification Types | Notify Type | Description | Common Scenario | | ------------ | -------------------------------------------------- | ------------------------------------------------ | | `successful` | Payment or transaction was processed successfully. | A customer’s card or bank transfer succeeded. | | `failed` | Transaction attempt failed or was declined. | Insufficient funds or incorrect payment details. | | `reversed` | A previously successful transaction was reversed. | Refunds or chargeback scenarios. | | `abandoned` | Transaction was started but not completed. | Customer exited before finalizing payment. | *** ## Handling Webhook payload Each webhook request payload sent from Novac follows the structure below: ```json expandable Collection Webhook Sample theme={null} { "data": { "id": 0, "card": { "type": "", "token": "", "issuer": "", "country": "", "last4Digits": "", "first6Digits": "" }, "amount": 300, "domain": "live", "status": "failed | reversed | successful | abandoned", "channel": "", "currency": "NGN", "customer": { "id": 0, "name": "", "email": "", "customerCode": "" }, "requestIp": "", "redirectUrl": "", "chargedAmount": 0, "transactionFee": 0, "transferDetail": { "bankCode": "", "bankName": "", "sessionId": "", "accountNumber": "", "originatorName": "", "creditAccountName": "", "originatorAccountNumber": "" }, "checkoutMetadata": "{}", "authorizationCode": "", "paymentDescriptor": "NOVAC", "gatewayResponseCode": "", "transactionReference": "" }, "notify": "transaction | wallet_funding | banktransfer", "notifyType": "failed | reversed | successful | abandoned" } ``` ```json Payout Webhook Sample theme={null} { "data": { "id": 1, "fee": "50.00", "amount": "500.00", "domain": "test | live", "status": "successful | failed | reversed", "currency": "NGN | GHS", "bank_code": "123456", "bank_name": "Test bank name", "narration": "Test Narration", "reference": "XXXXXXXXXXXXXXXXXXXXXXXXXX", "sessionid": "XXXXXXXXXXXXXXXXXXXXXXXXXX", "created_at": "2026-06-19T09:11:18", "updated_at": "2026-06-19T08:11:39", "countryCode": "NG | GH", "account_name": "Test Account Name", "account_number": "1234567890", "stamp_duty_fee": "50.00" }, "notify": "payout", "notifyType": "successful | failed | reversed" } ``` ```json expandable Sample success charge event theme={null} { "data": { "card": { "type": "MasterCard", "token": "", "issuer": "PROVIDUS BANK PLC", "country": "123", "last4Digits": "1234", "first6Digits": "123455" }, "amount": 10, "domain": "live", "paidAt": "2026-08-07T09:20:56", "status": "successful", "channel": "card", "endDate": "2036-08-07T10:14:10", "currency": "NGN", "customer": { "id": 1, "name": "string", "email": "string", "customerCode": "string" }, "reference": "string", "requestIp": "123.123.123.123", "startDate": "2026-08-07T10:14:10", "chargedAmount": 10, "transactionFee": 0.15, "nextPaymentDate": "2026-08-07T10:14:10", "transactionType": "transaction", "checkoutMetadata": "{\"name\": \"string\"}", "subscriptionStatus": "active", "transactionChannel": "card", "gatewayResponseCode": "00", "gatewayResponseMessage": "successful" }, "notify": "recurringtransaction", "notifyType": "successful" } ``` ```json expandable Sample failed charge event theme={null} { "data": { "card": { "type": "MasterCard", "token": "", "issuer": "PROVIDUS BANK PLC", "country": "123", "last4Digits": "1234", "first6Digits": "123455" }, "amount": 10, "domain": "live", "paidAt": "2026-08-07T09:20:56", "status": "failed", "channel": "card", "endDate": "2036-08-07T10:14:10", "currency": "NGN", "customer": { "id": 1, "name": "string", "email": "string", "customerCode": "string" }, "reference": "string", "requestIp": "123.123.123.123", "startDate": "2026-08-07T10:14:10", "chargedAmount": 10, "transactionFee": 0.15, "nextPaymentDate": "2026-08-07T10:14:10", "transactionType": "transaction", "checkoutMetadata": "{\"name\": \"string\"}", "subscriptionStatus": "failed", "transactionChannel": "card", "gatewayResponseCode": "99", "gatewayResponseMessage": "Card tokenization failed" }, "notify": "recurringtransaction", "notifyType": "failed" } ``` The webhook structure provides complete details about the transaction event, including customer, card, and transfer details. For best practices, after receiving a webhook, we recommend that you validate the transaction status by using the [verify transaction endpoint](/docs/accept-payment/manage-payment/verify-transaction). *** ## Verifying Webhook Source Webhooks are publicly available URLs; this means that anyone can fake a webhook sample and send a fake request to your system. It's important to verify that all webhooks received are from Novac to avoid man-in-the-middle attacks. To verify the webhook your system received. We advise merchants to allow requests from a dedicated network address. We provide our IP address, and you should verify that every webhook request comes from it. This method is called IP whitelisting. Novac public IP address: **18.233.137.110** It's important to know that we can add to this IP at any point in time; however, we will inform our merchant before doing so. ### What is IP whitelisting? IP whitelisting is a mechanism used on the server-side as a filter; it helps ensure only a pre-approved set of IP addresses or [IP ranges](https://help.clickguard.com/hc/en-us/articles/11875170187933-What-Is-an-IP-Address-Range) have the right to hit a server. If a request comes from an unknown IP address, your server will reject it. You must use IP whitelisting as a layer of protection for incoming webhooks. If your system is behind a [proxy](https://www.fortinet.com/resources/cyberglossary/proxy-server) or [load balancers](https://www.cloudflare.com/learning/performance/what-is-load-balancing/), you must obtain the real client IP. ### Validate incoming webhook IP address. To validate incoming webhooks, we have provided sample codes to give you a better context on how to go about this depending on your programming language. ```javascript NodeJs theme={null} // simple-ip-whitelist.js const express = require('express'); const app = express(); const ALLOWED_IPS = ['18.233.137.110']; app.set('trust proxy', true); // check for proxy or load balancer function ipWhitelist(req, res, next) { const clientIp = (req.ip || '').replace(/^::ffff:/, ''); // normalize IPv4-mapped IPv6 if (ALLOWED_IPS.includes(clientIp)) return next(); console.warn(`Blocked webhook from IP: ${clientIp}`); return res.status(403).send('Forbidden'); } app.post('/webhook', ipWhitelist, express.json(), (req, res) => { // handle verified webhook here res.status(200).send({received: true}); }); app.listen(3000, () => console.log('Webhook listener on :3000')); ``` ```php PHP theme={null} 'Forbidden']); exit; } // Handle verified webhook http_response_code(200); echo json_encode(['received' => true]); ``` ```go Golang theme={null} package main import ( "encoding/json" "log" "net" "net/http" "strings" ) var allowedIPs = []string{"18.233.137.110"} func getClientIP(r *http.Request) string { // Try to read X-Forwarded-For if behind proxy xff := r.Header.Get("X-Forwarded-For") if xff != "" { parts := strings.Split(xff, ",") return strings.TrimSpace(parts[0]) } ip, _, _ := net.SplitHostPort(r.RemoteAddr) return ip } func ipWhitelistMiddleware(next http.HandlerFunc) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { clientIP := getClientIP(r) allowed := false for _, ip := range allowedIPs { if clientIP == ip { allowed = true break } } if !allowed { log.Printf("Blocked webhook from IP: %s\n", clientIP) w.WriteHeader(http.StatusForbidden) json.NewEncoder(w).Encode(map[string]string{"error": "Forbidden"}) return } next(w, r) } } func webhookHandler(w http.ResponseWriter, r *http.Request) { w.Header().Set("Content-Type", "application/json") json.NewEncoder(w).Encode(map[string]bool{"received": true}) } func main() { http.HandleFunc("/webhook", ipWhitelistMiddleware(webhookHandler)) log.Println("Listening on :3000") log.Fatal(http.ListenAndServe(":3000", nil)) } ``` ```py python (Flask) theme={null} from flask import Flask, request, jsonify app = Flask(__name__) ALLOWED_IPS = ['18.233.137.110'] def get_client_ip(): # Use X-Forwarded-For if behind proxy if 'X-Forwarded-For' in request.headers: return request.headers['X-Forwarded-For'].split(',')[0].strip() return request.remote_addr @app.route('/webhook', methods=['POST']) def webhook(): client_ip = get_client_ip() if client_ip not in ALLOWED_IPS: app.logger.warning(f"Blocked webhook from IP: {client_ip}") return jsonify({'error': 'Forbidden'}), 403 return jsonify({'received': True}), 200 if __name__ == '__main__': app.run(port=3000) ``` It is crucial to thoroughly validate and properly test this with a test webhook before going live. In a case where your system is behind a proxy such as nginx. You can do a double validation, e.g., first validate in your config file that the webhook is coming from the Novac network address. If successful, you can then route this webhook to the endpoint defined in your system, which also runs another check to validate the request. *** ## Retries To ensure reliable delivery, Novac automatically retries webhook notifications when your server fails to respond with a successful 200 OK status code. Your webhook endpoint must always respond with HTTP 200 to acknowledge receipt of the event. Any other status code (e.g., 4xx or 5xx) will trigger a retry attempt. **Retry Policy** | Parameter | Description | | -------------- | ----------------------------------------------------------------------------------- | | Retry Count | 3 attempts | | Retry Interval | Every 5 seconds between retries | | Condition | Triggered when Novac doesn’t receive a `200 OK` response from your webhook endpoint | # Create Account Source: https://developer.novacpayment.com/docs/getting-started/create-merchant-account Learn how to sign up for a Novac merchant account and get started with payments. ## Overview Before you can make any API calls or start accepting payments, you need a Novac merchant account. During signup, you will choose an account type **Individual** or **Business** and complete KYC verification. Your account type determines your merchant name, transaction limits, and access to certain features like managing multiple business profiles. ## Account Types Novac supports two types of accounts. Choose the one that matches your situation before you sign up, you cannot switch types after account creation. For sole traders, freelancers, and developers building personal projects. * Your merchant name is derived from your **BVN-validated name** * Standard transaction limits apply * Full API access * Cannot add sub-businesses For registered companies, startups, and multi-branch operations. * Your merchant name is derived from your **CAC-validated business name** * Higher transaction limits * Full API access * Can add and manage multiple sub-businesses Both account types have access to the full Novac API. The primary differences are **transaction limits** and the ability to manage **multiple business profiles**, which is exclusive to Business accounts. *** ## Steps to Create an Account Go to the [**Sign Up**](https://www.app.novacpayment.com/register) page and complete the registration form. Provide a valid email address, we’ll use this to verify your account, choose a strong password, and fill any required business details. **Tips** * Use a strong password (8+ characters recommended). * If you plan to accept payments from customers, use your business email for clarity in communications. After sign up, check your inbox for a verification message from **[hello@novacpayment.com](mailto:hello@novacpayment.com)** and click the verification link to activate your account. **If you don't see the email** * Check Spam/Promotions folders. * Use the **Resend verification** option on the signup page. * If the link expires, request a fresh verification email. Once verified you will either receive a login link or be redirected to the Novac dashboard. After logging in, complete your account profile so the dashboard can show the right tools and configuration options. Choose either **Individual** or **Business** depending on your setup. | | Individual | Business | | ----------------------- | ------------------ | --------------------------- | | Merchant name source | BVN-validated name | CAC-validated business name | | Transaction limits | Standard | Higher | | Sub-business management | ✗ | ✓ | | API access | ✓ | ✓ | **Why this matters** * Accurate details speed up KYC and payout setup. * The dashboard uses this information to pre-fill forms and generate correct receipts and statements. To access live payment features (payouts, larger volumes, live API keys) you’ll need to submit KYC information. **Typical documents you may be asked for** * Business registration/incorporation document (e.g., certificate of incorporation). * Government-issued ID (passport, national ID, or driver’s license) for beneficial owners and signatories. * Proof of address (utility bill or bank statement dated within last 3 months). * Bank statement or voided cheque for the account that will receive payouts. * A short statement of business activity or website link (helps verification). **Process** * Upload documents via the Dashboard > Settings > KYC (or the onboarding flow). * Review times vary, you’ll be notified by email when the review completes. * While KYC is pending, you can still use **Test mode** to integrate and validate your code. Once your account is set up and KYC is completed, proceed to get your API keys; see [obtain API keys](docs/getting-started/obtain-api-keys) > to get started. *** ## Managing Multiple Businesses This feature is available to **Business accounts only**. Individual accounts cannot add sub-businesses. ```mermaid theme={null} flowchart TD A(["master business account"]) A --> B["Business A · Head Office"] A --> C["Business B · Lagos Branch"] B --> B1["API Keys"] B --> B2["Wallet Balance"] B --> B3["Virtual Account"] C --> C1["API Keys"] C --> C2["Wallet Balance"] C --> C3["Virtual Account"] style A fill:#7C3AED,color:#fff,stroke:none style B fill:#EDE9FE,stroke:#7C3AED,color:#1a1a1a style C fill:#EDE9FE,stroke:#7C3AED,color:#1a1a1a ``` ### What is Sub-Business Management? If your company operates multiple branches, outlets, or product lines, Novac lets you create and manage separate business profiles, all under one login. This means: * **No separate signups** for each branch or outlet. Add them directly from your dashboard. * **Each sub-business is fully independent** it gets its own API keys, wallet balance, virtual account, settlement account, and transaction history. * **Switch between businesses** from the dashboard or at login select the profile you want to work with and the dashboard updates to reflect that business's data entirely. Think of it as one master login that gives you access to several fully isolated merchant environments. ### Adding a New Sub-Business Sign in at [app.novacpayment.com](https://app.novacpayment.com) using your Business account credentials. In the dashboard, locate the business/profile section (typically in the bottom navigation or sidebar) and click **Add New Business**. This option is only visible on Business accounts. If you are on an Individual account, this option will not appear. Fill in the details for the new business name, business type, and any required documentation. Novac validates the business name against CAC records. Once created, the new business appears in your business list. You can switch to it from the dashboard at any time, or select it during login when prompted to choose a business profile. *** ## What’s Next? **Before going live** * Complete KYC and confirm live keys are visible. * Add your production secret key to a secure secrets manager. * Test full payment flows in Test mode (hosted checkout, direct charge, tokenization, refunds, webhooks). * Configure webhooks and verify signature verification locally. # Obtain API Keys Source: https://developer.novacpayment.com/docs/getting-started/obtain-api-keys Learn how to access your API keys and authenticate requests to Novac Payment APIs. ## Overview To ensure seamless communication between your application and Novac Payment, you'll need your API keys. Novac uses these keys to authenticate every request from your application. Each account is provided with two sets of API keys **public** and **secret** for both **Test** and **Live** environment. ### Public keys Public keys are safe to use on the client-side. They are typically used for initiating transactions such as **checkout, payment links, and in-app collections**. Public keys cannot modify your account or access sensitive data. ### Secret keys Secret keys are highly sensitive and must be kept confidential. They are used for secure operations such as **payouts, refunds, and accessing financial data**. All server-side API calls should be authenticated with your secret key. Never expose your secret keys in client-side code. If you suspect that your secret key has been compromised, you can quickly regenerate it on your Novac dashboard. This renders the old one useless. ## Obtaining your API Keys You can easily access your API keys from the Novac dashboard. Start by signing in to your Novac account to access your dashboard. In the dashboard sidebar, click on **Settings** to manage your account preferences. Novac dashboard API Settings tab showing Public and Secret API keys for Test and Live environments. The interface displays key values and options to regenerate keys. The environment is a clean dashboard layout with sidebar navigation. Text in the image includes API Settings, Public Key, Secret Key, Test, Live, and Regenerate. Under the **API Settings** section, you’ll see both your **Test API keys** and **Production API Keys**. # Payment Methods Source: https://developer.novacpayment.com/docs/getting-started/payment-methods Learn about the supported payment methods available on Novac and how to use them effectively in your integration. ## Overview Novac supports multiple payment methods to give your customers flexibility and improve transaction success rates. Each method is optimized for speed, security, and convenience. Whether you're using our prebuilt checkout, collection APIs, or payment links. Depending on your integration flow, you can dynamically select or allow customers to choose their preferred payment method at checkout. *** ## Supported Payment Methods Accept **Visa**, **Mastercard**, and **Verve** cards with 3DS authentication for added security. Ideal for web and mobile checkout where customers enter their card details. Generate a unique virtual account number for customers to complete payment via their bank app. Useful for one-time payments and reduces card decline rates. Provide a USSD code for customers to complete payment directly from their mobile phone. Best for customers with limited internet access or those using feature phones. Accept payments via MTN Ghana and Telecel Ghana mobile money wallets. Allow customers to pay using Opay via hosted checkout or custom checkout integrations Allow customers to pay using Palmpay via hosted checkout or custom checkout integrations. Allow customers to pay using their Novac wallet balance or a connected account. Suitable for repeat customers or in-app balance systems. A QR code generated automatically for merchants on payment link creation. Great for quick scan-and-pay scenarios at the point of sale. # Payment Preferences Source: https://developer.novacpayment.com/docs/getting-started/payment-preference Learn about the supported payment methods available on Novac and how to optimize checkout experience and fee handling. ## Overview Payment preference on Novac gives you control over how your customers pay and how transaction fees are handled during checkout. Instead of showing every available payment option or applying a fixed fee behavior, you can tailor the experience to match your business goals. This helps you: * Improve conversion by simplifying payment choices * Guide customers toward preferred payment methods * Decide who bears transaction fees (you or your customer) * Maintain better control over your revenue and margins Ultimately, payment preference is about optimizing both user experience and business outcomes. *** ## Controlling Payment Methods To control which payment channels are presented to customers at checkout. You can configure this at two levels: a **global default** on the dashboard which applies to all transactions, or a **per-transaction override** via the checkout API which applies to that transaction only. You can restrict what users see at checkout: * `"CARD,PWBT"` Only card and bank transfer * `"USSD"` Only USSD payments * `"Opay"` Only Opay * `"Palmpay` Only palmpay This ensures your customers are presented with only the most relevant options. ### Set a Global Default on the Dashboard The dashboard setting acts as your **default preference for all transactions**. It is the right choice when you want to consistently restrict or curate channels across your entire checkout flow without touching your code. Go to your to [your app and sign in](https://app.novacpayment.com). Click on **settings** in the sidebar and select **transaction settings** tab. Choose one or more payment channels. Your selection applies to all future transactions unless overridden at the checkout level. Click **Save**. The preference takes effect immediately for new transactions. ### Set Per-Transaction via the Checkout API This is useful when different parts of your product have different payment needs for example, showing only bank transfer for high-value orders, or only card options for a specific product category. Pass the `allowedPaymentOptions` field in your checkout request to control which channels appear for that specific transaction. ```bash theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/paymentlink/initiate \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "paymentLinkReference": "oeXQckL", "amount": 100, "currency": "NGN", "metaData": "{}", "allowedPaymentOptions":"CARD,PWBT,OPAY,USSD,PALMPAY,MOMO" "checkoutCustomerData": {}, "checkoutCustomizationData": {} }' ``` When you set `allowedPaymentOptions`, it will overrides whatever settings you have on the dashboard for that checkout session only. *** ## Fee Handling Options In addition to payment methods, you can also control **who pays the transaction fee**. This directly impacts both the customer experience and your final settlement amount. Novac merchant dashboard overview *** ### I will cover (Merchant pays the fee) The transaction fee is deducted from the payment amount before settlement. * Customer pays: ₦500 * Fee: ₦30 * Merchant receives: ₦470 This approach creates a smoother checkout experience since the customer pays exactly what they expect, with no extra charges. Novac merchant dashboard overview *** ### Customer covers (Customer pays the fee) The transaction fee is added on top of the payment amount. * Customer pays: ₦500 + ₦30 = ₦530 * Merchant receives: ₦500 This ensures you receive the full payment amount, making it ideal if you want to protect your margins. # Glossary Source: https://developer.novacpayment.com/docs/introduction/glossary Key terms and concepts you need to know when integrating with the Novac Payment API. A reference guide to the terminology used across the Novac Payment documentation. Understanding these terms will help you integrate faster and avoid common mistakes. *** ## A ### API Key A credential used to authenticate your application's requests to Novac. Each Novac account comes with two types of keys **Public** and **Secret** issued for both the **Test** and **Live** environments. ### Authorization Code A unique token returned after a successful card transaction. It confirms that the card issuer has approved the charge. Stored in webhook payloads as `authorizationCode`. ### Abandoned Transaction A transaction that was initiated but never completed typically because the customer exited the checkout flow before finalising payment. Reported as `notifyType: "abandoned"` in webhooks. *** ## B ### Bank Transfer A payment method where a unique virtual account number is generated for the customer. The customer completes payment via their bank app by sending funds to that account. Reduces card decline rates and is useful for one-time payments. ### Base URL The root endpoint for all Novac API calls: ``` https://api.novacpayment.com/ ``` Both Test and Production environments share this base URL. The environment is determined by which API key you authenticate with. *** ## C ### Callback URL / Redirect URL The URL your server or frontend provides to Novac so customers can be redirected after completing a payment. Also used to carry transaction references back to your system. ### Card Tokenisation The process of replacing a customer's raw card details with a secure token `card.token` that can be stored and used to charge the card again in the future — without re-entering card details. Essential for recurring billing. ### Checkout A payment session initiated by your server. Novac supports two checkout modes: * **Prebuilt Checkout** - Novac's hosted UI; minimal setup required. * **Custom Checkout** - You build the UI and call Novac APIs directly for full control. ### Collection API (Direct Card Charge) A server-side API for charging a customer's card directly without redirecting them to a hosted checkout page. Requires card details to be encrypted before transmission. ### CVV Card Verification Value - the 3- or 4-digit security code on a payment card. Must be encrypted using Novac's Encryption API before being sent in Direct Card Charge requests. *** ## D ### Dedicated Virtual Account A persistent virtual bank account assigned to a specific customer or business entity. Unlike a checkout virtual account, it doesn't expire after a single transaction. Used for ongoing payment collection. ### Decryption API An endpoint provided by Novac `POST /api/v1/decrypt-data` that reverses encrypted card data back to its original form. Use this when you need to inspect or process previously encrypted card details. *** ## E ### Encryption The process of converting sensitive data (card numbers, CVV, PIN) into an unreadable format so it cannot be intercepted or misused in transit. Novac provides a dedicated Encryption API endpoint `POST /api/v1/encrypt-data` so you don't need to implement your own. ### Environment Novac operates in two environments: | Environment | Purpose | | --------------------- | ------------------------------------------ | | **Test** | Simulate transactions; no real money moves | | **Production / Live** | Real transactions with real money | Switch between them by swapping your API keys. The base URL is the same for both. *** ## G ### Gateway Response Code A code returned by the underlying payment gateway indicating the result of a transaction attempt. Included in webhook payloads as `gatewayResponseCode`. Useful for diagnosing failed transactions. *** ## I ### IP Whitelisting A server-side security measure that only allows webhook requests from pre-approved IP addresses. Novac's public IP address is `18.233.137.110`. You should configure your webhook endpoint to reject requests from any other IP to prevent fake/spoofed webhook attacks. *** ## M ### Merchant Account A Novac business account that gives you access to the dashboard, API keys, and payment infrastructure. Required before any integration can begin. ### Mobile Money (MoMo) A payment method that lets customers pay using their mobile wallet balance. Novac currently supports **MTN Ghana** and **Telecel Ghana** mobile money wallets for GHS-denominated transactions. *** ## N ### NQR A QR code automatically generated by Novac when a payment link is created. Customers scan the code to initiate payment, suited for point-of-sale scenarios. ### Notify Type A field in the webhook payload (`notifyType`) that describes the outcome of a transaction event. Possible values: | Value | Meaning | | ------------ | ----------------------------------------------------------------- | | `successful` | Transaction completed successfully | | `failed` | Transaction was declined or failed | | `reversed` | A successful transaction was reversed (e.g. refund or chargeback) | | `abandoned` | Customer started but did not complete the payment | *** ## P ### Payout A transfer of funds from your Novac wallet to an external bank account. Used for disbursements, vendor payments, and settlements. Authenticated with your **Secret Key**. ### Payment Descriptor The name that appears on a customer's bank statement to identify the merchant. Novac's default descriptor is `NOVAC`. ### Payment Link A shareable URL that leads customers to a hosted checkout page. No custom UI required. Payment links also auto-generate an NQR code. ### Payment Preference Configuration that controls which payment methods are available at checkout and how transaction fees are handled (e.g. borne by merchant vs. passed to customer). ### Public Key A non-sensitive API key safe to use in client-side code. Used to initiate transactions — checkout sessions, payment links, and in-app card collections. **Cannot** modify account settings or trigger payouts. *** ## R ### Recurring Billing The ability to charge a customer's card on a schedule without requiring them to re-enter their card details. Enabled by saving a card token after the first successful transaction and using the Tokenised Card Charge endpoint for subsequent charges. ### Refund The process of returning funds to a customer for a completed transaction. Novac supports: * **Full Refund**: Returns the entire charged amount. * **Partial Refund**: Returns a portion of the charged amount. ### Reference (Transaction Reference) A unique string you generate to identify a transaction in your system. It is passed to Novac when creating a checkout and returned in webhooks and verification responses. Use it to match Novac events back to your own records. *** ## S ### Secret Key A highly sensitive API key that must **never** be exposed in client-side code or public repositories. Used for secure server-side operations: payouts, refunds, and accessing financial data. Regenerate immediately on the dashboard if compromised. ### Settlement The process by which collected payment funds are disbursed to your bank account. Novac supports split settlement via **Sub-settlement Accounts**. ### Split Payment / Sub-settlement Account A feature that allows incoming payments to be automatically split between a primary settlement account and one or more sub-accounts. Useful for marketplace or multi-vendor platforms. *** ## T ### 3DS (3D Secure) An additional authentication layer for card payments. After entering card details, the customer is asked to verify their identity (e.g. via OTP). Novac's Collection API supports initiating and retrieving the status of 3DS challenges. ### Tokenised Card Charge Charging a customer using a saved card token instead of raw card details. Requires the card to have been tokenised during a previous transaction. See Card Tokenisation. ### Transaction Fee The fee charged per transaction. Retrievable via the `GET /checkout/transaction-fee` endpoint before initiating a checkout. Can be configured to be borne by the merchant or passed to the customer. *** ## U ### USSD Payment A payment method where the customer dials a short code on their mobile phone to authorise payment. Works without internet access and is ideal for customers on feature phones or in areas with poor connectivity. *** ## V ### Verify Transaction An API call you make **after** receiving a webhook to independently confirm the transaction status directly with Novac. This is a best practice to prevent acting on forged webhook payloads. ### Virtual Account A bank account number generated by Novac for the purpose of receiving payments. Can be **dedicated** (persistent, tied to a customer) or **checkout-based** (temporary, expires after a single use). ### Void Transaction The cancellation of a transaction that has been authorised but not yet settled. Supported via the `POST /collections/void-transaction` endpoint. *** ## W ### Wallet A Novac-managed balance that can be used to fund payouts, purchase `airtime/data/electricity`, or accept customer payments. Balance is retrievable via the `GET /payouts/retrieve-balance` endpoint. ### Webhook An HTTP `POST` request that Novac automatically sends to your configured URL when a transaction event occurs (payment success, failure, reversal, etc.). Eliminates the need to poll the API for status updates. Novac retries failed delivery up to **3 times**, every **5 seconds**. *** Terms are listed in alphabetical order. For full API references, visit the [API Reference](/api-reference/checkout/introduction) section of the Novac documentation. # Key Features Source: https://developer.novacpayment.com/docs/introduction/key-features Learn about all Novac API features. Novac provides key features that can serve so many use cases in today's world. From custom checkout to hosted prebuilt checkout, you can explore all features and find your use case. Whether you are building an enterprise app or trying to accept a one-time payment for service-based work. We've got you covered. *** Accept payments quickly using a pre-built, secure checkout page.\ Ideal for fast integration with minimal code. Build your own checkout flow with Direct Charge APIs.\ Full control over UI, authentication, and customer experience. Save customer cards securely and charge them later.\ Enable one-click payments and faster checkout experiences. Generate shareable payment links.\ Get paid via email, SMS, or social platforms without a full integration. Transfer money to bank accounts, vendors, or partners.\ Includes bank verification and payout reporting. Refund customer transactions fully or partially.\ Manage disputes and keep your payment flow flexible. Create virtual accounts for your customers.\ Simplify reconciliation and enable seamless collections. ​ # Welcome to Novac Source: https://developer.novacpayment.com/docs/introduction/welcome-to-novac Discover how to integrate Novac Payment APIs to accept payments, send payouts, and handle bills seamlessly. This documentation provides in-depth guides, use cases, and ready-to-use code samples for enterprises and businesses looking to integrate payment infrastructure into their day-to-day workflow. Let's dive straight in! ## Quickstart Collect payments through hosted checkout, custom checkout, or payment links. Choose between quick setup or full control over the checkout experience. Send money instantly with APIs for payouts. Perfect for businesses that need to automate disbursements at scale. Create and manage dedicated or checkout virtual accounts to receive payments seamlessly from your customers. Listen for real-time event notifications and automate your workflows whenever payments, transfers, or account activities occur. ## Build with Our API Our API is designed to be developer-friendly and AI-readable whether you're building manually or using an AI coding agent. Every endpoint is clearly structured, consistently documented, and easy to navigate programmatically. Our documentation is structured so that AI agents and LLMs can read, reason, and build with Novac APIs with minimal friction. If you're using tools like Claude, ChatGPT, or Perplexity, just point them at our docs and start building. ## Developer Resources Test endpoints live with your API keys. See available plugins that expand the capabilities of Novac Financial products. See available SDKs that expand how you build with Novac. # Purchase Airtime Source: https://developer.novacpayment.com/docs/make-payment/bills/purchase-airtime Learn how to fetch airtime providers, check wallet balance, and purchase airtime. ## Overview The Airtime Purchase API allows you to buy airtime for different network providers through Novac Payment’s Bills API. Before making a purchase, you can retrieve available airtime providers, check your account balance, and confirm transaction details after completion. Use the correct `serviceId` for each network provider when making a purchase request. *** ## Get Balance Use this endpoint to check your current Novac Payment wallet balance before initiating a transaction. Provide the `currency code` for example `NGN` as part of the URL path. ```bash Request theme={null} curl --request GET \ --url https://integrations.novacpayment.com/api/v1/External/balance/{currency code} \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json Response theme={null} { "code": 200, "status": "success", "message": "Successful", "data": { "success": true, "message": "Balance Fetched Successfully", "data": { "currency": "NGN", "balance": 92840.98 } } } ``` This helps ensure you have sufficient funds before performing an airtime purchase. *** ## Purchase Airtime To purchase airtime, [retrieve the service provider here](/docs/make-payment/bills/retrieve-bills-service-providers). Once you’ve identified the desired provider and confirmed your balance, send a POST request to this endpoint `api/v1/BillsPayment/initiateairtimepurchase` to initiate an airtime purchase for the specified phone number. Novac uses a reference to track transactions, so it's important to include it; if you don't, we will generate one. ```bash expandable Request theme={null} curl --request POST \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/initiateairtimepurchase \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data ' { "serviceId": "A01E", "amount": 3500, "phoneNumber": "09011111222", "reference": "" } ' ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Your transaction is in progress.", "data": { "status": "pending", "message": "Your transaction is in progress.", "reference": "reference", "amount": 3500, "fee": 0.00. "Domain": “test” } } ``` If successful, the response confirms the transaction status and generated reference for tracking purposes. *** ## Transaction Details Use this endpoint to check the status or details of a completed or pending airtime purchase using its reference. This is especially useful for confirming delivery or updating transaction status in your system. ```bash expandable Request theme={null} curl --request GET \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/details?reference=string \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Successful", "data": { "reference": "string", "status": "successful | pending | failed", "amount": 3500.00, "fee": 0.00, "recipient": "09011111222", "ipAddress": "1.1.1.1", "domain": "test", "billsProviderCode": "A01E", "billsProviderType": "airtime", "processingResponseCode": "00", "processingResponseMessage": "Successful", "transactionMetaData": "{}", "date": "13/10/2025 21:01" } } ``` A successful response shows the full transaction metadata including the reference, amount, recipient, and transaction status. # Purchase Data Source: https://developer.novacpayment.com/docs/make-payment/bills/purchase-data-bundle Learn how to fetch data plans and purchase mobile data bundles. ## Overview The Data Purchase API allows you to fetch available data plans for a specific network provider and complete a data purchase for a customer. To begin, retrieve the list of available plans using the **Get Data Plans** endpoint. Once the customer selects a preferred plan, you can complete the purchase using the **Purchase Data** endpoint. Each mobile network provider has a unique `serviceId`. Always pass the correct one to ensure successful transactions. ## Get Data Plans Use this endpoint `api/v1/BillsPayment/dataplans?serviceId=string` to retrieve all available data plans for a specific network provider. Don't forget to retrieve the service providers for data purchase [here](/docs/make-payment/bills/retrieve-bills-service-providers) You’ll need to include the provider’s `serviceId` in your query parameters. ```bash Request theme={null} curl --request GET \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/dataplans?serviceId=string\ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Successful", "data": { "serviceId": "D04D", "dataPlans": [ { "amount": 100, "databundle": "110MB", "productId": "MTN-110MB-11", "validity": "1 Day" }, { "amount": 200, "databundle": "230MB", "productId": "MTN-200MB-2", "validity": "1 Day" } ], "isSuccessful": true, "message": "Successful", "processingProvider": "" } } ``` The response includes a list of available plans with their amount, bundle size, and validity period. Each plan also includes a `productId`, which is required for completing the purchase. ## Purchase Data After retrieving the available data plans, use this endpoint to purchase a selected plan for a customer. You’ll need to include the `serviceId`, `productId`, `amount`, and the customer’s `phoneNumber`. If you don’t provide a `reference`, Novac Payment will automatically generate one for you. Novac uses a reference to track transactions, so it's important to include it; if you don't, we will generate one. ```bash expandable Request theme={null} curl --request POST \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/initiatedatapurchase \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "serviceId":"D04D", "productId":"MTN-200MB-2", "amount": 200, "phoneNumber":"09011111222", "reference": "" }' ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Your transaction is in progress.", "data": { "status": "pending", "message": "Your transaction is in progress.", "reference": "reference", "amount": 200, "fee": 0.00. "Domain": “test” } } ``` A successful request returns the transaction status and reference details. You can track the transaction using the reference or display a “Transaction in progress” message to your customer while awaiting confirmation. # Purchase Electricity Source: https://developer.novacpayment.com/docs/make-payment/bills/purchase-electricity Learn how to validate and pay for electricity bills. ## Overview The Electricity Bills API allows you to validate a customer’s meter number and complete an electricity purchase across supported service providers. Before initiating a purchase, you must first validate the customer’s meter number using the validate meter number endpoint. Once validated, you can proceed to purchase electricity using the generated details. Ensure your integration uses the correct `serviceId` for the electricity provider you intend to process payments for. ## Validate Meter Number Use this endpoint to verify a customer’s meter details before initiating a purchase.\ You’ll need to pass the service provider ID (`serviceId`) and the customer’s meter number as (`customerAccountId`). ```bash Request theme={null} curl --request POST \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/validatemeternumber \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "serviceId": "string", "customerAccountId": "string" }' ``` ```json Response theme={null} { "code": 200, "status": "success", "message": "Successful", "data": { "statusCode": "00", "statusDescription": "Successful", "detail": { "name": "Test.", "address": "test", "meterNumber": "1234567890", "accountId": "1234567890", "providerRef": "1234567890", "minimumAmount": 1000 }, "isSuccessful": true, "message": "Successful", "processingProvider": "" } } ``` If the validation is successful, the API returns the customer’s name, address, and other meter details. You’ll use these details in the Purchase Electricity request. ## Purchase Electricity After successfully validating the meter number, send a POST request to this endpoint `api/v1/BillsPayment/initiateelectricitypurchase` to complete the electricity bill payment. Provide the customer’s meter information, `amount`, and `meterType` which can be "prepaid" or "postpaid". If you don’t include a `reference`. Novac uses a reference to track transactions, so it's important to include it; if you don't, we will generate one. ```bash expandable Request theme={null} curl --request POST \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/initiateelectricitypurchase \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ --data '{ "serviceId": "string", "amount": 1000, "reference": "" "customerName": "Test", "customerAddress": "Test", "customerAccountId": "1234567890", "meterType": "prepaid|postpaid" }' ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Your transaction is in progress.", "data": { "token": "string", "units": "10", "meterType": "prepaid|postpaid", "amount": 2000, "customerAccountId": "1234567890", "status": "pending", "message": "Your transaction is in progress.", "reference": "reference", "domain": "live", "fee": 100.00 } } ``` If the purchase is successful, you’ll receive details like the token, units, and transaction status. You can display the token and units to your customer or send them via SMS or email. # Retrieve Bill’s Service Providers Source: https://developer.novacpayment.com/docs/make-payment/bills/retrieve-bills-service-providers Learn how to fetch available service providers for airtime, data, or electricity purchases. To use the Bills APIs in a live or production environment, Novac Payment uses IP whitelisting to grant access.\ You’ll need to contact [support@novacpayment.com](mailto:support@novacpayment.com) to request access for your IP address. ## Overview The bills service providers API allows you to retrieve a list of all supported providers under different bill types such as **airtime**, **data**, and **electricity**. Each provider has a unique `serviceId` (or `code`) that you’ll use to initiate subsequent transactions — for example, purchasing airtime, data, or electricity tokens. Always pass the correct `type` query parameter for example, `airtime`, `data`, or `electricity` to retrieve the right provider list for your integration. *** ## Get Bill Service Providers by Type Use this endpoint to fetch all available service providers for a specified bill type.\ Each provider object includes its name, unique service code, and logo — which can be displayed to users when selecting a service to pay for. ```bash Request theme={null} curl --request GET \ --url https://integrations.novacpayment.com/api/v1/BillsPayment/providerdetailsbytype?type=airtime|data|electricity \ --header 'Authorization: ' \ --header 'Content-Type: application/json' \ ``` ```json expandable Response theme={null} { "code": 200, "status": "success", "message": "Successful", "data": { "type": "airtime", "billsPaymentProviders": [ { "name": "Airtel", "code": "A01E", "imageUrl": "https://res.cloudinary.com/dtld2ztim/image/upload/v1752065070/Airtel_upbjov.png" }, { "name": "9mobile", "code": "A02E", "imageUrl": "https://res.cloudinary.com/dtld2ztim/image/upload/v1752065069/9Mobile_eso0n0.png" } ], "isSuccessful": true, "message": "Successful", "processingProvider": "" } } ``` The `type` query parameter determines which set of providers is returned: `airtime` — returns all supported mobile network providers. `data` — returns all supported data service providers. `electricity` — returns all supported electricity distribution companies ## What’s Next? Learn how to purchase data, electricity or airtime using the follow APIs : * [Purchase Airtime](/docs/make-payment/bills/purchase-airtime) * [Purchase Data](/docs/make-payment/bills/purchase-data-bundle) * [Purchase Electricity](/docs/make-payment/bills/purchase-electricity) # Make a payout Source: https://developer.novacpayment.com/docs/make-payment/make-payout Learn how to initiate a payout request. To use the Payout APIs in a live or production environment, Novac Payment uses IP whitelisting to grant access.\ You’ll need to contact [support@novacpayment.com](mailto:support@novacpayment.com) to request access for your IP address. ## Overview The payout flow describes the complete process of sending funds from your Novac account to a customer’s settlement account.\ It ensures that every payout is validated, securely processed, and easily verifiable. To initiate a payout, your integration follows this flow: ## How payout flow works ```mermaid theme={null} sequenceDiagram participant C as Customer participant S as Your System participant N as Novac API C->>S: Initiates payout request S->>N: GET /api/v1/banks/{countryCode}
Fetch supported banks N-->>S: Returns bank list S-->>C: Display banks C->>S: Submit account number & select bank S->>N: POST /api/v1/banks/account/verify
{accountNumber, bankCode} N-->>S: Returns account owner name S-->>C: Display account name for confirmation Note over C,S: Optional: Check balance C->>S: Confirm payout S->>N: GET /api/v1/balance/{currency}
(Optional) N-->>S: Returns available balance S->>N: POST /api/v1/transfers
{amount, account, bank, ...} N->>N: Process payout N-->>S: Returns transaction reference S-->>C: Display transaction reference Note over C,S: Optional: Verify transaction C->>S: Request transaction status S->>N: GET /api/v1/transfers/{reference} N-->>S: Returns transaction status S-->>C: Display status ``` Retrieve the list of banks supported for payouts, filtered by country code. You'll need the correct bank code from this list to verify a recipient's account and to initiate a payout. Using an incorrect or unsupported bank code will cause later steps to fail. Before sending money, confirm the recipient's account number resolves to a valid, correctly named account at the selected bank. This step returns the account holder's name so you can display it back to your user for confirmation. Optionally check your available balance before initiating a payout, to confirm you have sufficient funds. This step is optional because the payout request itself will fail gracefully with an insufficient-funds error if your balance is too low. Send the actual payout request, specifying the verified recipient account, bank code, and amount. A successful call here doesn't necessarily mean the money has arrived. It means the payout has been accepted and is being processed. You'll receive a reference to track its status. Use the reference returned in the previous step to check whether the payout completed successfully, failed, or is still processing. Because payouts can take time to settle on the recipient's end, this is typically the step you'll listen for via webhook. ### Get supported payout banks based on country When a customer initiates a payout request, your system begins by fetching the list of supported banks from Novac by sending a [GET request](/api-reference/payouts/retrieve-payout-banks) to the endpoint `/api/v1/banks/{countryCode}`. You can pass NG, GH and KE as your country code, as Novac support payout on Nigeria, Ghana and Kenya. This allows you to display the available banks for the customer to select from. *** ### Verify customer settlement account After the customer selects a destination bank and enters their account number, your system should verify the account details by making a [POST request](/api-reference/payouts/verify-bank-account) to `/api/v1/banks/account/verify`. This verification confirms that the account exists and returns the account holder’s name, which can then be displayed to the customer for confirmation. Before proceeding with the payout, your system can optionally check the available balance by sending a [GET request](/api-reference/payouts/retrieve-balance) to `/api/v1/balance/{currency}` to ensure sufficient funds. *** ### Initiate a payout request Once the customer confirms the payout, your system sends a [POST request](/api-reference/payouts/initiate-transfer) to `/api/v1/transfers`, including the payout details such as the amount, bank, and account information. Novac processes the transaction and returns a unique transaction reference, which your system can display to the customer as proof of submission. Finally, to verify the payout’s completion, your system can send a [GET request](/api-reference/payouts/retrieve-bank-transaction) to `/api/v1/transfers/{reference}` using the transaction reference returned earlier. This endpoint provides the current transaction status such as "pending", "successful", or "failed" allowing your system to communicate the result back to the customer. This complete flow ensures that every payout is securely processed, verified, and transparently tracked from initiation to confirmation. # GiveWP Source: https://developer.novacpayment.com/docs/plugins/givewp Accept donations via Novac's hosted checkout in GiveWP on your WordPress site. ## Overview The Novac GiveWP plugin integrates Novac's hosted checkout system with GiveWP, allowing nonprofit organizations to accept donations securely through their WordPress donation forms. It supports multiple currencies and provides webhook-based payment verification so donation statuses are updated automatically after each transaction. *** ### Prerequisites Before you begin, ensure your environment meets the following requirements: * **WordPress** 6.0 or higher * **PHP** 7.4 or higher * **GiveWP plugin** installed and active — this plugin cannot function without it * A Novac account with API credentials from your [Novac Dashboard](https://www.app.novacpayment.com/login) ### Installation Upload the `novac-give` folder to your WordPress plugins directory `/wp-content/plugins/` In your WordPress admin panel, go to **Plugins** and activate the Novac GiveWP plugin. The Novac plugin requires GiveWP to be installed and active. If GiveWP is not running, the payment gateway will not load. Navigate to **GiveWP → Settings → Payment Gateways → Novac** to begin configuration. *** ## Configuration Once the plugin is installed and GiveWP is active, configure the gateway from the GiveWP settings panel: 1. Go to **Donations > Settings > Payment Gateways > Novac**. 2. Enter your **Novac API credentials** (public and secret keys from your Novac Dashboard). 3. Configure your **webhook settings** so Novac can notify your site when a payment completes. 4. Enable Novac for **specific donation forms** or activate it **globally** across all forms. # Magento 2 Source: https://developer.novacpayment.com/docs/plugins/magento Install and configure the Novac payment gateway module for your Magento 2 store. ## Overview The Novac Payment module is the official Magento 2 integration for Novac merchants. It adds Novac as a payment method at checkout, provides an admin configuration panel for managing API credentials, and includes webhook handlers that automatically update order statuses when payment notifications arrive from Novac. *** ### Prerequisites Before you begin, ensure your environment meets the following requirements: * **Magento 2.4+** (or a compatible 2.x release) with PHP and Composer support * Access to the **Magento CLI** (`bin/magento`) with permissions to install and enable modules * A Novac account with API keys from your [Novac Dashboard](https://dashboard.novacpayment.com) *** ## Installation There are two ways to install the module, manually by copying the module files, or via Composer if you have it packaged. ### Manual Installation Copy the module directory into your Magento installation. The [repository](https://github.com/novaccto/novac-magento) is already structured as the module root, so copy it directly to app/code/Novac/Payment From your Magento project root, run the following commands in sequence. These enable the module, apply any database schema changes, compile dependency injection, and clear the cache: ```bash theme={null} php bin/magento module:enable Novac_Payment php bin/magento setup:upgrade php bin/magento setup:di:compile php bin/magento cache:flush ``` If your store is running in production mode or you deploy static content separately, also run: ```bash theme={null} php bin/magento setup:static-content:deploy ``` ### Composer Installation This [repository](https://github.com/novaccto/novac-magento) does not include a `composer.json` package by default. To install via Composer, you can either package the module and publish it to your VCS or a private repository, or submit it to Packagist and require it using Composer as you would any other Magento package. *** ## Configuration Once the module is installed, configure it from the Magento Admin panel: **Admin > Stores > Configuration > Sales > Payment Methods > Novac** | Setting | Description | | ---------------------- | ----------------------------------------------------------------------------------- | | `Enable Novac Payment` | Enable or disable the Novac payment method at checkout | | `Title` | The label shown to customers on the checkout page | | `API Secret Key` | Your secret API key, used to sign and authenticate requests | | `API Public Key` | Your public API key used as an identifier | | `Sort Order` | Controls where Novac appears relative to other payment methods | | `Webhook URL` | Read-only field displaying the webhook endpoint to register in your Novac dashboard | # Wix Source: https://developer.novacpayment.com/docs/plugins/wix Install and configure the Novac payment plugin on your Wix store with minimal setup. ## Overview The Novac Wix plugin allows you to accept payments directly on your Wix store using Novac's secure checkout experience. This guide walks you through setting up the plugin, configuring your site, and testing your integration before going live. *** ### Prerequisites Before you begin, ensure that you have the following: * A **Novac Account**, preferably approved for live transactions * A **Wix account** with an active Premium subscription *** ## General Plugin Setup ### Turn On Developer Mode Developer Mode gives you access to Wix's code editor, which is required to install the plugin files. 1. Open your **Wix Editor**. 2. Click **Dev Mode** at the top of the screen. 3. Select **Turn on Dev Mode**. ### Add the Payment Provider Plugin With Developer Mode enabled, you can now add the Novac payment plugin to your site. 1. In the left panel, click the **\{ } Code Files** icon. 2. Under **Service Plugins**, click the **(+)** button and select **Payment**. 3. When prompted to name your plugin, enter exactly: Wix will automatically generate the following folder structure in your project: ### Add the Novac Plugin Code You need to replace the sample code in both generated files with the Novac plugin code from our GitHub repository. Start with `novac.js`: 1. Open `novac.js` in the Wix Editor. 2. Delete all existing sample code. 3. Copy and paste the code from our GitHub repository. Repeat the same steps for `novac-config.js`. Access both code files here: * [novac.js](https://github.com/Novac-Finance/novac-wix-plugin#) * [novac-config.js](https://github.com/Novac-Finance/novac-wix-plugin#) ### Add the Backend Function The backend function receives payment callbacks from Novac and processes webhooks for each transaction. Without this, your store will not be notified when a payment completes. 1. Go to the **Backend** folder in the Wix Editor. 2. Click **(+)** > **Expose Site API**. This creates an `http-functions.js` file. 3. If the file already exists, open it to edit. 4. Add the code from our [`http-functions.js`](https://github.com/Novac-Finance/novac-wix-plugin#) to the file. If your backend file already contains existing code, append the Novac callback function at the end. If it is a new file, remove the template code first, then paste in the Novac code. ### Publish Your Site Once all files are saved, click **Publish** in the top-right corner of the Wix Editor. This activates the plugin on your live site, the plugin will not work until the site is published. *** ## Site Installation ### Configure Novac in Your Wix Dashboard With the plugin files published, you can now connect Novac as a payment provider from your Wix Dashboard. 1. Go to your **Wix Dashboard**. 2. Navigate to **Settings > Accept Payments**. Novac should now appear as a payment provider. If it does not, refresh the page to clear Wix's cache. 3. Click **Connect** next to Novac. 4. Enter your `public_key`, `secret_key`, and `logo_url` to complete the configuration. # WooCommerce Source: https://developer.novacpayment.com/docs/plugins/woocommerce Install and configure the Novac payment plugin for WooCommerce with build instructions for developers. ## Overview The Novac WooCommerce plugin is the official payment gateway integration for WooCommerce stores. It enables you to accept payments directly at checkout using Novac's secure hosted checkout experience, with full support for cards, bank transfers, and mobile money. ## Prerequisites Before you begin, ensure the following tools are installed on your machine: * **Node.js** v20 or higher, required to run the build scripts * **pnpm** the package manager used for all JavaScript dependencies * **WP-CLI** used to interact with WordPress from the command line * **Webpack** bundled via `wp-scripts` to compile and optimize plugin assets *** ## Account Setup Before accepting payments, you need to connect your Novac account to the plugin: 1. Navigate to the Novac Payments settings page in your WordPress admin. 2. Enter your **API key** from the [Novac Dashboard](https://dashboard.novacpayment.com). 3. Configure your **Checkout preferences** to match your store's requirements. *** ## Build Process The plugin uses **Webpack** and **UglifyJS** as its core build tools to produce minified, production-ready JavaScript and CSS. This section is intended for developers who need to modify, debug, or reproduce the plugin build from source. ### Build Scripts The following scripts define the full build pipeline. They are run in sequence to install dependencies, minify JavaScript, generate translation files, bundle assets, and produce the final plugin zip: ```json theme={null} { "prebuild": "pnpm install && composer install", "build": "pnpm run preuglify && pnpm run uglify && composer run makepot && pnpm run build:webpack && pnpm run plugin-zip", "build:webpack": "wp-scripts build", "start": "pnpm run start:webpack", "start:webpack": "rimraf build/* && wp-scripts start", "preuglify": "rm -f $pnpm_package_config_assets_js_min", "uglify": "for f in $pnpm_package_config_assets_js_js; do file=${f%.js}; node_modules/.bin/uglifyjs $f -c -m > $file.min.js; done" } ``` **What each script does:** | Script | Description | | --------------- | --------------------------------------------------------------------------------- | | `prebuild` | Installs all JavaScript and PHP dependencies before the build starts | | `build` | Runs the full production build pipeline end to end | | `build:webpack` | Compiles and bundles assets using `wp-scripts` | | `start` | Starts the development server with file watching enabled | | `start:webpack` | Clears the build directory and starts `wp-scripts` in watch mode | | `preuglify` | Removes any previously minified JavaScript files before minification runs | | `uglify` | Minifies all JavaScript source files using UglifyJS with compression and mangling | *** ### Reproducing the Build Follow these steps to clone the repository and produce a fresh plugin zip from source: Clone the plugin source code from GitHub: ```bash theme={null} git clone https://github.com/Novac-Finance/novac-woocommerce-plugin ``` The setup script configures the local environment, including any server-side dependencies needed for the build: ```bash theme={null} /bin/setup.sh ``` Install all JavaScript dependencies defined in `package.json`: ```bash theme={null} pnpm install ``` Execute the full production build. This minifies JavaScript, compiles assets via Webpack, generates translation files, and packages everything into a plugin zip: ```bash theme={null} pnpm build ``` If you prefer not to build from source, you can download the latest prebuilt plugin zip directly from the [GitHub Releases page](https://github.com/Novac-Finance/novac-woocommerce-plugin/releases). *** ### Unminified Source Files For debugging or auditing purposes, the following unminified source files are available in the repository. These are the raw files that get processed during the build: | File | Description | | --------------------------------------------------------------------------------------------- | ----------------------------------------- | | [`assets/js/checkout.js`](https://github.com/Novac-Finance/novac-woocommerce-plugin) | Handles the frontend checkout flow | | [`assets/blocks/index.js`](https://github.com/Novac-Finance/novac-woocommerce-plugin) | Powers the WooCommerce blocks integration | | [`assets/admin/settings/index.js`](https://github.com/Novac-Finance/novac-woocommerce-plugin) | Admin settings page interface | | [`assets/editor/index.js`](https://github.com/Novac-Finance/novac-woocommerce-plugin) | Block editor (Gutenberg) integration | # WordPress Source: https://developer.novacpayment.com/docs/plugins/wordpress Install and configure the Novac payment plugin to accept payments on your WordPress site. ## Overview The Novac WordPress plugin enables you to accept payments on your WordPress site using Novac's secure payment gateway. It includes a full admin interface for managing transactions and API settings, flexible frontend options for embedding payment forms, and a robust backend integration that handles webhooks, transaction recording, and REST API communication automatically. ### Prerequisites Before you begin, ensure that you have the following: * A Novac Business Account with API keys from your [Novac Dashboard](https://www.app.novacpayment.com/login) * A WordPress site with admin access * Ability to install plugins via the WordPress admin panel or FTP ### Installation Upload the plugin folder to your WordPress plugins directory: /wp-content/plugins/ In your WordPress admin panel, go to **Plugins** and activate the Novac Payments plugin. Navigate to **Novac Payments** in the WordPress admin menu to begin configuration. *** ## Configuration ### API Keys Your API keys authenticate all communication between your WordPress site and Novac's backend. You'll need both a public and secret key from your dashboard. 1. Get your API keys from the [Novac Dashboard](https://www.app.novacpayment.com/login). 2. Go to **Novac Payments → Settings** in your WordPress admin. 3. Enter your **Public Key** and **Secret Key**. 4. Select your **Mode**, choose **Test** for development or **Live** for production. 5. Copy the generated **Webhook URL** and add it to your Novac dashboard. ### Webhook Setup The webhook URL allows Novac to send real-time payment notifications to your WordPress site, so transaction statuses are updated automatically after each payment. Configure the following URL in your Novac dashboard: [https://yoursite.com/?novac-webhook=1](https://yoursite.com/?novac-webhook=1) Replace `yoursite.com` with your actual WordPress site domain. *** ## Usage ### Using the Shortcode The `[novac_payment_form]` shortcode lets you embed a payment form on any page, post, or widget area. There are three ways to use it depending on your needs. 1. **Basic form**: lets the customer enter their own amount: \[novac\_payment\_form] 2. **Fixed amount form**: pre-sets the amount and describes what the payment is for ``` [ novac_payment_form amount="1000" currency="NGN" description="Product Purchase" button_text="Pay Now" ] ``` 3. **Fully customized form**: applies custom brand colors to the form container, button, and text ``` [ novac_payment_form amount="1000" currency="NGN" description="Product Purchase" button_text="Pay Now" text_color="#F4F4F5" container_color="#111827" button_color="#EAB308" button_text_color="#111827" ] ``` #### Shortcode Parameters | Parameter | Description | Default | | ------------------- | --------------------------------------------------------------------- | --------- | | `amount` | Fixed payment amount. Leave empty to let the customer enter their own | — | | `currency` | Currency code | `NGN` | | `description` | Payment description shown on the form | `Payment` | | `button_text` | Label on the payment button | `Pay Now` | | `text_color` | Color of form text | `#111111` | | `container_color` | Background color of the form container | — | | `button_color` | Background color of the payment button | — | | `button_text_color` | Color of the text on the payment button | — | *** ### Using the Gutenberg Block If you use the WordPress block editor, you can add the payment form as a block instead of a shortcode. 1. In the block editor, click the **(+)** button to add a new block. 2. Search for **Novac Payment Form**. 3. Add the block to your page. 4. Use the **block inspector panel** on the right to configure: * Fixed amount (optional) * Currency * Payment description * Button text *** ### Managing Transactions All payments processed through the plugin are recorded automatically and accessible from the WordPress admin. 1. Go to **Novac Payments → Transactions**. 2. Each transaction entry shows: * Transaction reference * Customer information * Amount and currency * Payment status * Date and time 3. Use the **search bar** to look up transactions by email, name, or reference. 4. Use the **status filter** to narrow results by Successful, Pending, or Failed. 5. Navigate large transaction lists using **pagination**. *** ## Payment Flow Understanding the full payment lifecycle helps with debugging and verifying your integration. ```mermaid theme={null} sequenceDiagram actor Customer participant Form as Payment Form participant WP as WordPress participant Novac as Novac API participant Webhook as Webhook Handler Customer->>Form: Fills out payment form Form->>WP: Submits via AJAX (no page reload) WP->>Novac: Initiates checkout session Novac-->>WP: Returns checkout session URL WP-->>Customer: Redirects to Novac payment page Customer->>Novac: Completes payment Novac->>Webhook: Sends webhook notification Webhook->>WP: Verifies & updates transaction status WP-->>Customer: Redirects back with payment result ``` *** ## API Reference ### Settings Endpoints Use these REST API endpoints to read or update your plugin settings programmatically. | Method | Endpoint | Description | | ------ | ---------------------------- | -------------------------------- | | `GET` | `/wp-json/novac/v1/settings` | Retrieve current plugin settings | | `POST` | `/wp-json/novac/v1/settings` | Update plugin settings | ### Transaction Endpoints | Method | Endpoint | Description | | ------ | ------------------------------------- | ------------------------------------------------------------ | | `GET` | `/wp-json/novac/v1/transactions` | List all transactions with pagination, search, and filtering | | `GET` | `/wp-json/novac/v1/transactions/{id}` | Retrieve a single transaction by ID | *** ## Advanced Usage ### Database The plugin automatically creates a `wp_novac_transactions` table in your WordPress database when activated. This table stores the following for each transaction: * Transaction reference * Customer information (email, name) * Amount and currency * Payment status and method * Metadata and timestamps ### Roles & Permissions The plugin introduces custom capabilities for fine-grained access control, and creates two dedicated roles so you can grant team members access without giving them full admin rights. **Custom capabilities:** | Capability | Description | | --------------------------- | --------------------------------------------------- | | `novac_manage_settings` | Configure API keys and plugin settings | | `novac_view_transactions` | View the transactions list | | `novac_refund_transactions` | Process refunds *(reserved for future use)* | | `novac_export_transactions` | Export transaction data *(reserved for future use)* | **Custom roles:** | Role | Access | | ------------------------- | ---------------------------------- | | **Novac Payment Manager** | Full access to all plugin features | | **Novac Finance Analyst** | View and export transactions only | Administrators automatically receive all capabilities. *** ## Development ### Building Assets The plugin's admin interface and Gutenberg block are built from source using Node.js and Composer. Run the following commands from the plugin root to compile all assets: ```bash theme={null} composer install npm install npm run build ``` This produces compiled output in two locations: * Admin React app → `includes/admin/build/` * Gutenberg block → `includes/blocks/build/` ### File Structure # Android Source: https://developer.novacpayment.com/docs/sdk/android Install and use Novac Android SDK with minimal setup config. ## Overview Novac Android SDKs enable Android developers to extend Novac's capabilities when building mobile platforms with minimal setup. The Novac Android SDK provides a seamless checkout experience with a customizable UI, native Jetpack Compose and Views support, and robust error handling—all with a simple setup. *** ### Prerequisites Before you begin, ensure that you’ve completed the following steps: * [Obtain your API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls. * Android project with Gradle build system * Minimum SDK version compatible with Jetpack Compose or AppCompat ### Installation In your **project-level** `build.gradle`, add the JitPack repository: ```groovy theme={null} allprojects { repositories { maven { url 'https://jitpack.io' } } } ``` In your app-level `build.gradle`, add the following dependency. ```groovy theme={null} dependencies { implementation 'com.github.novacpayment:novac-payment-android-sdk:v0.2.6' } ``` *** ## Initialize the SDK Initialize the SDK in your `Application` class or main `Activity`. You will need your `merchantId` and `apiKey` from your Novac dashboard, and you must specify the activities that will handle payment success and failure outcomes. ```kotlin theme={null} import com.novacpaymen.paywithnovac_android_skd.NovacCheckout import com.novacpaymen.paywithnovac_android_skd.CheckoutConfig class MainActivity : ComponentActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) NovacCheckout.initialize( CheckoutConfig( merchantId = "your-merchant-id", baseUrl = "https://api.novacpayment.com", apiKey = "your-api-key", enableLogging = false, successActivityClass = SuccessActivity::class.java, failureActivityClass = FailureActivity::class.java ) ) } } ``` ### Checkout Config Parameters | Parameter | Type | Required | Description | | ---------------------- | --------- | -------- | ---------------------------------------- | | `merchantId` | `String` | `true` | Your merchant ID from Novac | | `baseUrl` | `String` | `true` | API base URL | | `apiKey` | `String` | `true` | Your API key from Novac | | `enableLogging` | `Boolean` | `false` | Enable debug logging | | `successActivityClass` | `Class` | `true` | Activity to launch on successful payment | | `failureActivityClass` | `Class` | `true` | Activity to launch on failed payment | *** ### Create Result Activities You need two activities to handle the payment outcomes: one for success and one for failure. The SDK passes transaction details to each via the intent. ### `SuccessActivity.kt` ```kotlin theme={null} class SuccessActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_success) val transactionReference = intent.getStringExtra("transaction_reference") val amount = intent.getDoubleExtra("amount", 0.0) val currency = intent.getStringExtra("currency") val paymentStatus = intent.getStringExtra("payment_status") // Update your UI, confirm the order, etc. } } ``` ### `FailureActivity.kt` ```kotlin theme={null} class FailureActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) setContentView(R.layout.activity_failure) val transactionReference = intent.getStringExtra("transaction_reference") val amount = intent.getDoubleExtra("amount", 0.0) val currency = intent.getStringExtra("currency") val errorMessage = intent.getStringExtra("error_message") val errorCode = intent.getStringExtra("error_code") // Show error message, offer retry option, etc. } } ``` *** ### Launch the Checkout Flow Once the SDK is initialized, launching a payment is a single method call: ```kotlin theme={null} val sdk = NovacCheckout.getInstance() sdk.launchCheckoutFlow( context = this, transactionReference = UUID.randomUUID().toString(), amount = 120.0, currency = "NGN", customerEmail = "customer@example.com", customerFirstName = "John", customerLastName = "Doe", customerPhone = "1234567890" ) ``` *** ## Advanced Usage ### Customizing the Checkout UI You can personalize the checkout modal with your brand logo, a payment description, and a custom title: ```kotlin theme={null} val customizationData = CheckoutCustomizationData( logoUrl = "https://your-logo-url.com/logo.png", paymentDescription = "Payment for Order #123", checkoutModalTitle = "Complete Your Payment" ) sdk.launchCheckoutFlow( context = this, transactionReference = UUID.randomUUID().toString(), amount = 120.0, currency = "NGN", customerEmail = "customer@example.com", customerFirstName = "John", customerLastName = "Doe", customerPhone = "1234567890", customizationData = customizationData ) ``` ### Manual Checkout Initiation For greater control over the checkout flow — for example, to retrieve the payment URL and handle redirection yourself — use `initiateCheckout` directly within a coroutine: ```kotlin theme={null} val sdk = NovacCheckout.getInstance() val customerData = CheckoutCustomerData( email = "customer@example.com", firstName = "John", lastName = "Doe", phoneNumber = "1234567890" ) val customizationData = CheckoutCustomizationData( logoUrl = "https://your-logo-url.com/logo.png", paymentDescription = "Payment for Order #123", checkoutModalTitle = "Complete Your Payment" ) coroutineScope.launch { when (val result = sdk.initiateCheckout( transactionReference = UUID.randomUUID().toString(), amount = 120.0, currency = "NGN", checkoutCustomerData = customerData, checkoutCustomizationData = customizationData )) { is Result.Success -> { val paymentUrl = result.value.data?.paymentRedirectUrl // Redirect the user to the payment URL } is Result.Failure -> { Log.e("Checkout", "Payment initiation failed", result.exception) } } } ``` Keep the following in mind when testing: * Always use a unique `reference` value for each transaction, duplicate references will be rejected. * Start with small test amounts (₦100) to validate your integration before going live. * Check your sandbox dashboard to confirm transaction results and inspect any errors. # Flutter Source: https://developer.novacpayment.com/docs/sdk/flutter Install and use the Novac Flutter plugin to accept payments seamlessly in your Flutter apps. ## Overview The Novac Flutter plugin is the official plugin for the Novac Payment Gateway. It enables you to accept payments directly within your Flutter apps with support for cards, bank transfers, and mobile money — all with a customizable, secure checkout UI. *** ### Prerequisites Before you begin, ensure that you've completed the following steps: * [Obtain your API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls. * A Flutter project with a minimum iOS version of **12.0** and minimum Android SDK version of **21** * A Novac account with dashboard access ### Installation Add the plugin to your `pubspec.yaml` file: ```yaml theme={null} dependencies: novac_payment_plugin: ^1.0.0 ``` Run the following command in your terminal to fetch the package: ```bash theme={null} flutter pub get ``` *** ## Platform Setup Because the SDK uses a webview for checkout, both iOS and Android need a URL scheme registered so that users are redirected back to your app after payment completes. ### iOS Add the following to your `ios/Runner/Info.plist`. This registers a custom URL scheme that the payment gateway uses to deep link back into your app: ```xml theme={null} CFBundleURLTypes CFBundleURLSchemes yourappscheme ``` ### Android Add the following intent filter inside the relevant `` block in your `android/app/src/main/AndroidManifest.xml`. This tells Android to route the payment redirect back to your app: ```xml theme={null} ``` Replace `yourappscheme` on both platforms with the same unique scheme. This value should also match whatever redirect URL is configured in your Novac dashboard. *** ## Initialize the SDK Before launching any payment, call `NovacPaymentPlugin.initialize()` once. Typically, at app startup or before your first checkout. This authenticates your app with Novac and optionally applies a custom theme to the checkout UI. ```dart theme={null} import 'package:novac_payment_plugin/novac_payment_plugin.dart'; await NovacPaymentPlugin.initialize( apiKey: 'your_api_key', primaryColor: '#007AFF', // Optional: Customize theme backgroundColor: '#FFFFFF', // Optional buttonTextColor: '#FFFFFF', // Optional ); ``` *** ### Launch the Checkout Flow Once the SDK is initialized, call `launchCheckout()` to start a payment. The method is asynchronous and returns a `PaymentResult` object you can inspect to determine what happened. ```dart theme={null} final result = await NovacPaymentPlugin.launchCheckout( amount: 5000, // Amount in smallest currency unit currency: 'NGN', redirectUrl: 'https://yourapp.com/payment-complete', customerData: CustomerData( email: 'customer@example.com', firstName: 'John', lastName: 'Doe', // Optional phoneNumber: '+2348012345678', // Optional ), customizationData: CustomizationData( logoUrl: 'https://yourcompany.com/logo.png', paymentDescription: 'Payment for Order #12345', checkoutModalTitle: 'Complete Payment', ), transactionReference: 'unique-reference-123', // Optional: Auto-generated if not provided ); // Handle the result if (result.isSuccess) { print('Payment successful! Transaction ID: ${result.transactionId}'); } else if (result.isCancelled) { print('Payment cancelled by user'); } else { print('Payment failed: ${result.errorMessage}'); } ``` **Customer's Data** This controls customer information. Customer's email address Customer's first name Customer's last name Customer's phone number **Customer's Data** This Controls the visual appearance and copy shown on the checkout modal. URL to your company logo Description displayed on the checkout screen Title shown at the top of the checkout modal The object returned by `launchCheckout()`. Check its properties to determine the outcome of the payment. Whether the payment completed successfully Whether the user dismissed the checkout without paying Transaction ID, present if successful The transaction reference used for the payment Human-readable error message if the payment failed Error code for programmatic handling if the payment failed *** ### Verify a Payment After a successful checkout, you can independently verify the transaction status on your backend or client using `verifyPayment()`. Pass the transaction reference returned from the checkout result: ```dart theme={null} final verification = await NovacPaymentPlugin.verifyPayment('transaction-reference'); print('Status: ${verification.status}'); print('Amount: ${verification.amount}'); print('Currency: ${verification.currency}'); ``` The object returned by `verifyPayment()`. Use this to confirm a transaction's final status. Whether the payment completed successfully The transaction reference used for the payment The transaction amount transaction currency Error message if verification failed *** ### Error Handling Wrap your checkout call in a `try/catch` block to handle both expected payment outcomes (failure, cancellation) and unexpected runtime errors gracefully: ```dart theme={null} try { final result = await NovacPaymentPlugin.launchCheckout(...); if (result.isSuccess) { // Handle success } else if (result.isCancelled) { // Handle cancellation } else { // Handle failure print('Error: ${result.errorCode} - ${result.errorMessage}'); } } catch (e) { // Handle unexpected errors print('Unexpected error: $e'); } ``` Keep the following in mind when testing: * Always use a unique `reference` value for each transaction, duplicate references will be rejected. * Start with small test amounts (₦100) to validate your integration before going live. * Check your sandbox dashboard to confirm transaction results and inspect any errors. # iOS Source: https://developer.novacpayment.com/docs/sdk/ios Install and use the Novac iOS SDK with minimal setup config. ## Overview The Novac iOS SDK allows you to easily collect payments within your iOS apps using Novac's secure checkout experience. It provides APIs for payment initialization and verification, along with a built-in UI that handles the full checkout flow for you. *** ### Prerequisites Before you begin, ensure that you've completed the following steps: * [Obtain your API keys](/docs/getting-started/obtain-api-keys): required for making authenticated API calls. * Xcode project with Swift Package Manager support * A Novac account with dashboard access ### Installation In Xcode, navigate to **File → Add Packages…**, select **Add Local…**, and choose your SDK folder (`Novac/`). Then add **Novac** to your app target's dependencies. If your SDK is hosted on GitHub, you can add it directly via URL instead of a local folder: ```swift theme={null} .package(url: "https://github.com/yourusername/Novac.git", from: "1.0.0") ``` *** ## Initialize the SDK Before launching any payment, you need to set up two things: an `APIClient` (which authenticates your requests using your API key) and a `PaymentCoordinator` (which manages the entire checkout flow). Both are configured inside your `ViewController`. You'll need your `apiKey` from the Novac dashboard. The optional `CustomTheme` lets you style the checkout UI to match your brand. ```swift theme={null} import UIKit import Novac class ViewController: UIViewController, PaymentDelegate { var coordinator: PaymentCoordinator! override func viewDidLoad() { super.viewDidLoad() let apiClient = APIClient(apiKey: "YOUR_TEST_API_KEY") let theme = CustomTheme(primaryColor: .systemBlue, buttonTextColor: .white) coordinator = PaymentCoordinator( apiClient: apiClient, theme: theme, delegate: self ) } } ``` *** ### Launch the Checkout Flow Once the coordinator is set up, you can trigger a payment from any user action — in this case, a button tap. You create a `PaymentRequest` with the transaction details and pass it to the coordinator, which handles the rest. ```swift theme={null} @IBAction func startPayment(_ sender: UIButton) { let payment = PaymentRequest( amount: 5000, currency: "NGN", email: "test@example.com", reference: UUID().uuidString ) coordinator.start(presentingViewController: self, request: payment) } ``` *** ### Handle Payment Outcomes The `PaymentDelegate` protocol defines three callback methods that the SDK calls depending on what happens during checkout. Implement all three in your `ViewController` to handle every possible outcome. ```swift theme={null} func paymentDidSucceed(transactionId: String) { print("Payment succeeded with ID: \(transactionId)") // Update your UI, confirm the order, etc. } func paymentDidFail(error: Error) { print("Payment failed: \(error.localizedDescription)") // Show error message, offer retry option, etc. } func paymentDidCancel() { print("Payment cancelled by user.") // Handle cancellation gracefully } ``` *** ### Configure Redirect URL After a user completes checkout in the SDK's webview, the payment gateway redirects them back to your app using a URL scheme. You need to register this scheme in your `Info.plist` so iOS knows to route that redirect back to your app. ```xml theme={null} CFBundleURLTypes CFBundleURLSchemes exampleapp ``` Replace `exampleapp` with your own unique scheme. This value must match whatever redirect URL is configured in your Novac dashboard. ## Advanced Usage Ensure you use your Novac test key during development. Keep the following in mind when testing: * Always use a unique `reference` value for each transaction, duplicate references will be rejected. * Start with small test amounts (₦100) to validate your integration before going live. * Check your sandbox dashboard to confirm transaction results and inspect any errors. # Changelog Source: https://developer.novacpayment.com/update Product updates and announcements Introduced **NGN Card Recurring Payment** via payment links for subscription and repeat billing use cases. This release includes: * New API and documentation for creating recurring payment links for NGN card transactions. Merchants can configure the frequency **daily**, **weekly**, or **monthly** and customers are charged automatically on the defined schedule. * New documentation covering: * How NGN card recurring billing works and when to use it over card tokenisation. See [NGN Card Recurring Billing](/docs/accept-payment/manage-payment/ngn-recurring-billing) for the full flow. * Frequency options available when setting up a recurring payment link * The distinction between NGN card recurring billing (payment link-based) and USD card recurring billing (tokenisation-based) Introduced **two integration methods for Direct Card Charge** for custom checkout integrations. Introduced **KES support for Mobile Money payments**. This release includes: * A new API for initiating a direct card charge **without card encryption**, giving merchants two ways to initialize a charge. Previously, only the encrypted-card method was supported; you can now use either approach depending on your integration needs. See [Direct Card Charge](/docs/accept-payment/accept-payment-with-direct-card-charge) for both methods. * New documentation covering * The updated API flow and payment scenarios for initiating a charge on NGN cards * Mobile Money checkout collection is now available for Kenya shillings (KES), in addition to GHS. Customers can pay via M-Pesa, Airtel Money, or T-Kash. * Merchants can now set `currency` to `KES` when creating a MoMo checkout. See [Create Checkout for Mobile Money Payments](/docs/accept-payment/checkout/create-checkout-for-mobile-money-payment) for the full flow. Introduced **OPay and Palmpay API** for custom checkout integrations, New API for retrieving balance report. This release includes: * New API for retrieving account balance report. This allows merchants to get chronological data of money movement in their account. Go to [account balance report](/docs/accounts/fetch-balance-report) * Support for **Custom checkout Palmpay and Opay integration**. customers to the `paymentRedirectUrl`. * New API field addition when creating a checkout payment `allowedPaymentOptions`, This enables merchant to control a single transaction payment method. [Go to payment preferences](/docs/getting-started/payment-preference) to learn more. * New endpoints for merchants building a **custom checkout experience**: * Redirect customer to complete payment on Opay or Palmpay gateway via Novac * New documentation covering: * Completing payment with [Opay or Palmpay integrations](/docs/accept-payment/complete-payment/custom-checkout#opay-integration) via the custom checkout page * In-depth guide on using Novac [plugins](/docs/plugins/wordpress) and [SDKs](/docs/sdk/android) such as Magento, Wix, Wordpress, flutter and android. * Platform update for adding [multiple sub-business](/docs/getting-started/create-merchant-account) accounts under a business account. * Addition of different [use case cookbook](/use-case/overview) on how businesses should use Novac to receive payment across Digital product and Marketplace. * Addition of [Glossary page](/docs/introduction/glossary) to help understand terminology used across the documentation for agent and human readers Introduced **[Mobile Money (MoMo) payment collection](/docs/accept-payment/checkout/create-checkout-for-mobile-money-payment)** for Ghana cedis (GHS). This release includes: * Support for **MTN Ghana** and **Telecel Ghana** as MoMo providers. * Ability to collect GHS payments via the **Novac hosted checkout** by redirecting customers to the `paymentRedirectUrl`. * New endpoints for merchants building a **custom MoMo checkout experience**: * Fetch supported MoMo providers * Initiate a MoMo payment using a checkout reference * New documentation covering: * Creating a MoMo checkout payment * Completing payment via the hosted checkout page * Building a custom MoMo checkout flow Mobile money collection is currently available for **GHS transactions only**. Introduced **[Split Settlement (Split Payment)](/docs/accept-payment/split-payment/setup-primary-settlement-account)** support across the API and documentation. This release includes: * Ability to **configure a primary settlement account** via the dashboard (Novac wallet or bank account). * Support for creating **sub-settlement accounts via API** for automated fund distribution. * New endpoints to: * Create split configurations * Retrieve existing split accounts * Update split allocation rules * Support for **flat and percentage-based split types**. * Ability to **initiate transactions using preconfigured splits** or override split logic per transaction. * Improved documentation covering: * Split architecture (parent-child model) * Transaction flow and settlement behavior * Real-world integration examples This makes it easier to automate revenue sharing, vendor payouts, and internal fund distribution directly within your payment flow. Added documentation improvement. Released a new version of the payment documentation, now with 100% more comprehensive explanation. # Digital Services Source: https://developer.novacpayment.com/use-case/accepting-payments-for-digital-services Learn how to collect one-time payments for digital products, top-ups, and instant-access services using Novac Payment Links and the Checkout API. # Overview Digital services are downloadable products, course access, API credits, airtime top-ups, gift cards, or any content unlocked immediately after payment. They share a common requirement i.e, payment must be confirmed instantly before access is granted. Novac is well-suited for this. You can use **Payment Links** for zero-code collection, the **Checkout API** for custom flows, or the **Bills API** for utility and airtime purchases all backed by real-time webhook notifications. *** ## Common Digital Service Scenarios | Scenario | Recommended Integration | | -------------------------------- | -------------------------------------- | | Sell a course or ebook | Payment Link or Checkout API | | Top up API credits in-app | Checkout API with prebuilt checkout | | Sell gift cards or voucher codes | Checkout API + webhook to deliver code | | Purchase airtime or data bundles | Bills API (Airtime / Data) | | Pay for electricity | Bills API (Electricity) | | Accept donations | Payment Link with open amount | *** ## Prerequisites * [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 server-side operations * A **webhookURL** to receive payment confirmation before granting access * A **callbackURL** to redirect customers after payment completes *** ## Payment Links (No-Code) Payment Links are the fastest way to start collecting payments for digital products. Create a link from the Novac dashboard, share it anywhere, social media, email, WhatsApp and customers can pay immediately. Best for Content creators, course sellers, freelancers, donations, flexible-amount payments. ### Create a Payment Link from the Dashboard Sign in at [app.novacpayment.com](https://app.novacpayment.com). Go to **Payments > Payment Links** in the sidebar and click **New Payment Link**. Enter your product name, amount (leave blank for open/flexible amounts), and description. Leaving the **Amount** field empty allows customers to enter any amount, ideal for donations and pay-what-you-want products. Once created, Novac generates a shareable URL and an **NQR code** that customers can scan to pay. [Full guide → Create a Payment Link](/docs/accept-payment/accept-payment-with-payment-links) *** ## Checkout API (Programmatic) For digital services that require tracking who paid and granting access automatically, initiate checkouts via the API. This gives you a unique `transactionReference` per purchase, which you verify before delivering the digital product. Best for SaaS platforms, in-app purchases, credit top-ups, any service that needs per-customer tracking. ### Initiate a Checkout ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/checkout \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 3500, "currency": "NGN", "email": "user@example.com", "reference": "DIGITAL-PURCHASE-00101", "callbackUrl": "https://yourapp.com/payment/callback", "redirectUrl": "https://yourapp.com/library" }' ``` Redirect the customer to the `checkoutUrl` returned in the response. ### Verify Payment Before Granting Access When the customer returns to your `callbackURL`, verify the transaction server-side before unlocking access. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/checkout/DIGITAL-PURCHASE-00101/verify \ --header 'Authorization: Bearer ' ``` ```json Response (excerpt) theme={null} { "status": true, "data": { "status": "successful", "transactionReference": "DIGITAL-PURCHASE-00101", "amount": 3500, "currency": "NGN", "customer": { "email": "user@example.com", "name": "Fatima Bello" } } } ``` Only unlock the digital product, download link, or access key when `data.status === "successful"`. Do not rely on the `status` query parameter in the callback URL. Always call the Verify API from your server before granting access. [Full guide > Verify a Transaction](/docs/accept-payment/manage-payment/verify-transaction) *** ## Bills API (Utility Purchases) For platforms that facilitate airtime top-ups, mobile data purchases, or electricity payments, Novac's Bills API handles the full flow — from fetching available providers to completing the purchase. **Best for:** Fintech apps, super-apps, agent banking platforms. ### Purchase Airtime ```bash theme={null} # 1. Fetch available airtime providers curl --request GET \ --url https://api.novacpayment.com/api/v1/bills/providers?type=airtime \ --header 'Authorization: Bearer ' # 2. Purchase airtime curl --request POST \ --url https://api.novacpayment.com/api/v1/bills/airtime \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "provider": "MTN", "phone": "08012345678", "amount": 1000, "reference": "AIRTIME-00202" }' ``` [Full guide → Purchase Airtime](/docs/make-payment/bills/purchase-airtime) ### Purchase Electricity ```bash theme={null} # Validate meter number first curl --request POST \ --url https://api.novacpayment.com/api/v1/bills/electricity/validate \ --header 'Authorization: Bearer ' \ --data '{ "meterNumber": "12345678901", "provider": "IKEDC" }' ``` [Full guide → Purchase Electricity](/docs/make-payment/bills/purchase-electricity) *** ## Real-Time Notifications via Webhook For digital services, webhooks are critical — they let your system act on payment outcomes immediately, even if the customer closes the browser before being redirected. ```json Webhook Payload (successful purchase) theme={null} { "notify": "transaction", "notifyType": "successful", "data": { "transactionReference": "DIGITAL-PURCHASE-00101", "amount": 3500, "status": "successful", "customer": { "email": "user@example.com", "name": "Fatima Bello" } } } ``` On receipt of a `notifyType: "successful"` event: 1. Verify the transaction via the API (do not skip this step). 2. Deliver the digital product, send the download link, activate the account, issue the voucher code. 3. Respond to Novac's webhook request with `HTTP 200 OK`. [Full guide → Webhooks](/docs/api-basics/webhooks) *** ## What's Next? * **Payment Links** - [Create shareable payment links](/docs/accept-payment/accept-payment-with-payment-links) for products and services, no code required. * **Prebuilt Checkout** - Use Novac's [hosted checkout](/docs/accept-payment/complete-payment/prebuilt-checkout) for fast, reliable payment collection. * **Purchase Airtime & Data** - Integrate mobile top-up and [data bundle purchases](/docs/make-payment/bills/purchase-airtime) via the Bills API. # Subscription Services Source: https://developer.novacpayment.com/use-case/accepting-payments-for-subscription-based-services Learn how to save customer cards and charge them automatically on a recurring schedule using Novac's card tokenisation and recurring billing APIs. # Overview Subscription businesses such as SaaS products, membership platforms, content services need to charge customers on a regular schedule without asking them to re-enter payment details each time. Novac supports this through **card tokenisation** on the customer's first payment, Novac securely saves their card and returns a token. All future charges use that token, no manual input, no interrupted billing cycles. *** ## How It Works ```mermaid theme={null} sequenceDiagram participant C as Customer participant S as Your Server participant N as Novac Note over C,N: First payment — card details captured and tokenised C->>S: Subscribes and enters card details S->>N: POST /checkout (initiates session) N-->>C: Hosted or custom checkout C->>N: Completes payment N-->>S: Webhook: notifyType = "successful" S->>N: GET /checkout/{ref}/verify N-->>S: Returns transaction + card.token S->>S: Stores card.token against customer Note over C,N: Subsequent billing cycles — no customer action required S->>N: POST /tokenized-card-charge (using stored token) N-->>S: Payment processed N-->>S: Webhook: notifyType = "successful" or "failed" ``` *** ### Prerequisites * [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 initiation, Secret key for tokenised charges * A **webhookURL** registered in your Novac dashboard for payment status notifications * A database field to store each customer's `card.token` *** ### Capture and Tokenise the Card On signup or plan activation, initiate a standard checkout. After payment is completed and verified, the transaction response includes a `card.token` that represents the customer's saved card. #### Create a Checkout Session ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/checkout \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 5000, "currency": "NGN", "email": "subscriber@example.com", "reference": "SUB-INITIAL-00789", "callbackUrl": "https://yourapp.com/payment/callback", "redirectUrl": "https://yourapp.com/dashboard" }' ``` Redirect the customer to the returned `checkoutUrl` to complete payment. #### Verify the Transaction and Extract the Token After the customer pays and is redirected to your `callbackURL`, verify the transaction server-side: ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/checkout/SUB-INITIAL-00789/verify \ --header 'Authorization: Bearer ' ``` ```json Response (excerpt) theme={null} { "status": true, "data": { "status": "successful", "transactionReference": "SUB-INITIAL-00789", "amount": 5000, "card": { "first6Digits": "539983", "last4Digits": "8381", "issuer": "Access Bank", "type": "mastercard", "token": "tok_abc123xyz789" }, "customer": { "email": "subscriber@example.com", "name": "Emeka Nwosu" } } } ``` Never store raw card numbers, CVV, or PINs on your servers. Store only the `card.token` value returned by Novac. Save `card.token` in your database linked to the customer's account. This token is what you'll use for all future billing cycles. [Full guide → Verify a Transaction](/docs/accept-payment/manage-payment/verify-transaction) *** ### Subsequent Billing - Charge the Saved Card When a subscription renewal is due (daily, weekly, monthly), charge the customer's saved card directly — no checkout page needed, no customer action required. ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/tokenized-card-charge \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "token": "tok_abc123xyz789", "currency": "NGN", "amount": "5000", "email": "subscriber@example.com", "firstName": "Emeka", "lastName": "Nwosu", "reference": "SUB-RENEWAL-00790" }' ``` The `email` value must match exactly the one used when the original checkout was created. [Full guide here, save and charge customer's card](/docs/accept-payment/manage-payment/recurring-billing) *** ### Handle Payment Outcomes via Webhook Tokenised charges happen server-to-server with no customer involvement. Your webhook endpoint is the primary way to know whether a renewal succeeded or failed. ```json Successful Renewal theme={null} { "notify": "transaction", "notifyType": "successful", "data": { "transactionReference": "SUB-RENEWAL-00790", "amount": 5000, "status": "successful", "customer": { "email": "subscriber@example.com" } } } ``` ```json Failed Renewal theme={null} { "notify": "transaction", "notifyType": "failed", "data": { "transactionReference": "SUB-RENEWAL-00790", "amount": 5000, "status": "failed", "gatewayResponseCode": "51", "customer": { "email": "subscriber@example.com" } } } ``` **Recommended handling for failed renewals:** | Scenario | Recommended Action | | ------------------ | --------------------------------------------------------- | | Insufficient funds | Retry after 24–48 hours, notify customer | | Card expired | Prompt customer to update card details via a new checkout | | Repeated failures | Suspend subscription, send dunning email | [Full guide > Webhooks](/docs/api-basics/webhooks) *** ### Updating a Customer's Card When a customer's card expires or they want to use a different card, initiate a new checkout session to capture the new card details and replace the stored token. Use the same verification flow when extracting the new `card.token` and update your database record for that customer. *** ## What's Next? * **Save and Charge Customer** - Full technical reference for [card tokenisation](/docs/accept-payment/manage-payment/recurring-billing) and tokenised charges. * **Refund a Transaction** - [Issue full or partial refunds](/docs/accept-payment/manage-payment/refund-transaction) when a subscriber cancels mid-cycle. * **Webhooks** - Set up and secure your [webhook](/docs/api-basics/webhooks) endpoint for renewal notifications. # E-Commerce Platforms Source: https://developer.novacpayment.com/use-case/accepting-payments-on-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 * [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 *** ### 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. 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 ' \ --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) 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) *** ### Handle the Callback After payment, Novac redirects the customer back to your `callbackURL` with query parameters: ```http theme={null} GET {your-callback-url}?reference=&status= ``` 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. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/checkout/ORDER-00123/verify \ --header 'Authorization: Bearer ' ``` ```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" } } } ``` 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](/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 ' \ --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. # Marketplaces Source: https://developer.novacpayment.com/use-case/accepting-payments-on-marketplaces Learn how to collect payments from buyers and automatically distribute funds to multiple vendor accounts using Novac's Split Payment feature. # Overview Marketplaces deal with a payment challenge that a standard e-commerce checkout doesn't, funds collected from a single buyer often need to be distributed to multiple parties i.e, the vendor, the platform, a logistics partner, or all three. Novac's **Split Payment** feature handles this automatically. You define the split rules once (flat or percentage-based), and every incoming payment is settled to each configured account without manual transfers. *** ## How It Works ```mermaid theme={null} sequenceDiagram participant B as Buyer participant S as Marketplace Server participant N as Novac B->>S: Places order (multiple vendors) S->>N: POST /checkout (with split config) N-->>S: Returns checkoutUrl + transactionRef S-->>B: Redirects buyer to checkout B->>N: Completes payment N-->>S: Webhook: notifyType = "successful" N->>N: Automatically splits and settles funds Note over N: Vendor A gets flat ₦2,000
Vendor B gets 30%
Platform keeps remainder ``` *** ### Prerequisites * [Create a account](/docs/getting-started/create-merchant-account) with completed KYC * [Obtain your Secret API keys](/docs/getting-started/obtain-api-keys) — required for all split payment configuration * [Set up your primary settlement account](/docs/accept-payment/split-payment/setup-primary-settlement-account) before creating sub-accounts *** ### Configure Sub-settlement Accounts Before a split can happen, define the accounts that should receive a portion of each payment. You can use **flat** (fixed amount) or **percent** (percentage of total) split types. ```bash Request theme={null} curl -X POST \ 'https://api.novacpayment.com/api/v1/split-payment' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '[ { "split_name": "vendor_a", "bank_code": "000013", "account_number": "0004498921", "split_type": "flat", "split_value": 2000 }, { "split_name": "logistics_fee", "bank_code": "000013", "account_number": "0004498938", "split_type": "percent", "split_value": 10 } ]' ``` ```json Response theme={null} { "status": true, "message": "Split Settings saved successfully", "data": [ { "split_name": "vendor_a", "split_payment_reference": "31VENDOR_ASPLIT0000130004498921", "split_type": "flat", "split_value": 2000 }, { "split_name": "logistics_fee", "split_payment_reference": "31LOGISTICS_FEESPLIT0000130004498938", "split_type": "percent", "split_value": 10 } ] } ``` Store each `split_payment_reference` securely. You will need it to update split rules in the future. Use the [Retrieve Payout Banks](/api-reference/payouts/retrieve-payout-banks) endpoint to get valid `bank_code` values before creating sub-settlement accounts. **Split type comparison:** | Type | Behaviour | Example | | --------- | -------------------------------------------- | ------------------------------------------------------- | | `flat` | A fixed amount per transaction | Vendor always receives ₦2,000 regardless of order total | | `percent` | A percentage of the total transaction amount | Logistics partner receives 10% of every order | [Full guide → Manage Sub-settlement Accounts](/docs/accept-payment/split-payment/manage-sub-settlement-accounts) *** ### Create a Checkout with Split Payment When initiating a checkout, attach the split configuration so Novac knows how to distribute funds upon settlement. ```bash Request theme={null} curl --request POST \ --url https://api.novacpayment.com/api/v1/checkout \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "amount": 20000, "currency": "NGN", "email": "buyer@example.com", "reference": "MKT-ORDER-00456", "callbackUrl": "https://yourmarketplace.com/payment/callback", "splitPayment": true }' ``` [Full guide → Create Checkout with Split Payment](/docs/accept-payment/checkout/create-checkout-with-transaction-reference#create-checkout-payment-with-split-payment) *** ### Verify and Fulfil the Order After the buyer completes payment, Novac redirects them to your `callbackURL`. Verify the transaction server-side before marking the order as paid. ```bash Request theme={null} curl --request GET \ --url https://api.novacpayment.com/api/v1/checkout/MKT-ORDER-00456/verify \ --header 'Authorization: Bearer ' ``` Only release goods or notify vendors when `data.status` is `"successful"`. [Full guide → Verify a Transaction](/docs/accept-payment/manage-payment/verify-transaction) *** ### Updating Split Rules Vendor commissions, platform fees, or bank account details can change. Update any existing sub-settlement account without disrupting live payments. ```bash Request theme={null} curl -X PUT \ 'https://api.novacpayment.com/api/v1/split-payment' \ -H 'Authorization: Bearer ' \ -H 'Content-Type: application/json' \ -d '{ "split_reference_code": "31VENDOR_ASPLIT0000130004498921", "bank_code": "000013", "account_number": "0004498921", "split_type": "flat", "split_value": 2500 }' ``` *** ### Listen for Webhooks Configure a webhook endpoint to receive settlement and payment events in real time — especially important when orders have multiple fulfilment stages across vendors. ```json Webhook Payload (example) theme={null} { "notify": "transaction", "notifyType": "successful", "data": { "transactionReference": "MKT-ORDER-00456", "amount": 20000, "chargedAmount": 20000, "currency": "NGN", "status": "successful" } } ``` [Full guide → Webhooks](/docs/api-basics/webhooks) *** ## What's Next? * **Setup Primary Settlement Account** - [Configure](/docs/accept-payment/split-payment/setup-primary-settlement-account) where your platform's share of payments gets settled. * **Manage Sub-settlement Accounts** - [Create, retrieve](/docs/accept-payment/split-payment/manage-sub-settlement-accounts), and update vendor payout configurations. * **Refund a Transaction** - Handle buyer [refund requests](/docs/accept-payment/manage-payment/refund-transaction), including split transactions. # Overview Source: https://developer.novacpayment.com/use-case/overview Explore how businesses across industries use Novac to accept payments, automate payouts, and manage money at scale. # Use Cases Novac is built for businesses that need reliable, developer-friendly payment infrastructure. Whether you're running an online store, a marketplace with multiple vendors, a SaaS product on a subscription model, or a platform selling digital goods. Novac has the APIs to support your payment flow end to end. *** ## Choose Your Use Case Accept card, bank transfer, USSD, and wallet payments at checkout. Handle callbacks, verify transactions, and issue refunds seamlessly. Collect payments from buyers and automatically split funds across multiple vendor accounts using Novac's Split Payment feature. Save customer cards on first payment and charge them automatically on a recurring schedule, no re-entry of card details required. Use Payment Links or the Checkout API to collect one-time payments for digital products, top-ups, and instant-access services. *** ## Core API Capabilities Regardless of which use case applies to your business, the following Novac capabilities are available across all integration patterns: | Capability | What it does | | ---------------------------- | -------------------------------------------------------------------------- | | **Multiple Payment Methods** | Card, Bank Transfer, USSD, Mobile Money, Opay, Palmpay | | **Webhooks** | Real-time event notifications when payments succeed, fail, or are reversed | | **Transaction Verification** | Server-side API to confirm payment status before delivering value | | **Refunds** | Full or partial refunds via API | | **Test Environment** | Simulate all payment flows safely before going live | | **Encryption** | Novac-managed card data encryption for PCI-compliant integrations | *** ## Before You Start All use cases require the following baseline setup: Sign up at [app.novacpayment.com](https://app.novacpayment.com) and complete KYC verification. [Get started](/docs/getting-started/create-merchant-account) Retrieve your **Public** and **Secret** keys from the API Settings tab in the dashboard. [Learn how](/docs/getting-started/obtain-api-keys) Set up a publicly accessible webhook URL in your dashboard to receive real-time payment notifications. [Learn how](/docs/api-basics/webhooks) Use your **Test API keys** to simulate transactions in the test environment. No real money moves. [Testing guide](/docs/api-basics/testing)