# Payments OpenAPI Specification The DukaExpress Payments API provides a unified interface for payment processing, including payment intents, captures, refunds, payouts, ledger balance queries, and webhook management. The API is built on REST principles with JSON request/response bodies and OAuth 2.0 Bearer token authentication. ## Base URL All API requests are made to: {`https://api.dukaexpress.com/v1`} ## Authentication The Payments API requires OAuth 2.0 Bearer tokens issued by the identity-svc. Include the token in the Authorization header of every request: {`Authorization: Bearer `} Tokens are obtained via the identity-svc OAuth 2.0 token endpoint: {`POST https://api.dukaexpress.com/v1/auth/login Content-Type: application/json { "email": "merchant@example.com", "password": "SecureP@ss123" }`} ## Nedbank API Categories The Payments API integrates with 7 Nedbank API categories to provide comprehensive payment capabilities: ## Interactive API Reference ## Security Requirements - All endpoints require TLS 1.3 encryption in transit - Bearer JWT tokens must be obtained from identity-svc OAuth 2.0 endpoint - Tokens include merchant context, user roles, and permissions - Webhook endpoints validate the `X-Nedbank-Signature` header using HMAC-SHA256 - No PAN (Primary Account Number) data is stored — all card data is tokenized at the gateway - All mutation endpoints require an `Idempotency-Key` header to prevent duplicate operations - PCI DSS scope is reduced to SAQ-A through gateway-side tokenization ## Error Response Format All error responses follow a consistent format: {`{ "error": { "code": "INSUFFICIENT_BALANCE", "message": "Merchant does not have sufficient available balance for this payout", "details": { "availableBalance": 8500.00, "requestedAmount": 12500.00, "currency": "ZAR" }, "requestId": "req_01HX7K9M2N3P4Q5R6S7T8U9V" } }`} ### Error Codes