Staging API · provider-powered

Build secure financial experiences with clear, honest APIs.

Explore typed contracts, exact payment verification rules, signed webhooks and safely gated production capabilities.

Start integrating OpenAPI JSON

Scoped credentials

Backend-only keys with explicit capabilities.

Verified events

Signed delivery with duplicate-safe processing.

Safety gates

Unavailable rails cannot be executed from the console.

Integration guides

Quickstart

Sign in at /login, then open Dashboard → Developers → API Keys. Create a scoped key and save its secret immediately: secret keys are shown once. Send API requests only from your backend.

Authentication and scopes

Send agb_pk_ in x-public-key and agb_sk_ in x-secret-key. Available scopes are banks:read, transactions:read, virtual_accounts:write, and payouts:write. A missing scope returns a 403 FORBIDDEN error.

Idempotency

Send Idempotency-Key on payout requests and other retryable mutations. Reusing a key with a changed body returns 409 IDEMPOTENCY_CONFLICT.

Webhooks

Register an HTTPS endpoint in Dashboard → Developers → Webhook Endpoints. Verify x-arizona-signature as a lowercase hexadecimal HMAC-SHA256 digest of the unchanged raw HTTP body, using the endpoint signing secret shown once during setup. Events are payment.success and payment.failed. Example: {"eventId":"evt_01J...","type":"payment.success","createdAt":"2026-09-05T12:00:00.000Z","data":{"customerReference":"order_4021","status":"SUCCESS"}}. Reject invalid signatures and ignore duplicate eventId values.

Errors

Every API error contains exactly requestId, code, and a safe message. Use requestId when contacting support.

API v1

Endpoint reference

POSTsandboxpayments:write

Create a payment

Create an idempotent sandbox payment and receive an Arizona-hosted checkout URL.

/api/v1/payments
Readiness: Sandbox completion moves no real funds. Live mode fails closed without an authorized provider.

Parameters

Idempotency-Key
string · required

Unique retry key for this payment request.

amountMinor
integer · required

Positive amount in kobo.

currency
string · required

NGN for this staging release.

customerReference
string · required

Unique merchant order reference.

email
string · required

Customer email.

callbackUrl
string · required

HTTPS merchant return URL. A redirect never proves payment.

curl --request POST \
  --url 'https://www.arizonaglobalbank.org/api/v1/payments' \
  --header 'x-public-key: agb_pk_your_public_key' \
  --header 'x-secret-key: agb_sk_your_secret_key' \
  --header 'Idempotency-Key: payment_order_4021' \
  --header 'content-type: application/json' \
  --data '{"amountMinor":500000,"currency":"NGN","customerReference":"order_4021","email":"customer@example.com","callbackUrl":"https://merchant.example/paid"}'

Successful response

{
  "requestId": "req_01JABC123",
  "code": "PAYMENT_CREATED",
  "data": {
    "internalReference": "txn_66d9e21",
    "customerReference": "order_4021",
    "amountMinor": 500000,
    "currency": "NGN",
    "status": "PENDING",
    "checkoutUrl": "https://www.arizonaglobalbank.org/pay/order_4021"
  }
}

Errors

401 UNAUTHORIZED

API credentials are missing, invalid, or inactive.

403 FORBIDDEN

The API key does not have the required scope.

409 IDEMPOTENCY_CONFLICT

The key or customer reference conflicts with an existing request.

503 FEATURE_UNAVAILABLE

No authorized provider is configured for the selected gateway mode.

Open in console
GETavailable

Health and readiness

Check application and database readiness without authentication.

/api/health
curl --request GET \
  --url 'https://www.arizonaglobalbank.org/api/health'

Successful response

{
  "status": "ready",
  "service": "arizona-global-bank-web",
  "database": "connected",
  "checkedAt": "2026-09-05T12:00:00.000Z"
}

Errors

503 SERVICE_UNAVAILABLE

The application or database is not ready.

Open in console
GETsandboxbanks:read

List supported banks

Return banks supplied by the configured banking provider.

/api/v1/banks
Readiness: Availability depends on configured provider credentials.

Parameters

country
string · optional

ISO 3166-1 alpha-2 country code. Defaults to NG.

curl --request GET \
  --url 'https://www.arizonaglobalbank.org/api/v1/banks' \
  --header 'x-public-key: agb_pk_your_public_key' \
  --header 'x-secret-key: agb_sk_your_secret_key'

Successful response

