Ayoconnect's E-Wallet Management API enables partners to create and manage white-label e-wallet accounts for individual customers. ## Product Features

Create NON-KYC or KYC E-Wallet accounts using additionalInfo.accountType.
For KYC account creation, validate the required identity and KYC document references.
Update optional customer profile information, KYC documents, account status, and wallet balance.
Retrieve merchant master balance and individual account details.
Retrieve KYC documents securely from a merchant-hosted document endpoint.

## Account State Model | Field | Values | Meaning | |---|---|---| | accountType | NON-KYC, KYC | Determines the account type/tier and applicable product limits/features. | | accountStatus | ACTIVE, INACTIVE | Determines whether the account is operational. | Business onboarding is not supported through Account Creation or Update Account API. ## Update Account Behavior Update Account performs a partial update. Fields omitted from the request remain unchanged. partnerReferenceNo, customerId, and merchantId are required to identify the request and target account. At least one mutable field must be provided. name, phoneNo, and email are optional profile fields and have no KYC validation dependency. The API also supports KYC document renewal, merchant-requested account status update, additionalInfo1 updates, and wallet balance updates. Balance updates support two update types: | updateType | Behavior | Example | |---|---|---| | ADDITION | Adds the submitted value to the current balance. | Current balance 100,000 + update value 25,000 = 125,000 | | SUBTRACTION | Subtracts the submitted value from the current balance. | Current balance 100,000 - update value 25,000 = 75,000 | | PATCH | Replaces the current balance with the submitted value. | Current balance 100,000, update value 25,000 = new balance 25,000 | Balance monetary values remain strings with two decimal places, for example "25000.00". ## KYC Document Retrieval KYC documents remain hosted by the merchant. During onboarding, the merchant and Ayoconnect agree on a KYC Document Base URL, for example:

https://merchant-example.com/api/v1.0/kyc-documents

KYC Account Creation and optional Update Account KYC document renewal send document filenames/references only. Ayoconnect retrieves each document using:

GET {merchantKycDocumentBaseUrl}/{document_name.ext}
Authorization: Bearer <merchant-issued-access-token>

Example:

GET https://merchant-example.com/api/v1.0/kyc-documents/KYC-87cc19f3.png

The merchant must:

Allowlist Ayoconnect's agreed IP addresses.
Authenticate Ayoconnect using OAuth 2.0 Client Credentials.
Expose the document endpoint through HTTPS only.
Prevent public or unauthenticated document access.
Ensure document references are unique and non-predictable.
Validate document references and prevent path traversal.
Maintain document-access audit logs.
Return the document as binary content with the correct Content-Type.

KYC document binary/base64 content must not be included directly in Account Creation or Update Account JSON requests. ## Credentials Before starting integration, partners must ensure that they have all required credentials. Every partner receives a unique set of credentials from Ayoconnect during onboarding. | Credential | Description | Source | |---|---|---| | merchantId | 6-character merchant identifier unique to each merchant. | Provided by Ayoconnect. | | client_id | Unique client identifier used for token generation. | Provided by Ayoconnect. | | client_secret | Secret used to generate symmetric request signatures. | Provided by Ayoconnect. | | Public Key | RSA public key registered during onboarding. | Generated by the partner. | | Private Key | RSA private key used for asymmetric signature generation. | Generated by the partner. | ## Authentication All E-Wallet Management APIs require a B2B access token in the Authorization header, except Generate B2B Access Token itself.

Authorization: Bearer <b2b_token>

## Signature Generation Generate B2B Access Token uses SHA256withRSA:

stringToSign = client_ID + "|" + X-TIMESTAMP

E-Wallet Management transactional APIs use HMAC_SHA512:

stringToSign = HTTPMethod + ":" + URLPath + ":" + AccessToken + ":" + Lowercase(HexEncode(SHA-256(minify(RequestBody)))) + ":" + X-TIMESTAMP

## Balance and Account Detail Inquiry The Master Balance Inquiry follows the SNAP Balance Inquiry service concept and uses Service Code 11. It returns the merchant master account balance aggregated across the merchant's E-Wallet sub-accounts. The Account Detail Inquiry is an Ayoconnect extension using Service Code 81. It returns the complete stored account detail for the requested customerId. Identity document numbers are masked and never returned in full. ## Response Code Convention responseCode = HTTP Code + Service Code + Case Code Relevant service codes: | Service | Service Code | |---|---| | Account Creation | 06 | | Balance Inquiry / Master Balance | 11 | | Update Account (Ayoconnect extension) | 80 | | Account Detail Inquiry (Ayoconnect extension) | 81 | | Generate B2B Access Token | 73 |

200Successful API Response

401Unauthorized