Build with TwelveAI Business

Introduction

TwelveAI Business is a payments platform for Nigerian businesses. You can accept card and bank-transfer payments, open a business bank account, settle to your wallet at T+1, initiate payouts, and build on a REST API with signed webhooks. Every account also includes an AI assistant that answers questions over your live data.

All amounts are in kobo (minor units): ₦500.00 is 50000.

Quickstart

Create an account, grab your test API key from the dashboard, and initialize your first payment:

curl https://api.twelveai.app/api/business/v1/payments/initialize \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "customer@example.com",
    "amount": 50000,
    "callback_url": "https://yourapp.com/paid"
  }'

The response includes an authorization_url. Redirect the customer there to pay. You are paid the moment the webhook fires.

Authentication

Authenticate every request with a bearer API key. Keys are scoped to a mode: sk_test_… for test and sk_live_… for live. Never expose a secret key in client-side code.

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxx

Accept payments

Initialize a payment to get a hosted checkout URL. If you do not supply a callback_url, we return the customer to your dashboard payment page. Save a card for repeat charges by re-using the returned authorization.

POST /api/business/v1/payments/initialize
{
  "email": "customer@example.com",
  "amount": 50000,             // ₦500.00 in kobo
  "callback_url": "https://yourapp.com/paid",
  "metadata": { "order_id": "ORD-1024" }
}

Webhooks

We POST HMAC-signed events to your webhook URL. Verify the signature header against your webhook secret before trusting the payload. The callback URL (where the customer lands) and the webhook URL (server-to-server truth) are different. Always treat the webhook as the source of truth.

POST https://yourapp.com/webhooks/twelveai
X-TwelveAI-Signature: sha512=...

{ "event": "payment.successful", "data": { "reference": "...", "amount": 50000 } }

Payouts

Withdraw your available balance to your verified settlement account. Payouts are live-only, have a ₦5,000 minimum, and the destination name is verified before any money moves.

POST /api/business/v1/transfers
{ "amount": 500000 }           // ₦5,000.00 minimum

AI assistant

Every account has a built-in assistant that answers questions over your live data: payments, payouts, balance and customers. It runs inside the dashboard (no API call needed), your chat is private to your business, and test-mode activity is excluded from every answer.

Connect

TwelveAI Connect lets your platform act on behalf of businesses that connect to you, via OAuth 2.0. Exchange an authorization code for an access token, then call the merchant API with it, optionally taking an application fee.

POST /api/business/v1/payments/initialize
Authorization: Bearer tw_at_...        // connected account token
{
  "email": "customer@example.com",
  "amount": 50000,
  "application_fee_percent": 2.5       // your 2.5% cut
}

Errors

Errors return a non-2xx status with a JSON body: { "success": false, "message": "..." }. A 401 means a bad or revoked key/token; a 403 on Connect means the token is missing the required scope.