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

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

<Warning>
  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
</Warning>

***

## Prerequisites

<Accordion title="Before you begin" defaultOpen={true}>
  * [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.
</Accordion>

***

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

<CardGroup cols={2}>
  <Card icon="lock" title="With Card Encryption" href="#with-card-encryption">
    Encrypt card details on your server before sending. Recommended for teams that want an extra layer of security beyond HTTPS.
  </Card>

  <Card icon="bolt" title="Without Card Encryption" href="#without-card-encryption">
    Send card details over HTTPS without pre-encrypting. Suitable for compliant integrations on secure infrastructure.
  </Card>
</CardGroup>

***

### With Card Encryption {/* #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.

<Note>
  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.
</Note>

<ParamField body="amount" type="number" required>
  Amount to charge, in the smallest currency unit (e.g. kobo for NGN).
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code, e.g. `NGN`, `USD`.
</ParamField>

<ParamField body="reference" type="string" required>
  Unique transaction reference, **at least 16 alphanumeric characters**. Must match the reference used to encrypt the card data.
</ParamField>

<ParamField body="email" type="string" required>
  Customer's email address.
</ParamField>

<ParamField body="card" type="string" required>
  Novac-encrypted card string.
</ParamField>

<ParamField body="transactionType" type="string" required>
  Must be `sale`.
</ParamField>

<ParamField body="enforceSecureAuth" type="boolean" default="true">
  Controls 3DS authentication. Set to `true` to enforce 3DS, or `false` for No-Auth (2D) if enabled on your account.
</ParamField>

<ParamField body="redirectUrl" type="string">
  URL to redirect the customer to after payment. If omitted, Novac displays a default confirmation page.
</ParamField>

<ParamField body="metaData" type="string">
  A JSON string of key-value pairs to associate with this transaction.
</ParamField>

```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": ""
  }'
```

<Note>
  **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.
</Note>

***

### Without Card Encryption {/* #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.

<Info>
  `cardData.pin` is only required if the currency is NGN. `transactionType` must still be `sale`.
</Info>

```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"
  }
}
```

<Warning>
  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.
</Warning>

<Info>
  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.
</Info>

***

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