API reference

// lib/checkout.ts - talks to YOUR backend, never to TwelveAI directly.
// The server side of POST /api/checkout is in the Node, Python, PHP or Go tab.
export async function createCheckout(input: { email: string; amount: number; orderId: string }) {
  const r = await fetch('/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),          // amount in kobo: 50000 = NGN 500.00
  })
  if (!r.ok) throw new Error('Could not start checkout')
  return (await r.json()) as { checkout_url: string; reference: string }
}

// PayButton.tsx
import { useState } from 'react'
import { createCheckout } from './lib/checkout'

export function PayButton({ email, amount, orderId }: { email: string; amount: number; orderId: string }) {
  const [busy, setBusy] = useState(false)

  async function pay() {
    setBusy(true)
    try {
      const { checkout_url } = await createCheckout({ email, amount, orderId })
      window.location.href = checkout_url     // or window.open(checkout_url, '_blank')
    } finally {
      setBusy(false)
    }
  }

  return <button onClick={pay} disabled={busy}>{busy ? 'Starting...' : 'Pay NGN 500'}</button>
}

// PaymentResult.tsx - rendered at your callback_url, e.g. /pay/done?reference=order-12345
import { useEffect, useState } from 'react'

export function PaymentResult() {
  const [status, setStatus] = useState('checking')

  useEffect(() => {
    const reference = new URLSearchParams(window.location.search).get('reference')
    fetch('/api/checkout/' + reference)        // your backend calls GET /payments/verify/:reference
      .then((r) => r.json())
      .then((d) => setStatus(d.status))
  }, [])

  if (status === 'checking') return <p>Confirming your payment...</p>
  if (status === 'successful') return <p>Payment received. Thank you!</p>
  return <p>Payment {status}. If you were charged, it will reflect shortly.</p>
}
// This screen is for the customer. Fulfil the order from the charge.success
// webhook on your backend (Node, Python, PHP or Go tab), never from here.

// app/api/checkout/route.ts - a Route Handler runs on the server, so the
// secret key never reaches the browser. Keep it in .env as TWELVEAI_SECRET_KEY.
import { NextResponse } from 'next/server'

export async function POST(req: Request) {
  const { email, amount, orderId } = await req.json()
  const r = await fetch('https://api.twelveai.app/api/business/v1/payments/initialize', {
    method: 'POST',
    headers: {
      Authorization: 'Bearer ' + process.env.TWELVEAI_SECRET_KEY, // tw_test_... or tw_live_...
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      email,
      amount,                                        // kobo: 50000 = NGN 500.00
      reference: 'order-' + orderId,                 // your own id, unique per payment
      callback_url: process.env.NEXT_PUBLIC_APP_URL + '/pay/done',
      metadata: { order_id: orderId },
    }),
  })
  const { data } = await r.json()
  return NextResponse.json({ checkout_url: data.checkout_url, reference: data.reference })
}

// app/checkout/PayButton.tsx
'use client'
import { useState } from 'react'

export function PayButton({ email, amount, orderId }: { email: string; amount: number; orderId: string }) {
  const [busy, setBusy] = useState(false)

  async function pay() {
    setBusy(true)
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email, amount, orderId }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url     // or window.open(checkout_url, '_blank')
  }

  return <button onClick={pay} disabled={busy}>Pay NGN 500</button>
}

// app/pay/done/page.tsx - your callback_url. Verify is for the UI only.
export default async function PayDone({ searchParams }: { searchParams: Promise<{ reference?: string }> }) {
  const { reference } = await searchParams
  const r = await fetch('https://api.twelveai.app/api/business/v1/payments/verify/' + reference, {
    headers: { Authorization: 'Bearer ' + process.env.TWELVEAI_SECRET_KEY },
    cache: 'no-store',
  })
  const { data } = await r.json()
  return <h1>{data.status === 'successful' ? 'Payment received' : 'Payment ' + data.status}</h1>
}

// app/api/webhooks/twelve/route.ts - the source of truth for fulfilling the order
import crypto from 'node:crypto'

