Account Upgrade

Overview

The Account Upgrade endpoint elevates a customer's wallet from a lower KYC tier (e.g., Tier 1) to a higher tier (e.g., Tier 3).

This process:

• Increases transaction limits significantly
• Strengthens identity verification for regulatory compliance
• Requires additional documentation (NIN, valid ID, proof of address)
• Validates identity using regulatory-approved documents

Prerequisites

• Existing Tier 1 wallet
• Customer's National Identification Number (NIN)
• Clear image of customer's BVN slip/card
• Valid government-issued ID (Driver's License, Int'l Passport, Voter's Card, NIN Slip)
• Recent utility bill as proof of address

---

Tier Comparison

Feature	Tier 1	Tier 3
Daily Transaction Limit	₦50,000	₦5,000,000
Daily Transfer Limit	₦50,000	₦5,000,000
Maximum Balance	₦300,000	₦5,000,000
Requirements	BVN + Face Verification	BVN + NIN + Valid ID + Proof of Address
Verification Time	Instant	1-2 business days

Why Upgrade?

Upgrade to Tier 3 to enable customers to:

• Make larger transactions
• Hold higher balances
• Access premium features
• Meet merchant requirements

---

Endpoint

POST /waas/Onboarding/upgradeAccount

---

Request Parameters

Required Headers

Header	Value
Authorization	Bearer <access_token>
Ocp-Apim-Subscription-Key	Your access subscription key
Content-Type	application/json

Request Body Fields

Field	Type	Required	Description
MerchantId	string	Yes	Your unique merchant identifier
requestId	string	Yes	Unique client-side reference for tracking
walletId	string	Yes	Customer's wallet/account number
nin	string	Yes	Customer's 11-digit National Identification Number
IdType	string	Yes	Type of ID document (e.g., passport)
IdNo	string	Yes	ID document number
IdImage	string	Yes	Base64-encoded PNG/JPEG of valid ID document
utilityBill	string	Yes	Base64-encoded PNG/JPEG of utility bill (max 3 months old)

Document Requirements

ID Image (Acceptable Documents)

• Driver's License (front and back)
• International Passport (data page)
• National ID Card (front and back)
• NIN Slip (from NIMC)
• Voter's Card

Utility Bill (Proof of Address)

• Issued within last 3 months
• Must show: Customer name, full address, date
• Acceptable bills: Electricity, water, waste management, phone/internet

---

Request Example

curl -X POST https://api-sandbox.accessbankplc.com/waas/Onboarding/upgradeAccount \
  -H "Authorization: Bearer <access_token>" \
  -H "Ocp-Apim-Subscription-Key: <subscription_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "MerchantId": "MRC123456",
    "requestId": "UPG-2025-001-12345",
    "walletId": "0702334455",
    "nin": "56617423316",
    "IdType": "passport",
    "IdNo": "A12345678",
    "IdImage": "iVBORw0KGgoAAAANSUhEUgAAAAUA...",
    "utilityBill": "iVBORw0KGgoAAAANSUhEUgAAAAUA..."
  }'

---

Response

Success Response

{
  "succeeded": true,
  "code": "200",
  "message": ":Request has been submitted for processing",
  "data": { },
  "pageMeta": {},
  "errors": {}
}
 

Review Process

Account upgrades are manually reviewed by the compliance team. This typically takes 1-2 business days.

You'll receive a webhook notification when the review is complete.

---

Webhook Notification

After review, you'll receive a webhook event:

Event Type

account.upgrade.status

Approved Payload

 {
  "event_id": "EVT_123456",
  "event_type": ""account_upgrade",
  "calltime": "2026-04-16T10:30:00Z",
  "data": {},
  "metadata": {
    "environment": "production",
    "retry_count": 0
  }
}

Common Rejection Reasons

retry: boolean field indicating whether this webhook is a retry attempt after a previous delivery failure.

Reason	Description	Action Required
ID Image is not clear	Photo is blurry or unreadable	Re-upload clearer image
Utility bill expired	Bill is older than 3 months	Upload recent bill
Name mismatch	Name on documents doesn't match BVN	Verify customer details
Invalid NIN	NIN doesn't match NIMC records	Verify NIN with customer
Incomplete document	Document is cropped or partial	Upload complete document

---

Next Steps

• Set up Webhook Events to receive upgrade status
• Implement retry mechanism for rejected upgrades
• Track upgrade completion rates for optimization

---