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 tw_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’re paid the moment the webhook fires.

Authentication

Keys come as a public/secret pair, scoped to a mode. Authenticate every request with the secret key as a bearer token: tw_test_… for test and tw_live_… for live (the public key is tw_pub_test_… / tw_pub_live_…). Never expose a secret key in client-side code.

Authorization: Bearer tw_live_xxxxxxxxxxxxxxxxxxxx

Accept payments

Initialize a payment to get a hosted checkout URL. If you don’t 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
}

See the Connect overview for scopes, the consent flow, and platform webhooks.

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.