|
|
|
|
|
|
⚠️ You may not have access to some functionalities due to your Access Role.
|
Search: |
|
|
|
|
1
|
This is the official API documentation for eVend Api
Below you will find a current list of the available methods for eVend Api.
This Documentation will guide you through integrating with our system. Should you require any help please contact our support team.
All APIs are hosted in the base URL below
Sandbox Base URL: https://sandboxapi.vendifydigital.com
Production Base URL: https://api.vendifydigital.com
|
|
2
|
Authentication
RSA authentication is used to protect our API by utilizing public-key cryptography. Each client is assigned a private key and a public key.
Your private key must be used to sign the combination of your API key and a nonce for every request to the API.
Generating X-Signature
For example, if your API Key is xyz and your generated request nonce is 123, you must concatenate these two values to form:
xyz123
This string must then be signed using your RSA private key. The signature generated from this process is unique to each client and request, and must be included in the request header as the X-Signature value.
Signature Algorithm
| Property |
Value |
| Hash algorithm |
SHA-256 |
| Signature scheme |
RSA with PKCS#1 v1.5 padding (also called RSA-SHA256 or SHA256withRSA) |
| Text encoding |
UTF-8 |
| Output format |
Base64-encoded signature |
Conceptually, the signature is:
X-Signature = Base64( RSA-SHA256( apiKey + nonce ) )
This matches standard RSA-SHA256 signing mechanisms available in most programming languages.
Validation on Our Server
Our API server verifies your signature using the public key stored in your configuration profile, ensuring that only authorized clients can access the API.
Each request must include:
X-Api-Key
X-Nonce
X-Signature
X-Wallet-Id (Please check Authorization Header documentation for more details)
API Configuration Details
Your API key, private key, and account-specific public key can be found in your API configuration profile.
For some endpoints, request payloads must also be encrypted using our public key before sending. Your unique public key for encryption is available in the same profile.
You may also generate your own RSA private–public key pair using any standard tool and upload your public key into your profile if you prefer.
To access the API Configuration Profile:
PORTAL TOOLS ➡️ Site Management ➡️ Api Configuration Keys
|
|
3
|
RSA is used for our API authorization, with X-Api-Key, X-Nonce, and X-Signature headers required in each request. These headers ensure that we identify your request and process it as an authenticated request.
Updated: 2nd March, 2025
| Item |
Required |
Description |
| X-Api-Key |
Yes |
The API key for authenticating the API request |
| X-Nonce |
Yes |
A unique nonce value to prevent replay attacks. You should ensure that this nonce is uniquely generated on every request. |
| X-Signature |
Yes |
The signature for the API request. You are required to sign your APIKey+Nonce and include the signature in this header. |
| X-Wallet-Id |
Yes |
This is the wallet Id of the currency you wish to use to transanct. |
| X-Currency-Id |
No |
The ID of the currency being used in the request. Our system may ignore it in some requests if not relevant. This is depreciated. Use X-Wallet-Id |
| X-Currency-Code |
No |
X-Currency-Code is the ISO code of the currency being used in the request. Our system may ignore it in some requests if not relevant. This is depreciated. Use X-Wallet-Id |
| X-User-Name |
No |
X-User-Name is an optional header parameter that carries the username of the logged-in person performing an API action. This helps the system to further track which user used an API end point. It is advisable that all your system user's are registered on system to have a unique username (where possible) |
Header Update: X-Wallet-Id
Use X-Wallet-Id, which replaces both X-Currency-Code and X-Currency-Id.
| Header |
Status |
Description |
| X-Wallet-Id |
New (Preferred) |
Represents the wallet identifier, replacing both X-Currency-Code and X-Currency-Id. |
| X-Currency-Id |
Deprecated
(Still Supported) |
Represents the currency identifier. Now replaced by X-Wallet-Id. |
| X-Currency-Code |
Deprecated
(Still Supported) |
Represents the currency code (e.g., USD, EUR). Now replaced by X-Wallet-Id. |
Recommendation:
Use X-Wallet-Id for new integrations.
X-Currency-Code and X-Currency-Id will continue to work but may be phased out in the future.
NOTE:
If you wish to track your API requests, the suplied X-Nonce is returned back to you in the API response header as Request-X-Nonce
You can get your API Key (X-Api-Key) and other details to sign your request by going to the tab:
PORTAL TOOLS ➡️ SITE MANAGEMENT ➡️ API CONFIGURATION KEY
You can get details on Wallet Id (X-Wallet-Id ) by going to the tab:
REPORTS ➡️ Wallet Details
You can get details on Country and Currency (X-Currency-Id and X-Currency-Code) by going to the tab:
REPORTS ➡️ COUNTRY & CURRENCY
PLEASE NOTE: The currency (wallet) details to use is the currency in which you wish to transact in. All products will be converted to the currency details you use in your request header.
|
|
4
|
Nonce value must be exactly 24 characters and numeric. Nonce is used in combination with your API Key to create RSA signature that must be present in all request header (X-Signature).
E.G. If your API Key is abcdefghijk, you will need to create a nonce such as 103923052000333868714818, then combine both and sign with your private key. I.e You will sign this string abcdefghijk103923052000333868714818 and include the signature in the X-Signature parameter in your request header.
Your nonce must consist of 4 sections(parts) that must be followed scrictly as described in the sample below for a nonce value of 103923052000333868714818 as an example.
| NoncePrefix |
DateInyyMMddFormat |
TimeInHHmmFormat |
RandomNumbers |
| 1039 |
230520 |
0033 |
3868714818 |
Description of each section/part of your nonce value:
| Sections |
Lenght |
Description |
| NoncePrefix |
4 |
This value is constant for all your requests. It can be found in your API Configuration page |
| DateInyyMMddFormat |
6 |
This is the request date in yyMMdd format e.g 230427 will be for 27th of April, 2023 |
| TimeInHHmmFormat |
4 |
This is the request time in HHmm format. (in 24hr syntax). E.g 0830 means 8.30am and 2315 means 11.15pm |
| RandomNumbers |
10 |
This should be a randomly generated 10 digits unique number. |
| The combination of all these parts form a valid 24 character nonce value. This nonce must be unique per request. |
You can get your API Key (X-Api-Key), NoncePrefix value and other details to sign your request by going to the tab:
PORTAL TOOLS ➡️ SITE MANAGEMENT ➡️ API CONFIGURATION KEY
Download sample codes to generate Signature (X-Signature) below
PLEASE NOTE:
In the sandbox enviroment, Nonce Uniqueness is not enforced in order to quicken your development. You can also generate sample X-Nonce value and corresponding X-Signature value to use for your development from your API CONFIGURATION KEY page.
SAMPLE CODE: Please contact our Support team if you need any sample code snippet for your development.
|
|
5
|
The following describes the Attributes of API response.
| Attribute |
Description |
| authenticated |
A boolean value indicating whether the request was authenticated or not. |
| sysDate |
The system date and time when the response was generated. |
| sysErr |
An integer indicating the system error code, if any. |
| sysId |
A unique system identifier for the request. |
| sessionUid |
A unique session identifier for the request session. |
| requestStatus |
The status of the request, such as "PROCESSED" or "FAILED". |
| message |
A brief message describing the status of the request. |
| response |
The response data, if any. |
|
|
6
|
Pricing Exchange Rate is set by the System Administrator.
When requesting a voucher/product in a specific currency, it is essential to note that if no product is displayed for that currency, it could mean that the exchange rate is not yet set for that particular currency pair.
In a scenario as such, please contact our support team and request that such exchange rate is set.
Please note that if an exchange rate is not set for a product with a converted product price, you will not be able to list or resell the product.
|
|
7
|
The API will respond with one of the following HTTP status codes.
| Status |
Response |
Description |
| 200 |
SUCCESS |
Request completed successfully. |
| 400 |
BAD_REQUEST |
The request was invalid or cannot be otherwise served. An accompanying error message will explain further. |
| 401 |
UNAUTHORIZED |
Authentication credentials were missing or incorrect. |
| 403 |
FORBIDDEN |
The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. |
| 404 |
NOT_FOUND |
The URI requested is invalid or the resource requested does not exists. |
| 405 |
METHOD_NOT_ALLOWED |
Method doesn't exist or is not allowed. |
| 429 |
TOO_MANY_REQUESTS |
Rate Limit Exceeded. Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource. See Rate Limiting. |
| 500 |
INTERNAL_SERVER_ERROR |
Something is broken |
|
|
8
|
The following table shows possible System Error or Feedback code. This value is stored in sysErr attribute of the API response.
| sysErr |
Description |
| 0 |
Request successfully executed |
| 200 |
Request successful |
| 1 |
Request Failed with Error. |
| -1 |
Unknown Error. Please try again or Contact System Administrator |
| -2 |
Missing or Invalid Api Key. |
| -3 |
Missing or Invalid Nonce. |
| -4 |
Missing or Invalid Currency Header. Check X-Currency-Id and X-Currency-Code |
| -5 |
Missing or Invalid Signature. |
| -6 |
Currency in request header (X-Currency-Id) must match the currency_Fk in request body. |
| -7 |
Invalid Product Name. (Min 3, Max 20 characters) |
| -8 |
Invalid Product Code. (Min 3, Max 7 characters) |
| -9 |
Invalid code. The input code contains a forward slash (/). |
| -10 |
Invalid Product Description. (Min 5, Max 200 characters) |
| -11 |
Invalid Product Value in the {amount} attribute. Must be valid number |
| -12 |
Invalid Product Expiration Date |
| -13 |
Request Failed with Error. |
| -14 |
This product does not belong to your business |
| -15 |
Invalid product Id |
| -16 |
Invalid Profile Configuration [RSLR] |
| -17 |
Invalid Profile Configuration [PRVD] |
| -18 |
Invalid Buyer Details. |
| -19 |
Invalid Beneficiary Details. |
| -20 |
Service Provider has not been assigned to your profile |
| -21 |
Invalid Nonce. Nonce used in each request must be unique (See Documentation). |
| -22 |
Invalid Nonce length. Length of Nonce parameter must be 24 characters (See Documentation). |
| -23 |
Invalid Nonce. Nonce used for search is invalid. |
| -24 |
Invalid Provider ID. Supplied Provider ID is invalid. |
| -25 |
Invalid Method Call. |
| -26 |
Invalid Commission Rate [RSL]. |
| -27 |
Invalid Commission Rate [PRVD]. |
| -28 |
Transaction Credit Limit Exceeded. |
| -29 |
Invalid Product - Provider Currently Not Available. |
| -30 |
Maximum daily limit set by Provider has been reached. |
| -31 |
You have reached your set Maximum daily limit. |
| -32 |
Voucher or Product value has changed. |
| -33 |
Voucher or Product has expired. |
| -34 |
The Product Commission rate is invalid. |
| -35 |
The Request Failed. Please try again later. |
| -36 |
The Request is invalid. Please check your configuration. |
| -37 |
The request is invalid. Please check the supplied category code. |
| -38 |
Invalid endpoint. Please use /orders endpoint to create a new order. |
| -39 |
Invalid request currency setting for this product. Please check your currency setting. |
| -40 |
Invalid product value. The requested value is not allowed. |
| -41 |
Invalid product request. |
| -42 |
Invalid Account Unique ID. Please check your request. |
| -43 |
Invalid Request Credentials. Please check your configuration or refresh your request. |
| -44 |
Invalid Product. Please check your request data. |
| -45 |
Error: Unable to validate your API Credentials. |
| -46 |
Invalid API key and/or Signature Key: Please ensure you have generated your API Key and Signature Key pair. |
| -47 |
Service provider is currently not available. Please try later or contact our support for more info. |
| -48 |
You do not have a default currency for your account. |
| -49 |
Invalid Wallet Id. |
| -50 |
Insufficient wallet balance. |
| -51 |
Invalid Currency Id. |
| -52 |
Invalid Currency Code. |
| -53 |
Invalid WalletId. |
| -54 |
Invalid Request. Check request headers. |
| -55 |
Invalid Beneficiary Phone Number. |
| -56 |
Invalid or Missing Service Code. |
| -57 |
Invalid or Missing Brand Code. |
| -58 |
Invalid or Missing Unique Account Id. |
| -59 |
Invalid or Missing Transaction Reference. |
| -60 |
Invalid Transaction Reference. |
| -61 |
sysId field is missing or invalid. |
| -62 |
sessionUid field is missing or invalid. |
| -63 |
Invalid Request Body. |
| -64 |
Invalid query parameter. |
| -65 |
Invalid character in Nonce value. |
| -66 |
Transaction Failed. |
| -67 |
You can only use either value or faceValue. |
| -68 |
You must provide either value or faceValue. |
| -69 |
Invalid Bank Wallet Account Number. |
| -70 |
Invalid Bank Wallet Bank Name. |
| -71 |
Invalid Bank Wallet IDP Username. |
| -72 |
Invalid Bank Wallet IDP User ID. |
| -73 |
Wallet KYC record not found. |
| -74 |
Requested record does not exist. |
| -75 |
Service Provider is currently unavailable. |
| -76 |
Access denied. IP not whitelisted. |
| -77 |
You can pass either requestTargetValue OR requestFaceValue, but not both. |
| -78 |
Product provider is currently not available. |
| -79 |
Invalid Request Endpoint. |
| -80 |
Transaction has been reversed. |
| -81 |
Transaction is still being processed. Please requery shortly. |
| -82 |
Please provide a valid UniqueAccount ID. |
| -83 |
Authentication Failed. |
| -84 |
Customer information could not be retrieved. |
| -85 |
Invalid customer telephone number. |
| -86 |
Invalid or Missing x-nonce for query. |
|
|
9
|
This endpoint allows you to get a list of all product categories
GET: /api/v1/Product/Categories
Sample Response:
{
"authenticated": true,
"sysDate": "2024-10-14T20:55:57.408Z",
"sysErr": 200,
"sysId": 241014205585143174,
"sessionUid": "S:IBSUITESYAVATSZSKHUUCGPQN",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": [
{
"id": 1,
"name": "Voucher",
"categoryCode": "Voucher",
"description": "Voucher"
},
{
"id": 2,
"name": "Gift Card",
"categoryCode": "GiftCard",
"description": "Gift Card"
},
{
"id": 3,
"name": "eSim",
"categoryCode": "eSim",
"description": "eSim"
},
{
"id": 4,
"name": "AirTime",
"categoryCode": "AirTime",
"description": "AirTime"
},
{
"id": 5,
"name": "Data",
"categoryCode": "Data",
"description": "Data"
},
{
"id": 6,
"name": "Utilities",
"categoryCode": "Utilities",
"description": "Utilities"
}
]
}
| Attribute |
Description |
| id |
The Product category ID |
| name |
The Product category name |
| categoryCode |
The Category Code. Use this value to pull products by category |
| description |
The Category Description |
|
|
10
|
This endpoint allows you to get list of all product countries
GET: /api/v1/Product/Countries
Sample Response:
{
"authenticated": true,
"sysDate": "2024-10-14T20:55:57.408Z",
"sysErr": 200,
"sysId": 241014205585143174,
"sessionUid": "S:IBSUITESYAVATSZSKHUUCGPQN",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": [
{
"id": 1,
"name": "Afghanistan",
"countryCode": "AFG",
"currencyCode": "AFN"
},
{
"id": 2,
"name": "Åland Islands",
"countryCode": "ALA",
"currencyCode": null
},
{
"id": 3,
"name": "Albania",
"countryCode": "ALB",
"currencyCode": "ALL"
},
{
"id": 4,
"name": "Algeria",
"countryCode": "DZA",
"currencyCode": "DZD"
},
{
"id": 5,
"name": "American Samoa",
"countryCode": "ASM",
"currencyCode": null
},
{
"id": 6,
"name": "AndorrA",
"countryCode": "AND",
"currencyCode": "EUR"
},
{
"id": 7,
"name": "Angola",
"countryCode": "AGO",
"currencyCode": "AON"
}
]
}
| Attribute |
Description |
| id |
A unique numeric identifier for the country or region |
| name |
The name of the country or region |
| countryCode |
The ISO 3166-1 alpha-3 code, a three-letter code representing the country. |
| currencyCode |
The ISO 4217 currency code for the country's official currency. If null, the currency is either undefined or unavailable. |
|
|
11
|
This endpoint allows you to get details of a voucher to validate basic details. Sensitive data of the voucher will be masked with *. This endpoint can be used to check voucher details and not to redeem vouchers.
GET: /api/v1/Voucher/{VoucherCode}
Sample Response
{
"authenticated": true,
"sysDate": "2024-10-21T14:16:39.178Z",
"sysErr": 200,
"sysId": 241021141655107634,
"sessionUid": "S:VVVZNSBIBABIFTGFFZMWMZCEZ",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": {
"voucherCode": "SXR**********UHK",
"qrCodeData": "",
"voucherAmount": 25000.0,
"currencyCode": "NGN",
"is_Redeemed": 0,
"transactionReference": "20241017101308oslgezjilrkgdhqhevmoqjngi",
"buyerFirstname": "John",
"buyerLastname": "Doe",
"buyerEmail": "suppo****************l.com",
"buyerTelephone": "+4********732",
"valueDate": "2024-10-17",
"valueTime": "10:13:08",
"isoDate": "2024-10-17T10:13:08.217Z",
"requestStatus": true,
"requestResponse": "Basic Voucher details retrieved.",
"beneficiaryEmail": "john*************.com",
"beneficiaryTelephone": "+2*********741",
"originalAmount": 25000.0,
"transactedAmount": 25000.0,
"originalCurrencyId": 160,
"transactedCurrencyId": 160,
"productName": "Voucher Christmas Package",
"productDescription": "Subscription payment during the Christmas holidays",
"productCode": "PRD089",
"productId": 321,
"providerName": "Vouchers Solutions Limited",
"providerBrandName": "VouchersSandbox",
"expirationDate": "2025-10-12",
"maskedVoucherCode": "SXR**********UHK",
"redemptionStatus": "Purchased. Not Redeemed",
"resellerName": "Sand************ Ltd",
"redemptionOption": 1
}
}
|
|
12
|
This endpoint allows you to get voucher status using the transaction reference number generated by the eVend portal at the point of purchase. Sensitive data of the voucher will be masked with *. This endpoint can be used to check basic voucher details and status.
GET: /api/v1/Voucher/Status/{TransactionReference}
Sample Response
{
"authenticated": true,
"sysDate": "2023-06-04T19:22:36.684Z",
"sysErr": 200,
"sysId": 230704192220204733,
"sessionUid": "S:GAGANUSTPGRXTBZKRIWZXIGMB",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": {
"providerName": "eVend Portal",
"transactionReference": "20230403110314ognwvpjdsuptmimjksjhyilce",
"maskedVoucherCode": "TJE*********ULE",
"isRedeemed": 0,
"redemptionStatus": "Purchased. Not Redeemed",
"currencyCode": "GBP",
"voucherAmount": 200.00,
"valueDate": "2023-04-14",
"expirationDate": "2024-04-08",
"beneficiaryEmail": "harry@vendifydigital.com",
"requestStatus": 1,
"requestComment": "Record Found"
}
}
Attribute Description
| Attribute |
Description |
| providerName |
This is the name of the voucher Service Provider |
| transactionReference |
This is a unique reference that was generated at the point of purchase of the voucher |
| maskedVoucherCode |
Masked Voucher Code to hide some part of the actual Voucher code for security reasons |
| isRedeemed |
0 means Not Redeemed. 1 means Redeemed |
| redemptionStatus |
Description of the status of the voucher |
| currencyCode |
Currency Code of the value paid for the voucher |
| voucherAmount |
Voucher value or amount |
| valueDate |
Date Voucher was purchased. |
| expirationDate |
Expiration Date of the voucher |
| beneficiaryEmail |
Email of the beneficiary of the voucher supplied during purchase |
| requestStatus |
1 means successffully pulled a record. 0 means record not found. |
| requestComment |
General comment about the API request and response |
|
|
13
|
This endpoint allows you to query a voucher transaction using the X-Nonce value that was used in the header to generate the voucher.
Please note that this end point will only return successful voucher details. If the request failed while attempting to generate a voucher such transactions, this end point will not return any record.
GET: /api/v1/Voucher/Nonce/{X-Nonce}
Sample Response
{
"authenticated": true,
"sysDate": "2023-07-05T21:14:02.029Z",
"sysErr": 200,
"sysId": 230705211407385504,
"sessionUid": "S:AUJZQOBNYJEDVVHKDBOXVOWTF",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": {
"voucherCode": "OVFARO***FEHCMG",
"voucherAmount": 100.0,
"currencyCode": "GBP",
"is_Redeemed": 0,
"transactionReference": "20230705193428txwqqqiivqamkqyrclmnggwtg",
"buyerFirstname": "Harry",
"buyerLastname": "Porter",
"buyerEmail": "harr***************l.com",
"buyerTelephone": "+4********677",
"valueDate": "2023-07-05",
"valueTime": "19:34:29",
"isoDate": "2023-07-05T19:34:29.195Z",
"requestStatus": true,
"requestResponse": "Basic Voucher details retrieved.",
"beneficiaryEmail": "info@vendifydigital.com",
"beneficiaryTelephone": "+4475***15677",
"originalAmount": 100.0,
"transactedAmount": 100.0,
"originalCurrencyId": 229,
"transactedCurrencyId": 229,
"productName": "OST-NG-100 Gift Card",
"providerName": "Online Service Terminal Ltd",
"expirationDate": "2024-06-29",
"maskedVoucherCode": "OVF*********CMG",
"redemptionStatus": "Purchased. Not Redeemed",
"resellerName": "Digiwave Reseller Ltd"
}
}
|
|
14
|
This endpoint allows you to get your account balance details by currency type.
GET: /api/v1/Report/AccountBalance
Sample Response
{
"authenticated": true,
"sysDate": "2023-04-09T12:54:12.049Z",
"sysErr": 200,
"sysId": 230409125443850421,
"sessionUid": "S:MJZQCMGEWECYVUCOZJXWQQVLP",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": [
{
"currencyId": "230",
"currencyCode": "USD",
"currencyCountry": "United States",
"accountBalance": "24,998.00"
},
{
"currencyId": "229",
"currencyCode": "GBP",
"currencyCountry": "United Kingdom",
"accountBalance": "-14,271.40"
},
{
"currencyId": "160",
"currencyCode": "NGN",
"currencyCountry": "Nigeria",
"accountBalance": "-123,490.56"
}
]
}
|
|
15
|
This endpoint allows you to get API Log for all transactions using the X-Nonce value that was used in the header. This will show the exact response from the server during the trasaction up to seven (7) years. Please Note that the value that is present in the response data will be different for different end point calls.
GET: /api/v1/Report/Transaction/Nonce/{X-Nonce}
Sample Response
{
"authenticated": true,
"sysDate": "2023-07-05T21:28:37.796Z",
"sysErr": 200,
"sysId": 230705212837204476,
"sessionUid": "S:IVHAMOXRVASICSWOIKXUICSAH",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": [
{
"requestDate": "2023-06-04",
"requestTime": "21:03:17",
"requestData": {
"location": "https://sandboxapi.vendifydigital.com/api/v1/reseller/providers",
"headers": [
{
"name": "Connection",
"value": "keep-alive"
},
{
"name": "Accept",
"value": "*/*"
},
{
"name": "X-Api-Key",
"value": "HGiphRnRMSicX1dzItCJTe+GJB2OICLIOzMArHfQi60="
},
{
"name": "X-Nonce",
"value": "105123070420576720628735"
},
{
"name": "X-Signature",
"value": "W9SHBgeXlxryPTIIAik0KAiTN8etsA"
},
{
"name": "X-Currency-Id",
"value": "229"
},
{
"name": "X-Currency-Code",
"value": "GBP"
}
],
"body": {}
},
"requestUri": "/api/v1/reseller/providers",
"requestIPAddress": "::1",
"responseComment": "REQUEST OK",
"responseData": {
"authenticated": true,
"sysDate": "2023-07-04T21:03:17.343Z",
"sysErr": 200,
"sysId": 230704210300476406,
"sessionUid": "S:BBNWSNBSMMYQPTILLSGCKNQAO",
"requestStatus": "PROCESSED",
"message": "REQUEST OK",
"response": [
{
"providerCode": "sandboxservicep",
"name": "Sandbox Service Provider Ltd",
"url": "www.servicep.com",
"description": "Sandbox Service Provider creates test vouchers for ",
"email": "www.servicep.com",
"telephone": "Sandbox Service Provider creates test vouchers for ",
"requestStatus": 1
}
]
}
}
]
}
| Attribute |
Description |
| requestDate |
The Date the request was made |
| requestTime |
The time the request was made |
| requestData |
The request that was passed to the end point |
| requestUri |
The end point that was callled |
| requestIPAddress |
The Server IP Address where the API call was made |
| responseComment |
The Comment for the transaction |
| responseData |
The response object that was passed to the client. Please note that the structure of this object will vary depending on the endpoint that was called. |
|
|
16
|
Webhook Manager
The Webhook Manager allows you to register and manage webhook URLs for real-time event notifications. It provides an interface where you can configure callback URLs for various system events such as account credit updates or exchange rate changes etc.
Access Path
You can access the Webhook Manager via your Client Portal under:
PORTAL TOOLS → Site Management → Webhook Mgmt
Overview
- The Webhook Manager enables you to register external URLs that can receive POST notifications from our system.
- Each webhook must be linked to one or more event types; for example, Exchange Rate Updated or Account Credited.
- The system automatically sends a POST request to the registered URL whenever the selected event occurs.
| Field |
Description |
| Event Type |
The trigger condition for the webhook, e.g., Exchange Rate Updated, Account Credited. |
| Webhook URL |
The external HTTPS endpoint where notifications will be posted. |
| Status |
Indicates whether the webhook is Active, or InActive. |
| Code |
The response status code received during the last test (must be 200 to activate) |
Important Notes
- Only URLs using HTTPS are supported for security reasons.
- The Webhook must pass the 200 OK test before it can be enabled.
- Webhook data payloads are sent in JSON format via POST requests.
- You can disable or delete a webhook at any time via the Webhook Manager interface.
|
|
17
|
What is IP Whitelisting?
IP Whitelisting restricts API access to approved IP addresses. When enabled by adding any IP, only requests from active whitelisted IPs are accepted.
What happens if no IP address is added?
If no active IP address is configured, API requests will be allowed from any IP address.
How do I add a new IP address?
Navigate to PORTAL TOOLS ➡️ Site Management ➡️ IP Whitelist
How do I deactivate an IP address?
Locate the IP in the Active IP list ➡️ Click Deactivate ➡️ Enter a remark ➡️ Confirm Deactivate. Once deactivated, the IP will no longer be allowed to access the API.
Can I edit or delete an IP address?
No. For security and audit purposes, IP whitelist records cannot be edited or deleted. If incorrect details were entered, deactivate the record and add a new IP.
When do changes take effect?
Changes usually take effect shortly after saving. In some cases, it may take a few minutes for the system security cache to refresh.
Why is my API request being rejected?
This may occur if the request is coming from a non-whitelisted IP, the IP was recently deactivated, or your network or VPN is using a different public IP.
How can I check which IP my request is coming from?
You may confirm your server’s outbound public IP or contact your network/infrastructure team for assistance.
Who can manage IP whitelist settings?
Only users with appropriate administrative permissions in the Admin Portal can add or deactivate IP addresses.
|
|
18
|
You can create multiple users on the platform. Before creating a user, it is important to understand the role to assign, as this determines what the user can see and do.
Available Roles
| Role |
Description |
| User |
Can log in and perform basic operations such as viewing reports and general activities. |
| Officer |
Can perform transactions on the platform, in addition to all capabilities available to a User. |
| Manager |
Can perform managerial actions such as creating and managing business units, along with all Officer permissions. |
| Executive |
Has access to high-level system activities and reports. This role is typically assigned to business executives. |
| Setup |
Administrative role with the ability to configure platform settings, manage system behaviour, and control features such as API settings. |
Creating a User
To create a new user, navigate to:
USER ADMIN → Manage User Profile → Create User Account
Understanding Role Access
To view detailed permissions for each role, visit:
HELP → Reseller/Provider Role Access
|
|
19
|
Rate Limiting and Efficient API Usage
To ensure platform stability and fair usage across all clients, the system monitors how frequently API endpoints are called.
If your integration makes repeated or inefficient requests, such as polling the same data at short intervals over a long period, you may receive a rate limit exception. This usually indicates that the integration approach is not optimised for how data should be retrieved from the platform.
Recommended Best Practices
| SN |
Guideline |
| 1 |
Avoid continuous polling of the same endpoint. |
| 2 |
Cache responses where appropriate to reduce repeated calls. |
| 3 |
Request data only when necessary. |
| 4 |
Design integrations to minimise repeated calls for unchanged data. |
If you encounter rate limiting, review your implementation approach. In many cases, improving efficiency will resolve the issue.
If you need assistance optimising your integration, please contact the support team for guidance.
|
|
|
