{"openapi":"3.1.0","info":{"title":"Arizona Global Bank API","version":"1.0.0","description":"Secure, provider-powered payments and financial technology. Financial services are provided through appropriately authorized third-party providers where available."},"servers":[{"url":"https://www.arizonaglobalbank.org","description":"Live staging host"}],"paths":{"/api/v1/payments":{"post":{"operationId":"payments","tags":["Gateway"],"summary":"Create a payment","description":"Create an idempotent sandbox payment and receive an Arizona-hosted checkout URL. Sandbox completion moves no real funds. Live mode fails closed without an authorized provider.","security":[{"publicKey":[],"secretKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique retry key for this payment request.","schema":{"type":"string"}}],"responses":{"201":{"description":"Successful response.","content":{"application/json":{"example":{"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"}}}}},"401":{"description":"API credentials are missing, invalid, or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"UNAUTHORIZED","message":"API credentials are missing, invalid, or inactive."}}}},"403":{"description":"The API key does not have the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FORBIDDEN","message":"The API key does not have the required scope."}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use POST."}}}},"409":{"description":"The key or customer reference conflicts with an existing request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"IDEMPOTENCY_CONFLICT","message":"The key or customer reference conflicts with an existing request."}}}},"503":{"description":"No authorized provider is configured for the selected gateway mode.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FEATURE_UNAVAILABLE","message":"No authorized provider is configured for the selected gateway mode."}}}}},"x-agb-availability":"sandbox","x-agb-scope":"payments:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"},"example":{"amountMinor":500000,"currency":"NGN","customerReference":"order_4021","email":"customer@example.com","callbackUrl":"https://merchant.example/paid"}}}}}},"/api/health":{"get":{"operationId":"health","tags":["Platform"],"summary":"Health and readiness","description":"Check application and database readiness without authentication.","security":[],"parameters":[],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"status":"ready","service":"arizona-global-bank-web","database":"connected","checkedAt":"2026-09-05T12:00:00.000Z"}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use GET."}}}},"503":{"description":"The application or database is not ready.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"SERVICE_UNAVAILABLE","message":"The application or database is not ready."}}}}},"x-agb-availability":"available"}},"/api/v1/banks":{"get":{"operationId":"banks","tags":["Banking"],"summary":"List supported banks","description":"Return banks supplied by the configured banking provider. Availability depends on configured provider credentials.","security":[{"publicKey":[],"secretKey":[]}],"parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166-1 alpha-2 country code. Defaults to NG.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"requestId":"req_01JABC123","code":"BANKS_RETRIEVED","data":[{"code":"044","name":"Access Bank"}]}}}},"401":{"description":"API credentials are missing, invalid, or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"UNAUTHORIZED","message":"API credentials are missing, invalid, or inactive."}}}},"403":{"description":"The API key does not have the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FORBIDDEN","message":"The API key does not have the required scope."}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use GET."}}}},"503":{"description":"The banking provider cannot currently serve the request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"PROVIDER_UNAVAILABLE","message":"The banking provider cannot currently serve the request."}}}}},"x-agb-availability":"sandbox","x-agb-scope":"banks:read"}},"/api/v1/verify-transaction/{customerReference}":{"get":{"operationId":"verify-transaction","tags":["Payments"],"summary":"Verify a transaction","description":"Read an existing transaction by your own customer reference. Redirects and provider acceptance do not prove payment.","security":[{"publicKey":[],"secretKey":[]}],"parameters":[{"name":"customerReference","in":"path","required":true,"description":"The exact reference your integration assigned to an existing transaction.","schema":{"type":"string"}}],"responses":{"200":{"description":"Successful response.","content":{"application/json":{"example":{"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"}}}}},"401":{"description":"API credentials are missing, invalid, or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"UNAUTHORIZED","message":"API credentials are missing, invalid, or inactive."}}}},"403":{"description":"The API key does not have the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FORBIDDEN","message":"The API key does not have the required scope."}}}},"404":{"description":"No transaction belongs to this business and reference.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"TRANSACTION_NOT_FOUND","message":"No transaction belongs to this business and reference."}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use GET."}}}},"503":{"description":"The application or database is unavailable.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"SERVICE_UNAVAILABLE","message":"The application or database is unavailable."}}}}},"x-agb-availability":"sandbox","x-agb-scope":"transactions:read"}},"/api/v1/virtual-account":{"post":{"operationId":"virtual-account","tags":["Banking"],"summary":"Create a virtual account","description":"This provider-dependent rail is not enabled. No successful response is advertised while this capability is gated.","security":[{"publicKey":[],"secretKey":[]}],"parameters":[],"responses":{"401":{"description":"API credentials are missing, invalid, or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"UNAUTHORIZED","message":"API credentials are missing, invalid, or inactive."}}}},"403":{"description":"The API key does not have the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FORBIDDEN","message":"The API key does not have the required scope."}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use POST."}}}},"503":{"description":"Virtual accounts are not currently enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FEATURE_UNAVAILABLE","message":"Virtual accounts are disabled pending provider, ledger, and reconciliation readiness."}}}}},"x-agb-availability":"unavailable","x-agb-scope":"virtual_accounts:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VirtualAccountRequest"},"example":{"customerId":"cus_2048","email":"customer@example.com"}}}}}},"/api/v1/payouts":{"post":{"operationId":"payouts","tags":["Transfers"],"summary":"Create a payout","description":"This provider-dependent rail is not enabled. No successful response is advertised while this capability is gated.","security":[{"publicKey":[],"secretKey":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique retry key for this payout request.","schema":{"type":"string"}}],"responses":{"401":{"description":"API credentials are missing, invalid, or inactive.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"UNAUTHORIZED","message":"API credentials are missing, invalid, or inactive."}}}},"403":{"description":"The API key does not have the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FORBIDDEN","message":"The API key does not have the required scope."}}}},"405":{"description":"Method not allowed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"METHOD_NOT_ALLOWED","message":"Method not allowed. Use POST."}}}},"409":{"description":"The key was already used with a different request body.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"IDEMPOTENCY_CONFLICT","message":"The key was already used with a different request body."}}}},"503":{"description":"Payouts are not currently enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"requestId":"req_01JABC123","code":"FEATURE_UNAVAILABLE","message":"Payouts are disabled pending ledger migration and provider configuration."}}}}},"x-agb-availability":"unavailable","x-agb-scope":"payouts:write","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutRequest"},"example":{"amountMinor":1000000,"currency":"NGN","bankCode":"058","accountNumber":"0123456789","customerReference":"payout_2048"}}}}}}},"webhooks":{"paymentStatus":{"post":{"summary":"Payment status event delivered to the merchant HTTPS endpoint.","parameters":[{"name":"x-arizona-signature","in":"header","required":true,"schema":{"type":"string"},"description":"Lowercase hexadecimal HMAC-SHA256 of the raw body."}],"requestBody":{"required":true,"content":{"application/json":{"example":{"eventId":"evt_01JABC123","type":"payment.success","createdAt":"2026-09-05T12:00:00.000Z","data":{"customerReference":"order_4021","status":"SUCCESS"}}}}},"responses":{"200":{"description":"Merchant acknowledged the event."}}}}},"components":{"schemas":{"Error":{"type":"object","required":["requestId","code","message"],"additionalProperties":false,"properties":{"requestId":{"type":"string","example":"req_01JABC123"},"code":{"type":"string","example":"UNAUTHORIZED"},"message":{"type":"string","example":"API credentials are required."}}},"Money":{"type":"object","required":["amountMinor","currency"],"properties":{"amountMinor":{"type":"integer","minimum":1},"currency":{"type":"string","pattern":"^[A-Z]{3}$"}}},"VirtualAccountRequest":{"type":"object","additionalProperties":false,"required":["customerId","email"],"properties":{"customerId":{"type":"string"},"email":{"type":"string","format":"email"}}},"PayoutRequest":{"type":"object","additionalProperties":false,"required":["amountMinor","currency","bankCode","accountNumber","customerReference"],"properties":{"amountMinor":{"type":"integer","minimum":1},"currency":{"type":"string","example":"NGN"},"bankCode":{"type":"string"},"accountNumber":{"type":"string"},"customerReference":{"type":"string"}}},"PaymentRequest":{"type":"object","additionalProperties":false,"required":["amountMinor","currency","customerReference","email","callbackUrl"],"properties":{"amountMinor":{"type":"integer","minimum":1},"currency":{"type":"string","enum":["NGN"]},"customerReference":{"type":"string"},"email":{"type":"string","format":"email"},"callbackUrl":{"type":"string","format":"uri"}}}},"securitySchemes":{"publicKey":{"type":"apiKey","in":"header","name":"x-public-key"},"secretKey":{"type":"apiKey","in":"header","name":"x-secret-key"}}}}