export async function POST(req: Request) {
  const raw = await req.text()                       // raw body, before JSON.parse
  const expected = crypto.createHmac('sha512', process.env.TWELVEAI_WEBHOOK_SECRET!).update(raw).digest('hex')
  const got = req.headers.get('x-twelveai-signature') || ''
  if (got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return new Response('bad signature', { status: 401 })
  }
  const eventId = req.headers.get('x-twelveai-event-id')!
  const { event, data } = JSON.parse(raw)
  void enqueue(eventId, event, data)                 // hand to a queue, do not await it; dedupe by eventId
  return new Response('ok', { status: 200 })         // ack within 10 seconds
}

// server/api/checkout.post.ts (Nuxt) - runs on the server, so the secret key never reaches the browser.
// Plain Vue without Nuxt? Put this endpoint on your backend: see the Node, Python, PHP or Go tab.
export default defineEventHandler(async (event) => {
  const { email, amount, orderId } = await readBody(event)
  const { data } = await $fetch<{ data: { checkout_url: string; reference: string } }>(
    'https://api.twelveai.app/api/business/v1/payments/initialize',
    {
      method: 'POST',
      headers: { Authorization: 'Bearer ' + process.env.TWELVEAI_SECRET_KEY }, // tw_test_... or tw_live_...
      body: {
        email,
        amount,                                  // kobo: 50000 = NGN 500.00
        reference: 'order-' + orderId,           // your own id, unique per payment
        callback_url: 'https://yourapp.com/pay/done',
        metadata: { order_id: orderId },
      },
    },
  )
  return { checkout_url: data.checkout_url, reference: data.reference }
})

<!-- components/PayButton.vue -->
<script setup lang="ts">
import { ref } from 'vue'
const props = defineProps<{ email: string; amount: number; orderId: string }>()
const busy = ref(false)

async function pay() {
  busy.value = true
  try {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: props.email, amount: props.amount, orderId: props.orderId }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
  } finally {
    busy.value = false
  }
}
</script>

<template>
  <button :disabled="busy" @click="pay">Pay NGN 500</button>
</template>

<!-- pages/pay/done.vue - your callback_url. Verify is for the UI only. -->
<script setup lang="ts">
const route = useRoute()
// server/api/checkout/[reference].get.ts calls GET /payments/verify/:reference with your secret key
const { data } = await useFetch('/api/checkout/' + route.query.reference)
</script>
<template>
  <h1>{{ data?.status === 'successful' ? 'Payment received' : 'Payment ' + data?.status }}</h1>
</template>

// server/api/webhooks/twelve.post.ts - the source of truth for fulfilling the order
import { createHmac, timingSafeEqual } from 'node:crypto'

export default defineEventHandler(async (event) => {
  const raw = (await readRawBody(event, 'utf8')) || ''        // raw body, before JSON.parse
  const expected = createHmac('sha512', process.env.TWELVEAI_WEBHOOK_SECRET!).update(raw).digest('hex')
  const got = getHeader(event, 'x-twelveai-signature') || ''
  if (got.length !== expected.length || !timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    throw createError({ statusCode: 401 })
  }
  const eventId = getHeader(event, 'x-twelveai-event-id')!
  const { event: name, data } = JSON.parse(raw)
  void enqueue(eventId, name, data)   // hand to a queue; dedupe by eventId, fulfil once per data.reference
  return { ok: true }                 // 200 within 10 seconds
})

// src/routes/api/checkout/+server.ts (SvelteKit) - server only; the secret key never reaches the browser.
// Plain Svelte without Kit? Put this endpoint on your backend: see the Node, Python, PHP or Go tab.
import { json } from '@sveltejs/kit'
import { TWELVEAI_SECRET_KEY } from '$env/static/private'   // tw_test_... or tw_live_...

