Public docs

Build controlled Paystack and AI-agent execution.

Use Azums when a backend, webhook, or AI agent needs to request Paystack payment verification, transfers, refunds, receipts, callbacks, reconciliation, and approval-aware execution without building the correctness layer yourself.

Direct API

Your backend submits typed Paystack payment verification, transfer, or refund requests. Azums handles idempotency, policy, approval, dispatch, receipts, callbacks, and reconciliation.

AI-agent gateway

Your agent runtime asks for a financial action. Azums converts it into the same controlled lifecycle and pauses high-risk actions for approval.

Shared truth

API and AI actions land in the same transaction model, so receipts, callbacks, reconciliation, exceptions, and audit evidence stay consistent.

1. Create API key

Generate a test key from the customer console.

2. Choose Paystack action

Verify payment, create transfer, or create refund.

3. Policy runs

Azums checks limit, environment, actor, and approval rules.

4. Inspect proof

Review transaction timeline, receipt, callback, and reconciliation.

Hosted Paystack connector

Azums controls execution only after the workspace connects Paystack safely.

The launch model is hosted connector: the workspace owner adds a Paystack secret key, Azums encrypts it, scopes it to demo or live, and uses it only when policy allows execution.

Demo default

Use test keys only. No real money movement.

Live activation

Live mode executes real financial actions. Billing and live usage apply.

Strict key separation

Test Azums API keys cannot run live actions. Live keys cannot run demo actions.

Workspace admin approval

Customer workspace admins approve customer actions. Platform admins do not approve financial actions.

Direct API

Paystack actions through one execution lifecycle.

Every request should include an idempotency key. Replays with the same key and same payload return the same transaction. Reusing the key with a different amount, currency, action, or reference must conflict.

Paystack payment verification

copy-safe example

curl -X POST https://api.getazums.com/api/requests \
  -H "authorization: Bearer <AZUMS_API_KEY>" \
  -H "idempotency-key: verify-payment-ord-1001-v1" \
  -H "content-type: application/json" \
  -d '{
    "intent_kind": "paystack.transaction.verify.v1",
    "payload": {
      "reference": "paystack_payment_ref_123"
    }
  }'

Paystack transfer

copy-safe example

curl -X POST https://api.getazums.com/api/requests \
  -H "authorization: Bearer <AZUMS_API_KEY>" \
  -H "idempotency-key: transfer-vendor-2044-v1" \
  -H "content-type: application/json" \
  -d '{
    "intent_kind": "paystack.transfer.create.v1",
    "payload": {
      "recipient": "RCP_paystack_recipient_code",
      "amount": 500000,
      "currency": "NGN",
      "reason": "Vendor payout for invoice INV-2044"
    }
  }'

Paystack refund

copy-safe example

curl -X POST https://api.getazums.com/api/requests \
  -H "authorization: Bearer <AZUMS_API_KEY>" \
  -H "idempotency-key: refund-ord-1001-v1" \
  -H "content-type: application/json" \
  -d '{
    "intent_kind": "paystack.refund.create.v1",
    "payload": {
      "payment_reference": "paystack_payment_ref_123",
      "amount": 250000,
      "currency": "NGN",
      "reason": "Customer return approved by support"
    }
  }'

AI-agent gateway

Let agents request. Do not let agents bypass control.

The gateway receives structured agent requests, maps them to Paystack actions, evaluates policy, and pauses high-risk work for approval before provider execution.

Example: an AI refund above the workspace limit creates an approval. Provider execution does not begin until an admin approves once.

AI Paystack refund request

copy-safe example

curl -X POST https://api.getazums.com/api/agent/gateway/requests \
  -H "authorization: Bearer <AZUMS_AGENT_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "agent_id": "refund_assistant",
    "runtime_identity": "support-agent-runtime",
    "structured_action": {
      "action_request_id": "act_refund_1001",
      "intent_type": "refund",
      "adapter_type": "adapter_paystack",
      "payload": {
        "payment_reference": "paystack_payment_ref_123",
        "amount": 600000,
        "currency": "NGN"
      },
      "idempotency_key": "agent-refund-1001-v1",
      "requested_scope": ["refunds"],
      "reason": "Customer requested a high-value refund"
    }
  }'

AI Paystack transfer request

copy-safe example

curl -X POST https://api.getazums.com/api/agent/gateway/requests \
  -H "authorization: Bearer <AZUMS_AGENT_KEY>" \
  -H "content-type: application/json" \
  -d '{
    "agent_id": "payout_assistant",
    "runtime_identity": "ops-agent-runtime",
    "structured_action": {
      "action_request_id": "act_transfer_2044",
      "intent_type": "transfer",
      "adapter_type": "adapter_paystack",
      "payload": {
        "recipient": "RCP_paystack_recipient_code",
        "amount": 500000,
        "currency": "NGN",
        "reason": "Vendor payout"
      },
      "idempotency_key": "agent-transfer-2044-v1",
      "requested_scope": ["payments"],
      "reason": "Agent requested vendor payout"
    }
  }'

Lifecycle states

Execution outcome, reconciliation, callback delivery, approval, and billing are separate dimensions. A successful refund can still create a reconciliation exception.

Callbacks

Callbacks report state changes to your system. Callback delivery failure does not change execution truth.

{
  "transaction_id": "AZ-TXN-0002",
  "rail": "paystack",
  "action": "refund",
  "execution_outcome": "pending",
  "reconciliation": "pending",
  "receipt_url": "https://app.getazums.com/app/receipts/..."
}

What to inspect

Transaction timeline
Approval decision and reason
Provider reference
Receipt hash
Callback attempts
Reconciliation result
Exception report if truth disagrees

Start in demo, prove the lifecycle, then activate live deliberately.

Demo mode uses Paystack test keys only and moves no real money. Live mode requires billing, approval email, live connector, callback choice, and risk confirmation before real financial execution is available.

Create workspace Open console