{
  "requestId": "req_01JABC123",
  "code": "BANKS_RETRIEVED",
  "data": [
    {
      "code": "044",
      "name": "Access Bank"
    }
  ]
}

Errors

401 UNAUTHORIZED

API credentials are missing, invalid, or inactive.

403 FORBIDDEN

The API key does not have the required scope.

503 PROVIDER_UNAVAILABLE

The banking provider cannot currently serve the request.

Open in console
GETsandboxtransactions:read

Verify a transaction

Read an existing transaction by your own customer reference. Redirects and provider acceptance do not prove payment.

/api/v1/verify-transaction/{customerReference}

Parameters

customerReference
string · required

The exact reference your integration assigned to an existing transaction.

curl --request GET \
  --url 'https://www.arizonaglobalbank.org/api/v1/verify-transaction/{customerReference}' \
  --header 'x-public-key: agb_pk_your_public_key' \
  --header 'x-secret-key: agb_sk_your_secret_key'

Successful response

{
  "requestId": "req_01JABC123",
  "code": "TRANSACTION_FOUND",
  "data": {
    "internalReference": "66d9e21...",
    "customerReference": "order_4021",
    "providerReference": null,
    "currency": "NGN",
    "amountMinor": 500000,
    "status": "PENDING",
    "createdAt": "2026-09-05T12:00:00.000Z"
  }
}

Errors

401 UNAUTHORIZED

API credentials are missing, invalid, or inactive.

403 FORBIDDEN

The API key does not have the required scope.

404 TRANSACTION_NOT_FOUND

No transaction belongs to this business and reference.

503 SERVICE_UNAVAILABLE

The application or database is unavailable.

Open in console
POSTunavailablevirtual_accounts:write

Create a virtual account

This provider-dependent rail is not enabled.

/api/v1/virtual-account
Readiness: No successful response is advertised while this capability is gated.

Parameters

customerId
string · required

Your stable customer identifier.

email
string · required

Verified customer email address.

curl --request POST \
  --url 'https://www.arizonaglobalbank.org/api/v1/virtual-account' \
  --header 'x-public-key: agb_pk_your_public_key' \
  --header 'x-secret-key: agb_sk_your_secret_key' \
  --header 'content-type: application/json' \
  --data '{"customerId":"cus_2048","email":"customer@example.com"}'

Current 503 response

{
  "requestId": "req_01JABC123",
  "code": "FEATURE_UNAVAILABLE",
  "message": "Virtual accounts are disabled pending provider, ledger, and reconciliation readiness."
}

Errors

401 UNAUTHORIZED

API credentials are missing, invalid, or inactive.

403 FORBIDDEN

The API key does not have the required scope.

503 FEATURE_UNAVAILABLE

Virtual accounts are not currently enabled.

Console unavailable
POSTunavailablepayouts:write

Create a payout

This provider-dependent rail is not enabled.

/api/v1/payouts
Readiness: No successful response is advertised while this capability is gated.

Parameters

Idempotency-Key
string · required

Unique retry key for this payout request.

amountMinor
integer · required

Positive amount in kobo.

currency
string · required

ISO currency code; initially NGN.

bankCode
string · required

Provider bank code from the banks endpoint.

accountNumber
string · required

Destination account number.

customerReference
string · required

Unique reference assigned by your integration.

curl --request POST \
  --url 'https://www.arizonaglobalbank.org/api/v1/payouts' \
  --header 'x-public-key: agb_pk_your_public_key' \
  --header 'x-secret-key: agb_sk_your_secret_key' \
  --header 'Idempotency-Key: payout_2048' \
  --header 'content-type: application/json' \
  --data '{"amountMinor":1000000,"currency":"NGN","bankCode":"058","accountNumber":"0123456789","customerReference":"payout_2048"}'

Current 503 response

{
  "requestId": "req_01JABC123",
  "code": "FEATURE_UNAVAILABLE",
  "message": "Payouts are disabled pending ledger migration and provider configuration."
}

Errors

401 UNAUTHORIZED

API credentials are missing, invalid, or inactive.

403 FORBIDDEN

The API key does not have the required scope.

409 IDEMPOTENCY_CONFLICT

The key was already used with a different request body.

503 FEATURE_UNAVAILABLE

Payouts are not currently enabled.

Console unavailable

Changelog

API contracts now distinguish availability, integer minor-unit amounts and normalized lifecycle states.

Platform status

Application and database readiness are available through the health endpoint.

Developer support

Contact support@arizonaglobalbank.org with the safe request ID—never send secret keys.