export async function POST({ request }) {
  const { email, amount, orderId } = await request.json()
  const r = await fetch('https://api.twelveai.app/api/business/v1/payments/initialize', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + TWELVEAI_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      amount,                                  // kobo: 50000 = NGN 500.00
      reference: 'order-' + orderId,           // your own id, unique per payment
      callback_url: 'https://yourapp.com/pay/done',
      metadata: { order_id: orderId },
    }),
  })
  const { data } = await r.json()
  return json({ checkout_url: data.checkout_url, reference: data.reference })
}

<!-- PayButton.svelte -->
<script lang="ts">
  export let email: string
  export let amount: number      // kobo: 50000 = NGN 500.00
  export let orderId: string
  let busy = false

  async function pay() {
    busy = true
    try {
      const r = await fetch('/api/checkout', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, amount, orderId }),
      })
      const { checkout_url } = await r.json()
      window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
    } finally {
      busy = false
    }
  }
</script>

<button on:click={pay} disabled={busy}>Pay NGN 500</button>

// src/routes/pay/done/+page.server.ts - your callback_url. Verify is for the UI only.
import { TWELVEAI_SECRET_KEY } from '$env/static/private'

export async function load({ url, fetch }) {
  const reference = url.searchParams.get('reference')
  const r = await fetch('https://api.twelveai.app/api/business/v1/payments/verify/' + reference, {
    headers: { Authorization: 'Bearer ' + TWELVEAI_SECRET_KEY },
  })
  const { data } = await r.json()
  return { status: data.status }   // +page.svelte shows "Payment received" when it is 'successful'
}

// src/routes/webhooks/twelve/+server.ts - the source of truth for fulfilling the order
import { createHmac, timingSafeEqual } from 'node:crypto'
import { TWELVEAI_WEBHOOK_SECRET } from '$env/static/private'

export async function POST({ request }) {
  const raw = await request.text()             // raw body, before JSON.parse
  const expected = createHmac('sha512', TWELVEAI_WEBHOOK_SECRET).update(raw).digest('hex')
  const got = request.headers.get('x-twelveai-signature') || ''
  if (got.length !== expected.length || !timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return new Response('bad signature', { status: 401 })
  }
  const eventId = request.headers.get('x-twelveai-event-id')!
  const { event, data } = JSON.parse(raw)
  void enqueue(eventId, event, data)          // queue it; dedupe by eventId, fulfil once per data.reference
  return new Response('ok', { status: 200 })  // ack within 10 seconds
}

// lib/checkout.ts - talks to YOUR backend, never to TwelveAI directly.
// Secret keys must never ship inside a mobile app. The server side of
// POST /api/checkout is in the Node, Python, PHP or Go tab.
const BACKEND = 'https://yourapp.com'

export async function createCheckout(input: { email: string; amount: number; orderId: string }) {
  const r = await fetch(BACKEND + '/api/checkout', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(input),          // amount in kobo: 50000 = NGN 500.00
  })
  if (!r.ok) throw new Error('Could not start checkout')
  return (await r.json()) as { checkout_url: string; reference: string }
}
// On the server, send callback_url: 'https://yourapp.com/pay/done'. Make that URL a
// universal / app link so the in-app browser closes and returns to your app.

// PayButton.tsx
import * as WebBrowser from 'expo-web-browser'
import { Button } from 'react-native'
import { router } from 'expo-router'
import { createCheckout } from './lib/checkout'

const CALLBACK_URL = 'https://yourapp.com/pay/done'   // the same callback_url your backend sends

export function PayButton(props: { email: string; amount: number; orderId: string }) {
  async function pay() {
    const { checkout_url, reference } = await createCheckout(props)
    // Opens the branded checkout in an in-app browser and closes it once the
    // customer lands on CALLBACK_URL?reference=...
    const result = await WebBrowser.openAuthSessionAsync(checkout_url, CALLBACK_URL)
    if (result.type === 'success') {
      router.push({ pathname: '/pay/done', params: { reference } })
    }
    // 'cancel' or 'dismiss': the customer closed the sheet. A payment may still have
    // completed, so let them re-check the order; the webhook will have fulfilled it.
  }
  return <Button title="Pay NGN 500" onPress={pay} />
}

