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

# 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

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

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

<Accordion title="See details" defaultOpen={true}>
  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.
</Accordion>

## Payment Methods

<Accordion title="See details" defaultOpen={true}>
  Your clients can choose to pay via :

  1. Card Payment
  2. Bank transfer
  3. USSD payment
  4. OPAY
  5. Palmpay
</Accordion>

***

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

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

```bash expandable Request theme={null}
curl --request POST \
  --url https://api.novacpayment.com/api/v1/initiate \
  --header 'Authorization: <public-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "transactionReference": "<string>",
  "amount": 123,
  "currency": "<string>",
  "metaData": "<string>",
  "redirectUrl": "<string>",
  "allowedPaymentOptions":"<string>",
  "checkoutCustomerData": {
    "email": "<string>",
    "firstName": "<string>",
    "lastName": "<string>",
    "phoneNumber": "<string>"
  },
  "checkoutCustomizationData": {
    "logoUrl": "<string>",
    "paymentDescription": "<string>",
    "checkoutModalTitle": "<string>"
  }
}'
```

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

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**

<Note>
  This endpoint uses your **Public Key** for production and sandbox environment.
</Note>

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

<Note>
  This override applies only to the current transaction. Your saved split configuration remains unchanged.
</Note>

```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)