Digital Product Cart Checkout

Sell multiple digital products in a single checkout. No shipping, no address collection, instant fulfillment.

Supported Product Types: digital, gift_card, othersThese product types share a simplified checkout flow - no cart validation step, no shipping address required.

Quick Start

1. Build Your Payload

{
  "product_type": "digital",
  "product_title": "Design Assets Bundle",
  "order_total_charge": 4500,
  "cart": [
    {
      "product_id": 3553,
      "quantity": 1,
      "price": 2000,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none"
    },
    {
      "product_id": 3570,
      "quantity": 1,
      "price": 2500,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none"
    }
  ],
  "email": "customer@example.com",
  "first_name": "John",
  "last_name": "Doe",
  "currency": "USD",
  "payment_type": "one",
  "is_coupon_used": false,
  "is_second_time_payment": false,
  "payment_by": "customer"
}

2. Call Payment Intent API

curl -X POST https://api.khaime.com/api/v1/payment/intent \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ ... payload above ... }'

3. Use the Token

{
  "status": true,
  "message": "Payment Intent Successful",
  "data": {
    "token": "eyJtZXJjaGFudF9pZCI6MTc5MCwi...",
    "amount": 4500,
    "currency": "USD",
    "cart_identifier": "digital-1234567890-abc123"
  }
}

Pass token to <KhaimeCheckout /> - payment gateway is handled automatically.

How It Works

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│  Your Frontend  │────▶│  Your Backend   │────▶│   Khaime API    │
│                 │     │                 │     │                 │
│  Cart Items     │     │  POST /checkout │     │  POST /payment  │
│  + Customer     │     │  (your route)   │     │  /intent        │
└─────────────────┘     └─────────────────┘     └─────────────────┘
                                                        │
                                                        ▼
                              ┌─────────────────────────────────────┐
                              │  Returns token with gateway config  │
                              │  (Stripe, Paystack, StartButton)    │
                              └─────────────────────────────────────┘
                                                        │
                                                        ▼
                        ┌─────────────────────────────────────────────┐
                        │  <KhaimeCheckout token={token} />           │
                        │  Renders correct payment UI automatically   │
                        └─────────────────────────────────────────────┘

Key points:

Your backend calls Khaime API and gets a token
Token contains everything needed for payment (gateway, keys, amount)
Your code never touches Stripe/Paystack/etc directly
Gateway is selected automatically based on currency

Request Reference

Top-Level Fields

Field	Type	Required	Description
`product_type`	string	Yes	`"digital"`, `"gift_card"`, or `"others"`
`product_title`	string	Yes	Display name (e.g., `"Cart (3 items)"`)
`order_total_charge`	number	Yes	Total in cents (sum of price × quantity)
`cart`	array	Yes	Array of cart items
`email`	string	Yes	Customer email
`first_name`	string	Yes	Customer first name
`last_name`	string	Yes	Customer last name
`currency`	string	Yes	ISO currency code (`"USD"`, `"NGN"`, `"GHS"`, etc.)
`payment_type`	string	Yes	Must be `"one"` for cart checkout
`is_coupon_used`	boolean	Yes	Set `false` if no coupon
`is_second_time_payment`	boolean	Yes	Set `false` for new purchases
`payment_by`	string	Yes	Must be `"customer"`

Cart Item Fields

Field	Type	Required	Description
`product_id`	number	Yes	Khaime product ID
`quantity`	number	Yes	Number of units
`price`	number	Yes	Per-unit price in cents
`product_image`	string	Yes	Image URL or empty string `""`
`has_variation`	boolean	Yes	Set `false` for standard products
`product_variant_data`	string	Yes	Set `"none"` for standard products
`additional_information`	object	No	Custom form fields (see below)

Digital cart items use a SIMPLER schema than physical products.Do NOT include: product_title, product_thumbnail, main_variant, least_sub_variant_id, shipping_rate

Currency & Gateway Routing

Khaime automatically selects the payment gateway based on currency:

Currency	Gateway	Payment UI
USD, EUR, GBP, CAD	Stripe	Embedded card form
NGN	Paystack	Popup / redirect
GHS	StartButton	Redirect
KES	Paystack Kenya	Popup / redirect
ZAR	Paystack	Popup / redirect

Your code doesn’t need to know about gateways - just pass the currency and Khaime handles the rest.

Complete Examples

USD Checkout (Stripe)

{
  "product_type": "digital",
  "product_title": "Premium Template Pack",
  "order_total_charge": 4900,
  "cart": [
    {
      "product_id": 1001,
      "quantity": 1,
      "price": 2900,
      "product_image": "https://example.com/template1.jpg",
      "has_variation": false,
      "product_variant_data": "none"
    },
    {
      "product_id": 1002,
      "quantity": 1,
      "price": 2000,
      "product_image": "https://example.com/template2.jpg",
      "has_variation": false,
      "product_variant_data": "none"
    }
  ],
  "email": "buyer@example.com",
  "first_name": "Sarah",
  "last_name": "Connor",
  "currency": "USD",
  "payment_type": "one",
  "is_coupon_used": false,
  "is_second_time_payment": false,
  "payment_by": "customer"
}