// Prefer a WebView (react-native-webview)? Watch navigation for the callback:
//   <WebView source={{ uri: checkout_url }}
//     onNavigationStateChange={(s) => s.url.startsWith(CALLBACK_URL) &&
//       onDone(new URL(s.url).searchParams.get('reference'))} />

// app/pay/done.tsx - shows the result. Verify is for the UI only.
import { useEffect, useState } from 'react'
import { Text } from 'react-native'
import { useLocalSearchParams } from 'expo-router'

const BACKEND = 'https://yourapp.com'

export default function PayDone() {
  const { reference } = useLocalSearchParams<{ reference: string }>()
  const [status, setStatus] = useState('checking')

  useEffect(() => {
    fetch(BACKEND + '/api/checkout/' + reference)  // your backend calls GET /payments/verify/:reference
      .then((r) => r.json())
      .then((d) => setStatus(d.status))
  }, [reference])

  return <Text>{status === 'successful' ? 'Payment received' : 'Payment ' + status}</Text>
}
// Fulfil the order from the charge.success webhook on your backend, never from this screen.

// lib/checkout.dart - talks to YOUR backend, never to TwelveAI directly.
// Secret keys must never ship inside a mobile app. The server side of
// POST /api/checkout is in the Node, Python, PHP or Go tab.
import 'dart:convert';
import 'package:http/http.dart' as http;

const backend = 'https://yourapp.com';

Future<({String checkoutUrl, String reference})> createCheckout({
  required String email,
  required int amount, // kobo: 50000 = NGN 500.00
  required String orderId,
}) async {
  final r = await http.post(
    Uri.parse('$backend/api/checkout'),
    headers: {'Content-Type': 'application/json'},
    body: jsonEncode({'email': email, 'amount': amount, 'orderId': orderId}),
  );
  if (r.statusCode != 200) throw Exception('Could not start checkout');
  final body = jsonDecode(r.body) as Map<String, dynamic>;
  return (checkoutUrl: body['checkout_url'] as String, reference: body['reference'] as String);
}

// checkout_page.dart - webview_flutter; closes itself when the customer lands on callback_url
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';

const callbackUrl = 'https://yourapp.com/pay/done'; // the same callback_url your backend sends

/// Resolves with the reference once the customer reaches callback_url, or null if they close it.
Future<String?> openCheckout(BuildContext context, String checkoutUrl) {
  return Navigator.push<String>(context, MaterialPageRoute(builder: (ctx) {
    final controller = WebViewController()
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setNavigationDelegate(NavigationDelegate(onNavigationRequest: (req) {
        if (req.url.startsWith(callbackUrl)) {
          Navigator.pop(ctx, Uri.parse(req.url).queryParameters['reference']);
          return NavigationDecision.prevent;
        }
        return NavigationDecision.navigate;
      }))
      ..loadRequest(Uri.parse(checkoutUrl));
    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: WebViewWidget(controller: controller),
    );
  }));
}

// Prefer the system browser? url_launcher:
//   launchUrl(Uri.parse(checkoutUrl), mode: LaunchMode.externalApplication);
// and make callback_url an app link that reopens your app with ?reference=...

// pay_result.dart - shows the result. Verify is for the UI only.
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;

Future<void> showResult(BuildContext context, String reference) async {
  // Your backend calls GET /payments/verify/:reference with the secret key and returns { status }
  final r = await http.get(Uri.parse('$backend/api/checkout/$reference'));
  final status = (jsonDecode(r.body) as Map<String, dynamic>)['status'] as String;
  if (!context.mounted) return;
  ScaffoldMessenger.of(context).showSnackBar(SnackBar(
    content: Text(status == 'successful' ? 'Payment received' : 'Payment $status'),
  ));
}

// Putting it together in your pay button:
//   final c = await createCheckout(email: email, amount: 50000, orderId: '12345');
//   final reference = await openCheckout(context, c.checkoutUrl);
//   if (reference != null) await showResult(context, reference);
//
// Fulfil the order from the charge.success webhook on your backend, never from the app.

