Skip to main content

​
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

​
Prerequisites

See details

  • Create an account with completed KYC
  • Obtain your 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

Request
curl --request POST \
  --url https://api.novacpayment.com/api/v1/checkout \
  --header 'Authorization: Bearer <your-public-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 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:
Request
curl --request GET \
  --url https://api.novacpayment.com/api/v1/checkout/SUB-INITIAL-00789/verify \
  --header 'Authorization: Bearer <your-secret-key>'
Response (excerpt)
{
  "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

​
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.
Request
curl --request POST \
  --url https://api.novacpayment.com/api/v1/tokenized-card-charge \
  --header 'Authorization: Bearer <your-secret-key>' \
  --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

​
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.
Successful Renewal
{
  "notify": "transaction",
  "notifyType": "successful",
  "data": {
    "transactionReference": "SUB-RENEWAL-00790",
    "amount": 5000,
    "status": "successful",
    "customer": { "email": "subscriber@example.com" }
  }
}
Failed Renewal
{
  "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:
ScenarioRecommended Action
Insufficient fundsRetry after 24–48 hours, notify customer
Card expiredPrompt customer to update card details via a new checkout
Repeated failuresSuspend subscription, send dunning email
Full guide > 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 and tokenised charges.
  • Refund a Transaction - Issue full or partial refunds when a subscriber cancels mid-cycle.
  • Webhooks - Set up and secure your webhook endpoint for renewal notifications.