Initiate Checkout Transaction

The Initiate Checkout endpoint creates a new checkout session for your customer. This generates a one-time payment address and reference details, allowing the payer to complete their transaction.

📝 Key Notes

• A valid email address must be included in the request body. This is used to notify the customer about each payment step.

• Customers are expected to pay directly from their exchange/wallet, copying the provided address and destination tag (when required).

• Each session is valid for 5 minutes. After expiration, a new request will be automatically generated if the customer is still on the checkout screen.

Endpoint

POST

{{base_url}}/api/checkout/initiate-checkout/

Example Request

curl --location '{{base_url}}/api/checkout/initiate-checkout/' \
--header 'X-Api-Key: *******************' \
--header 'X-Api-Id: ****************' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 2000.00,
  "from_currency": "USDC",
  "to_currency": "NGN",
  "chain": "BASE",
  "reference": "28282882882",
  "description": "Payment for goods or services"
  "email": "[email protected]"
}'

Request Body Parameters

Name	Type	Required	Description
amount	number	✅ Yes	The fiat amount to charge. Supported: NGN, GHS, ZAR, KES.
from_currency	string	✅ Yes	The cryptocurrency the customer will pay with. Supported: USDT, USDC, SOL.
to_currency	string	✅ Yes	The fiat currency you want to receive. Supported: NGN, GHS, ZAR, KES.
chain	string	✅ Yes	The blockchain/network of the from_currency (e.g., BASE, POLYGON, SOLANA).
email	string	✅ Yes	Customer’s valid email address for notifications.
reference	string	✅ Yes	Merchant reference ID (up to 32 characters). Recommended: generate unique references for reconciliation.
description	string	Optional	If not provided would default to "Payment for goods or services"

Example Response (200 OK)

{
    "success": true,
    "message": "Checkout initiated successfully",
    "data": {
        "payment_reference_id": "17f23c46-428b-435c-9c55-a2a6ea1f56fc",
        "crypto_amount": 1.357188,
        "fiat_amount": 2000.0,
        "fiat_currency": "NGN",
        "crypto_currency": "USDC",
        "crypto_chain": "BASE",
        "exchange_rate": 1473.6351414819635,
        "merchant_reference_id": "28212882882",
        "payment_address": "0x9881A1d52673C90aC70921319bE7e3f0f961dE49",
        "payment_address_tag": null,
        "expires_at": "2025-09-09T18:36:24.070118Z",
        "redirect_url": "www.mykazza.com/checkout/redirect/17f23c46-428b-435c-9c55-a2a6ea1f56fc",
        "callback_url": null,
        "status": "payment_pending",
        "email": "[email protected]",
        "origin_asset_code": "USDC",
        "destination_asset_code": "NGN",
        "origin_asset_name": "USD Coin (USDC)",
        "destination_asset_name": "NG Naira",
        "origin_asset_logo": "https://firebasestorage.googleapis.com/v0/b/kazza-2f5ca.firebasestorage.app/o/usd-coin-usdc-logo.png?alt=media&token=79f75260-9edf-4a99-8aca-bfe68632fa86",
        "destination_asset_logo": "https://firebasestorage.googleapis.com/v0/b/kazza-2f5ca.firebasestorage.app/o/Component%209.png?alt=media&token=f777e66e-dcfe-4541-8ed2-3260edeaa638",
        "origin_asset_chain": "BASE",
        "checkout_link": "www.mykazza.com/checkout/17f23c46-428b-435c-9c55-a2a6ea1f56fc"
    }
}

Response Field Definitions

Field	Type	Description
payment_reference_id	string	Unique Kazza-generated ID for the transaction.
crypto_amount	number	Exact amount of crypto the customer must send.
merchant_fiat_amount	string	Fiat equivalent the merchant will receive.
merchant_reference_id	string	Reference you provided in the request.
payment_address	string	Wallet address the customer should send to.
payment_address_tag	string	Destination tag/memo if required (e.g., XLM, XRP).
expires_at	string	Expiration timestamp for this checkout session.
status	string	Initial transaction status. Usually payment_pending.
origin_asset_code	string	The crypto being paid (e.g., USDC).
destination_asset_code	string	The fiat settlement currency (e.g., NGN).
checkout_link	string	Shareable checkout page link.

---

🧑‍💻 Developer Notes

• Customers must pay the exact crypto amount (crypto_amount) displayed.

• Merchants will receive settlement in fiat (merchant_fiat_amount) or crypto, depending on configuration.

• Always verify the transaction status via:

  • Webhook notifications, or

  • GET /api/checkout/verify-payment-request/{payment_reference_id}.

• Sessions expire after 5 minutes. Always handle expired status gracefully.