// server.js - the secret key lives in .env as TWELVEAI_SECRET_KEY and never leaves this process
import express from 'express'
const app = express()
const API = 'https://api.twelveai.app/api/business/v1'
const AUTH = { Authorization: 'Bearer ' + process.env.TWELVEAI_SECRET_KEY } // tw_test_... or tw_live_...

app.post('/api/checkout', express.json(), async (req, res) => {
  const { email, amount, orderId } = req.body
  const r = await fetch(API + '/payments/initialize', {
    method: 'POST',
    headers: { ...AUTH, 'Content-Type': 'application/json' },
    body: JSON.stringify({
      email,
      amount,                                   // kobo: 50000 = NGN 500.00
      reference: 'order-' + orderId,            // your own id, unique per payment
      callback_url: 'https://yourapp.com/pay/done',
      metadata: { order_id: orderId },
    }),
  })
  const { data } = await r.json()
  res.json({ checkout_url: data.checkout_url, reference: data.reference })
})

app.listen(3000)

<!-- any page on your site: ask YOUR backend for a checkout_url, then send the customer there -->
<button id="pay">Pay NGN 500</button>
<script>
  document.getElementById('pay').onclick = async () => {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'customer@example.com', amount: 50000, orderId: '12345' }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
  }
</script>

// Result page data: verify is for the UI only (your /pay/done page calls this)
app.get('/api/checkout/:reference', async (req, res) => {
  const r = await fetch(API + '/payments/verify/' + req.params.reference, { headers: AUTH })
  const { data } = await r.json()
  res.json({ status: data.status, paid: data.status === 'successful' })
})

// Webhook: the source of truth for fulfilling the order
import crypto from 'node:crypto'

app.post('/webhooks/twelve', express.raw({ type: '*/*' }), (req, res) => {
  const raw = req.body.toString('utf8')       // raw body, before any JSON parsing
  const expected = crypto.createHmac('sha512', process.env.TWELVEAI_WEBHOOK_SECRET).update(raw).digest('hex')
  const got = req.header('x-twelveai-signature') || ''
  if (got.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) {
    return res.sendStatus(401)
  }
  const ts = Number(req.header('x-twelveai-timestamp') || 0)
  if (Math.abs(Date.now() / 1000 - ts) > 300) return res.sendStatus(401)

  const eventId = req.header('x-twelveai-event-id')
  const { event, data } = JSON.parse(raw)
  res.sendStatus(200)                          // ack first, within 10 seconds
  queue.add('twelve-event', { eventId, event, data }) // then dedupe by eventId, fulfil once per data.reference
})

# main.py - the secret key lives in the environment as TWELVEAI_SECRET_KEY and never leaves this process
import os, httpx
from fastapi import FastAPI, Request, HTTPException, BackgroundTasks
from pydantic import BaseModel

app = FastAPI()
API = "https://api.twelveai.app/api/business/v1"
AUTH = {"Authorization": "Bearer " + os.environ["TWELVEAI_SECRET_KEY"]}  # tw_test_... or tw_live_...

class Checkout(BaseModel):
    email: str
    amount: int      # kobo: 50000 = NGN 500.00
    order_id: str

@app.post("/api/checkout")
async def checkout(body: Checkout):
    async with httpx.AsyncClient() as client:
        r = await client.post(f"{API}/payments/initialize", headers=AUTH, json={
            "email": body.email,
            "amount": body.amount,
            "reference": f"order-{body.order_id}",       # your own id, unique per payment
            "callback_url": "https://yourapp.com/pay/done",
            "metadata": {"order_id": body.order_id},
        })
    data = r.json()["data"]
    return {"checkout_url": data["checkout_url"], "reference": data["reference"]}

<!-- any page on your site: ask YOUR backend for a checkout_url, then send the customer there -->
<button id="pay">Pay NGN 500</button>
<script>
  document.getElementById('pay').onclick = async () => {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'customer@example.com', amount: 50000, orderId: '12345' }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
  }