NGN Checkout (Paystack)

{
  "product_type": "digital",
  "product_title": "E-book Collection",
  "order_total_charge": 1500000,
  "cart": [
    {
      "product_id": 2001,
      "quantity": 1,
      "price": 500000,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none"
    },
    {
      "product_id": 2002,
      "quantity": 2,
      "price": 500000,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none"
    }
  ],
  "email": "buyer@example.ng",
  "first_name": "Chidi",
  "last_name": "Okonkwo",
  "currency": "NGN",
  "payment_type": "one",
  "is_coupon_used": false,
  "is_second_time_payment": false,
  "payment_by": "customer"
}

Gift Cards with Recipient Info

{
  "product_type": "gift_card",
  "product_title": "Gift Cards (2)",
  "order_total_charge": 10000,
  "cart": [
    {
      "product_id": 5001,
      "quantity": 1,
      "price": 5000,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none",
      "additional_information": {
        "recipient_name": "John Smith",
        "recipient_email": "john@example.com",
        "gift_message": "Happy Birthday!"
      }
    },
    {
      "product_id": 5001,
      "quantity": 1,
      "price": 5000,
      "product_image": "",
      "has_variation": false,
      "product_variant_data": "none",
      "additional_information": {
        "recipient_name": "Jane Doe",
        "recipient_email": "jane@example.com",
        "gift_message": "Congratulations!"
      }
    }
  ],
  "email": "purchaser@example.com",
  "first_name": "Mike",
  "last_name": "Wilson",
  "currency": "USD",
  "payment_type": "one",
  "is_coupon_used": false,
  "is_second_time_payment": false,
  "payment_by": "customer"
}

Merchant Backend Example

Your backend receives cart data from your frontend, transforms it to Khaime format, and returns the token.

Next.js API Route

// app/api/checkout/route.ts
import { NextResponse } from 'next/server';

const KHAIME_API_KEY = process.env.KHAIME_API_KEY;
const KHAIME_API_URL = 'https://api.khaime.com/api/v1';

export async function POST(request: Request) {
  const body = await request.json();
  const { items, currency, email, firstName, lastName } = body;

  // Transform to Khaime format
  const cart = items.map((item: any) => ({
    product_id: Number(item.productId),
    quantity: item.quantity,
    price: item.price,
    product_image: item.productImage || '',
    has_variation: false,
    product_variant_data: 'none',
  }));

  const totalAmount = items.reduce(
    (sum: number, item: any) => sum + item.price * item.quantity,
    0
  );

  const productTitle = items.length === 1
    ? items[0].productTitle
    : `Cart (${items.length} items)`;

  // Call Khaime API
  const response = await fetch(`${KHAIME_API_URL}/payment/intent`, {
    method: 'POST',
    headers: {
      'X-API-Key': KHAIME_API_KEY!,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      product_type: 'digital',
      product_title: productTitle,
      order_total_charge: totalAmount,
      cart,
      email,
      first_name: firstName,
      last_name: lastName,
      currency,
      payment_type: 'one',
      is_coupon_used: false,
      is_second_time_payment: false,
      payment_by: 'customer',
    }),
  });

  const data = await response.json();

  if (!data.status) {
    return NextResponse.json(
      { ok: false, error: data.message },
      { status: 400 }
    );
  }

  // Return token to frontend
  return NextResponse.json({
    ok: true,
    data: {
      token: data.data.token,
      amount: data.data.amount,
      currency: data.data.currency,
    },
  });
}

Frontend Component

import { useState } from 'react';
import { KhaimeCheckout } from '@khaime/react';

interface CartItem {
  productId: number;
  productTitle: string;
  productImage: string;
  price: number;
  quantity: number;
}

export function DigitalCheckout({ items, currency }: {
  items: CartItem[];
  currency: string;
}) {
  const [token, setToken] = useState<string | null>(null);
  const [loading, setLoading] = useState(false);

  const handleCheckout = async () => {
    setLoading(true);

    const response = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        items,
        currency,
        email: 'customer@example.com',
        firstName: 'John',
        lastName: 'Doe',
      }),
    });

    const result = await response.json();
    setLoading(false);

    if (result.ok) {
      setToken(result.data.token);
    }
  };

  if (token) {
    return (
      <KhaimeCheckout
        token={token}
        onSuccess={(result) => {
          console.log('Payment successful!', result);
          window.location.href = '/success';
        }}
        onError={(error) => {
          console.error('Payment failed:', error);
          setToken(null);
        }}
        onClose={() => setToken(null)}
      />
    );
  }

  return (
    <button onClick={handleCheckout} disabled={loading}>
      {loading ? 'Processing...' : `Pay Now`}
    </button>
  );
}

