Overview

The Access Bank Wallet-as-a-Service (WaaS) API uses Bearer token authentication to secure all API requests.

Before making any API calls, you must first obtain an access token by authenticating with your client credentials. This token must be included in the Authorization header of all subsequent requests.

---

Authentication Flow

---

Merchant Credentials

Each merchant is issued unique credentials upon onboarding:

Credential	Description	Usage
Merchant ID	Unique identifier for your organization	Sent in request body
Authorization Key	Secret key for authentication	Sent in request header

Security Notice

Never expose your Authorization Key in client-side code, public repositories, or logs. Store it securely using environment variables or secret management systems.

---

Obtaining an Access Token

Endpoint

POST /waas/Client/authenticate

Request Headers

Key	Value	Required
Authorization	Your client-specific secret key	Yes
Ocp-Apim-Subscription-Key	Your access subscription key	Yes
Content-Type	application/json	Yes

Request Body

Field	Type	Required	Description
merchantId	string	Yes	Your unique merchant identifier

Example Request

curl -X POST https://api-sandbox.accessbankplc.com/waas/Client/authenticate \
  -H "Authorization: YOUR_AUTHORIZATION_KEY" \
  -H "Ocp-Apim-Subscription-Key: YOUR_SUBSCRIPTION_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchantId": "YOUR_MERCHANT_ID"
  }'

Response

Success Response

{
  "succeeded": true,
  "code": "200",
  "message": "Authentication successful",
  "data": {
    "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresIn": 120
  },
  "pageMeta": {},
  "errors": {}
}

Response Fields

Field	Type	Description
accessToken	string	Bearer token to use for API requests
expiresIn	integer	Token validity duration in seconds (typically 120 = 2 minutes)

---

Using the Access Token

Once you have obtained an access token, include it in the Authorization header of all API requests:

Authorization: Bearer <accessToken>

Example Authenticated Request

curl -X POST https://api-sandbox.accessbankplc.com/waas/Onboarding/loadWallet \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000.00
  }'

---

Token Expiration & Renewal

Expiration Handling

Tokens are time-bound and will expire after the duration specified in expiresIn (typically 2 minutes).

When a token expires, API requests will fail with:

{
  "succeeded": false,
  "code": "401",
  "message": "Unauthorized",
  "data": {},
  "pageMeta": {},
  "errors": {}
}

---

Common Authentication Errors

Code	Message	Cause	Solution
401	Unauthorized	Invalid or missing Authorization Key	Verify your Authorization Key is correct
401	Unauthorized	Token expired	Re-authenticate to obtain a new token
400	Bad Request	Missing or invalid merchantId	Ensure merchantId is provided and correct
403	Forbidden	Client account suspended	Contact Access Bank support

---

Security Recommendations

1. Never hardcode credentials - Use environment variables or secure vaults
2. Use HTTPS only - All requests must use TLS 1.2 or higher
3. Implement token caching - Avoid unnecessary authentication requests
4. Monitor for suspicious activity - Log all authentication attempts
5. Restrict access - Limit who can access your credentials

Production Checklist

Before going live:

• ✅ Credentials stored securely (not in code)
• ✅ Token refresh logic implemented
• ✅ Error handling for 401 responses
• ✅ Logging and monitoring in place
• ✅ Production credentials obtained (not sandbox)

---