</script>

import hmac, hashlib, time

# Result page data: verify is for the UI only (your /pay/done page calls this)
@app.get("/api/checkout/{reference}")
async def checkout_status(reference: str):
    async with httpx.AsyncClient() as client:
        r = await client.get(f"{API}/payments/verify/{reference}", headers=AUTH)
    status = r.json()["data"]["status"]
    return {"status": status, "paid": status == "successful"}

# Webhook: the source of truth for fulfilling the order
@app.post("/webhooks/twelve")
async def twelve_webhook(request: Request, tasks: BackgroundTasks):
    raw = await request.body()                   # raw bytes, before any parsing
    expected = hmac.new(os.environ["TWELVEAI_WEBHOOK_SECRET"].encode(), raw, hashlib.sha512).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("x-twelveai-signature", "")):
        raise HTTPException(401)
    if abs(time.time() - int(request.headers.get("x-twelveai-timestamp", "0"))) > 300:
        raise HTTPException(401)
    event_id = request.headers["x-twelveai-event-id"]
    tasks.add_task(process_event, event_id, await request.json())   # runs after the 200 is sent
    return {"ok": True}                          # ack within 10 seconds

def process_event(event_id: str, payload: dict):
    # 1. skip if event_id was already processed
    # 2. on charge.success, fulfil the order once per payload["data"]["reference"]
    ...

// routes/web.php - the secret key lives in .env (TWELVEAI_SECRET_KEY) via config/services.php
use Illuminate\Http\Request;
use Illuminate\Support\Facades\Http;

Route::post('/api/checkout', function (Request $request) {
    $orderId = $request->input('order_id');

    $data = Http::withToken(config('services.twelveai.secret'))   // tw_test_... or tw_live_...
        ->post('https://api.twelveai.app/api/business/v1/payments/initialize', [
            'email'        => $request->input('email'),
            'amount'       => (int) $request->input('amount'),   // kobo: 50000 = NGN 500.00
            'reference'    => "order-{$orderId}",                // your own id, unique per payment
            'callback_url' => url('/pay/done'),
            'metadata'     => ['order_id' => $orderId],
        ])
        ->json('data');

    return response()->json([
        'checkout_url' => $data['checkout_url'],
        'reference'    => $data['reference'],
    ]);
});