Response Structure

Success Response

{
  "status": true,
  "message": "Payment Intent Successful",
  "data": {
    "token": "eyJtZXJjaGFudF9pZCI6MTc5MCwicGF5bWVudF9nYXRld2F5Ijoic3RyaXBlIi...",
    "cart_identifier": "digital-1788636780073-tcvplc8s0",
    "amount": 4500,
    "currency": "USD"
  }
}

Token Security

The token is signed with HMAC-SHA256 and expires after 15 minutes. Format: base64(payload).signature

{
  "merchant_id": 1790,
  "payment_gateway": "stripe",
  "publishable_key": "pk_test_...",
  "client_secret": "pi_xxx_secret_xxx",
  "amount": 4500,
  "currency": "USD",
  "payment_type": "one_time",
  "iat": 1699900000,
  "exp": 1699900900,
  "metadata": {
    "stripe_account_id": "acct_xxx",
    "is_direct_charge": true
  },
  "product": {
    "name": "Design Assets Bundle",
    "type": "digital",
    "currency": "USD"
  }
}

You don’t need to decode the token - just pass it to <KhaimeCheckout /> and it handles everything.Important: Tokens expire after 15 minutes. If a customer waits too long, create a new payment intent.

After Payment

Order Structure

After successful payment, the Order contains all cart items:

{
  "id": 91234,
  "status": "completed",
  "payment_status": "paid",
  "cart_items": {
    "cart_details": [
      {
        "product_id": 1001,
        "quantity": 1,
        "price": 2900,
        "product_title": "Premium Template",
        "product_type": "digital",
        "downloadable_links": [
          {
            "name": "template.zip",
            "url": "https://storage.example.com/signed-url"
          }
        ]
      }
    ]
  },
  "cart_item_identifier": "digital-1788636780073-tcvplc8s0"
}

Customer Receives

Confirmation email with all purchased items
Download links for each digital product
Order accessible in their account

Pricing

All Amounts in Cents

Display Price	API Value	Currency
$15.00	`1500`	USD
$149.99	`14999`	USD
N15,000.00	`1500000`	NGN
GH₵100.00	`10000`	GHS

Total Calculation

line_total = price × quantity
cart_total = sum(all line_totals)
final_charge = cart_total + platform_fees

vs Physical Products

Aspect	Physical Products	Digital Products
Cart validation	Required (`/cart/validate`)	Not required
`cart_unique_id`	Required	Auto-generated
Shipping address	Required	Not required
`delivery_details`	Required	Not required
Shipping fees	Calculated	None
Fulfillment	Manual shipping	Instant download

Error Codes

Code	Description	Fix
`VALIDATION_ERROR`	Missing/invalid fields	Check required fields
`PRODUCT_NOT_FOUND`	Invalid `product_id`	Verify product exists
`PAYMENT_INTENT_FAILED`	Gateway error	Check API keys/config
`CURRENCY_NOT_SUPPORTED`	Unsupported currency	Use supported currency

Physical Product Checkout

Checkout with shipping and cart validation

Payment Intent API

Full API reference

React SDK

<KhaimeCheckout /> component

Webhooks

Payment event notifications

​Digital Product Cart Checkout

​Quick Start

​1. Build Your Payload

​2. Call Payment Intent API

​3. Use the Token

​How It Works

​Request Reference

​Top-Level Fields

​Cart Item Fields

​Currency & Gateway Routing

​Complete Examples

​USD Checkout (Stripe)

​NGN Checkout (Paystack)

​Gift Cards with Recipient Info

​Merchant Backend Example

​Next.js API Route

​Frontend Component

​Response Structure

​Success Response

​Token Security

​After Payment

​Order Structure

​Customer Receives

​Pricing

​All Amounts in Cents

​Total Calculation

​vs Physical Products

​Error Codes

​Related

Physical Product Checkout

Payment Intent API

React SDK

Webhooks

Digital Product Cart Checkout

Quick Start

1. Build Your Payload

2. Call Payment Intent API

3. Use the Token

How It Works

Request Reference

Top-Level Fields

Cart Item Fields

Currency & Gateway Routing

Complete Examples

USD Checkout (Stripe)

NGN Checkout (Paystack)

Gift Cards with Recipient Info

Merchant Backend Example

Next.js API Route

Frontend Component

Response Structure

Success Response

Token Security

After Payment

Order Structure

Customer Receives

Pricing

All Amounts in Cents

Total Calculation

vs Physical Products

Error Codes

Related