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 fully managed by Novac
• Custom Checkout for USSD and Bank Transfer partial control without handling card data

---

Prerequisites

Before you begin

• Create a merchant account with KYC completed.
• Obtain your secret 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.

With Card Encryption

Encrypt card details on your server before sending. Recommended for teams that want an extra layer of security beyond HTTPS.

Without Card Encryption

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 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 · number · required

Amount to charge, in the smallest currency unit (e.g. kobo for NGN).

currency · string · required

ISO 4217 currency code, e.g. NGN, USD.

reference · string · required

Unique transaction reference, at least 16 alphanumeric characters. Must match the reference used to encrypt the card data.

email · string · required

Customer’s email address.

card · string · required

Novac-encrypted card string.

transactionType · string · required

Must be sale.

enforceSecureAuth · boolean · default: "true"

Controls 3DS authentication. Set to true to enforce 3DS, or false for No-Auth (2D) if enabled on your account.

redirectUrl · string

URL to redirect the customer to after payment. If omitted, Novac displays a default confirmation page.

metaData · string

A JSON string of key-value pairs to associate with this transaction.

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": "[e-mail]",
    "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.

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": "[e-mail]",
    "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.

Response

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

Response Approved (No-Auth)

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

Response

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

Response

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

• 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

• Recurring Payment: Learn how to save and charge customer’s card for subscriptions based services.

• Request Refund: Initiate a full or partial refund.