{{-- resources/views/pay.blade.php --}}
<button id="pay">Pay NGN 500</button>
<script>
  document.getElementById('pay').onclick = async () => {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json', 'X-CSRF-TOKEN': '{{ csrf_token() }}' },
      body: JSON.stringify({ email: 'customer@example.com', amount: 50000, order_id: '12345' }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
  }
</script>

// Result page: verify is for the UI only
Route::get('/pay/done', function (Request $request) {
    $data = Http::withToken(config('services.twelveai.secret'))
        ->get('https://api.twelveai.app/api/business/v1/payments/verify/' . $request->query('reference'))
        ->json('data');

    return view('pay-result', ['paid' => $data['status'] === 'successful', 'status' => $data['status']]);
});

// Webhook: the source of truth for fulfilling the order.
// Exclude this route from CSRF (VerifyCsrfToken::$except or ->withoutMiddleware()).
Route::post('/webhooks/twelve', function (Request $request) {
    $raw = $request->getContent();                                    // raw body, not $request->all()
    $expected = hash_hmac('sha512', $raw, config('services.twelveai.webhook_secret'));
    if (! hash_equals($expected, $request->header('x-twelveai-signature', ''))) {
        abort(401);
    }
    if (abs(time() - (int) $request->header('x-twelveai-timestamp', 0)) > 300) {
        abort(401);
    }

    ProcessTwelveEvent::dispatch($request->header('x-twelveai-event-id'), json_decode($raw, true));

    return response()->noContent(200);   // ack within 10 seconds; the job dedupes by event id
});

// main.go - net/http only; the secret key comes from the TWELVEAI_SECRET_KEY env var
package main

import (
	"bytes"
	"encoding/json"
	"net/http"
	"os"
)

const api = "https://api.twelveai.app/api/business/v1"

func checkout(w http.ResponseWriter, r *http.Request) {
	var in struct {
		Email   string `json:"email"`
		Amount  int    `json:"amount"`   // kobo: 50000 = NGN 500.00
		OrderID string `json:"order_id"`
	}
	json.NewDecoder(r.Body).Decode(&in)

	body, _ := json.Marshal(map[string]any{
		"email":        in.Email,
		"amount":       in.Amount,
		"reference":    "order-" + in.OrderID, // your own id, unique per payment
		"callback_url": "https://yourapp.com/pay/done",
		"metadata":     map[string]any{"order_id": in.OrderID},
	})
	req, _ := http.NewRequest("POST", api+"/payments/initialize", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TWELVEAI_SECRET_KEY")) // tw_test_... or tw_live_...
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		http.Error(w, err.Error(), http.StatusBadGateway)
		return
	}
	defer res.Body.Close()

	var out struct {
		Data struct {
			CheckoutURL string `json:"checkout_url"`
			Reference   string `json:"reference"`
		} `json:"data"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	json.NewEncoder(w).Encode(map[string]string{"checkout_url": out.Data.CheckoutURL, "reference": out.Data.Reference})
}

func main() {
	http.HandleFunc("/api/checkout", checkout)
	http.ListenAndServe(":3000", nil)
}

<!-- any page on your site: ask YOUR backend for a checkout_url, then send the customer there -->
<button id="pay">Pay NGN 500</button>
<script>
  document.getElementById('pay').onclick = async () => {
    const r = await fetch('/api/checkout', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ email: 'customer@example.com', amount: 50000, orderId: '12345' }),
    })
    const { checkout_url } = await r.json()
    window.location.href = checkout_url   // or window.open(checkout_url, '_blank')
  }
</script>

import (
	"crypto/hmac"
	"crypto/sha512"
	"encoding/hex"
	"io"
	"strconv"
	"strings"
	"time"
)

// Result page data: verify is for the UI only (your /pay/done page calls this)
func checkoutStatus(w http.ResponseWriter, r *http.Request) {
	ref := strings.TrimPrefix(r.URL.Path, "/api/checkout/")
	req, _ := http.NewRequest("GET", api+"/payments/verify/"+ref, nil)
	req.Header.Set("Authorization", "Bearer "+os.Getenv("TWELVEAI_SECRET_KEY"))
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	var out struct {
		Data struct {
			Status string `json:"status"`
		} `json:"data"`
	}
	json.NewDecoder(res.Body).Decode(&out)
	json.NewEncoder(w).Encode(map[string]any{"status": out.Data.Status, "paid": out.Data.Status == "successful"})
}

// Webhook: the source of truth for fulfilling the order
func twelveWebhook(w http.ResponseWriter, r *http.Request) {
	raw, _ := io.ReadAll(r.Body) // raw bytes, before any parsing
	mac := hmac.New(sha512.New, []byte(os.Getenv("TWELVEAI_WEBHOOK_SECRET")))
	mac.Write(raw)
	if !hmac.Equal([]byte(hex.EncodeToString(mac.Sum(nil))), []byte(r.Header.Get("x-twelveai-signature"))) {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	ts, _ := strconv.ParseInt(r.Header.Get("x-twelveai-timestamp"), 10, 64)
	if d := time.Now().Unix() - ts; d > 300 || d < -300 {
		w.WriteHeader(http.StatusUnauthorized)
		return
	}
	eventID := r.Header.Get("x-twelveai-event-id")
	w.WriteHeader(http.StatusOK)  // ack within 10 seconds
	go processEvent(eventID, raw) // then dedupe by eventID and fulfil once per data.reference
}
// main: http.HandleFunc("/api/checkout/", checkoutStatus); http.HandleFunc("/webhooks/twelve", twelveWebhook)