Recurring Payment (NGN Cards)

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

See details

Before creating a recurring payment link

• Create a 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.

1. Create recurring Payment Link

   A merchant creates a recurring payment link on the Novac dashboard, where the amount and charge frequency are configured

   

   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.

2. Complete Initial Checkout

   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.

3. Novac automate recurring payment when due

   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.

Request

curl --request POST \
    --url https://api.novacpayment.com/api/v1/recurring/initiate \
    --header 'Authorization: <public-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "paymentLinkReference": "string",
        "amount": 100,
        "metaData": "{\"name\":\"John\"}",
        "allowedPaymentOptions": "",
        "redirectUrl": "http://test.com",
        "checkoutCustomerData"*: {
            "email": "[e-mail]",
            "firstName": "John",
            "lastName": "Doe",
            "phoneNumber": "0908637****"
        },
        "checkoutCustomizationData": {
            "logoUrl": "",
            "paymentDescription": "",
            "checkoutModalTitle": ""
        }
    }'

Response

{
    "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.

Request

curl --request GET \
    --url https://api.novacpayment.com/api/v1/recurring/{reference} \
    --header 'Authorization: <public-key>' \
    --header 'Content-Type: application/json' \

Response

{
    "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

Request

curl --request POST \
    --url https://api.novacpayment.com/api/v1/recurring/card-payment \
    --header 'Authorization: <public-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "cardNumber": "string",
        "expiryMonth": "01",
        "expiryYear": "30",
        "cvv": "123",
        "cardPin": "1234",
        "transactionReference": "string"
    }'

Success Response

{
    "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.

Request

curl --request GET \
    --url https://api.novacpayment.com/api/v1/recurring/{reference}/verify \
    --header 'Authorization: <public-key>' \
    --header 'Content-Type: application/json' \

Success Response

{
    "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.

Request

curl --request POST \
    --url https://api.novacpayment.com/api/v1/recurring/updatestatus \
    --header 'Authorization: <public-key>' \
    --header 'Content-Type: application/json' \
    --data '{
        "reference": "string",
        "status": "active"
    }'

Success Response

{
    "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

• 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

• Request Refund: Initiate a full or partial refund.