Skip to main content

​
Quickstart

​
In a nutshell

This guide shows the shortest path to a card-backed subscription: create a tenant API key, create a plan, create a customer, and initialize a Nomba Checkout order with card tokenization enabled.

​
1. Get an API key

Create a tenant and store the returned key securely on your server. 
curl -X POST https://nombasub.oluwadunsin.dev/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "businessName": "Acme SaaS",
    "accountId": "nomba_account_or_subaccount_id"
  }'
Response: 
{
  "status": "success",
  "message": "Tenant registered successfully",
  "data": {
    "apiKey": "sub_xxx"
  }
}

​
2. Create a plan

curl -X POST https://nombasub.oluwadunsin.dev/v1/plan/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "name": "Growth Monthly",
    "description": "Monthly subscription for growing teams",
    "amount": 500000,
    "currency": "NGN",
    "interval": "monthly",
    "intervalCount": 1,
    "trialPeriodDays": 0
  }'

​
3. Create a customer

curl -X POST https://nombasub.oluwadunsin.dev/v1/customer/ \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "email": "customer@example.com",
    "name": "Ada Lovelace",
    "phoneNumber": "+2348012345678",
    "externalRef": "user_123"
  }'

​
4. Initialize checkout

curl -X POST https://nombasub.oluwadunsin.dev/v1/checkout/order \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: sub_xxx" \
  -d '{
    "planCode": "PLN_8AbC123x",
    "order": {
      "callbackUrl": "https://merchant.example.com/callback",
      "customerEmail": "customer@example.com",
      "amount": 0,
      "currency": "NGN",
      "orderReference": "merchant_order_123"
    }
  }'
The engine uses the selected plan amount and currency, enables card tokenization, and returns a checkout link.

​
5. Complete payment

Redirect the customer to the checkout link. After payment, the engine stores the reusable Nomba card token, updates billing records, and sends merchant webhooks when configured.

​
Next steps