Certainly! Below is an extended section on how a merchant can use the ALATPay API to register new businesses.
Please note: Before embarking on performing API integration to onboard your businesses, ensure to create your ONBOARDING CALLBACK WEBHOOK
Event: update_business_onboarding callback
Endpoint: BaseURL/merchant-onboarding/api/v1/merchants/update-business-callback/{merchantId}
Method: PUT
Content-Type: application/json
"https://www.callback-url.com" //Required
Success Response
{
"data": true,
"status": true,
"message": "Successfully updated"
}
Error Response
{
"data": null,
"status": false,
"message": "No merchant found"
}
Event: business_onboarding
Endpoint: BaseURL/merchant-onboarding/api/v1/merchants/{merchantId}/addUnRegisteredBusiness
Method: POST
Content-Type: application/json
PS: All properties are required
{
"name": "string",//Required
"businessAddress": {
"houseNumber": 0,//Required
"streetName": "string",//Required
"country": "string",//Required
"houseAddress": {
"houseNumber": 0,//Required
"streetName": "string",//Required
"country": "string",//Required
"nearestLandMark": "string",//Required
"state": "string",//Required
"lga": "string",//Required
"city": "string"//Required
},
"nearestLandMark": "string",//Required
"state": "string",//Required
"lga": "string",//Required
"city": "string",//Required
"lcda": "string"//Required
},
"paymentMethodIds": "string",//Required (1,2,3,4,5 or *)
"businessProjectionCurrency": "string",//Required
"businessProjectionValue": 0,//Required
"category": "string",//Required
"callbackUrl": "string",//Required
"setUpUrl": "string",//Required
"businessWebsiteUrl": "string",//Required
"businessDescription": "string",//Required
"phoneNumber": "string",//Required
"nin": "string"//Required
}
Event: business_onboarding
Endpoint: BaseURL/merchant-onboarding/api/v1/unregistered-business/{merchantId}/validate-otp/{otp}
Method: POST
Content-Type: application/json
{
"nin": "string", //Required
"MerchantBusinessId": "String",//Required
}
Success Response
{
"data": object,
"status": true,
"message": "OTP successfully validated"
}
Error Response
{
"data": null,
"status": false,
"message": "Failed to validate OTP"
}
Event: business_onboarded
Endpoint: BaseURL/merchant-onboarding/api/v1/merchants/{merchantID}/business-onboarding
Method: POST
Content-Type: application/json
{
"name": "<string>",//Required
"businessAddress": {
"houseNumber": "<integer>",//Required
"streetName": "<string>",//Required
"country": "<string>",//Required
"nearestLandMark": "<string>",//Optional
"state": "<string>",//Required
"lga": "<string>",//Required
"city": "<string>",//Required
"lcda": "<string>"//Optional
},
"businessShareholders": [
{
"name": "<string>",//Required
"phoneNumber": "<string>",//Required
"email": "<string>",//Required
"bvn": "<string>",//Required
"sharesOwned": "<integer>",//Required
"idType": 4,//Required
"fileUrlString": "<string>"//Required
}
],
"businessLicenseFileUrl": "<string>",//Optional
"cacFileUrl": "<string>",//Required
"mermartFileUrl": "<string>",//Required
"paymentMethodIds": "<string>",//Required (1,2,3,4,5 or *)
"businessProjectionCurrency": "<string>",//Required
"businessProjectionValue": "<double>",//Required
"category": "<string>",//Required
"bankAccountNumber": "<string>",//Required
"bankName": "<string>",//Required
"usdBankAccountNumber": "<string>",//Optional
"usdBankName": "<string>",//Optional
"usdBankAccountName": "<string>",//Optional
"bankCode": "<string>",//Required
"usdBankCode": "<string>",//Optional
"correspondentBank": "<string>",//Optional
"beneficiaryBankAddress": "<string>",//Optional
"bankSWIFTOrBICCode": "<string>",//Optional
"bankBranch": "<string>",//Optional
"logo": "<string>",
"callbackUrl": "<string>",//Required
"businessWebsiteUrl": "<string>" //Optional
"setUpUrl": "string",//Required
}
Whilst filling the onboarding properties, Ensure to pass appropriate enum types which is usually interpreted as interger.
[Shareholders] enum IdType
{
DriversLicense = 1,
InternationPassport =2,
NationalID =3,
VotersCard =4,
NotorizedForeignPassport =5
}
[businessVerificationStatus] enum BusinessVerificationStatus
{
YetToCompletedRegistration =0,
AwaitingVerification =1,
AwaitingApproval =2,
Approved =3,
Rejected =4
}
{
"data": null,
"status": false,
"message": "Oops, an error occurred. Please, retry. If problem persist, please contact the system admin"
}
{
"status": true,
"message": "Success",
"data": {
"merchantId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"businessName": "string",
"onboardingRequestReference": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"onboardingComments": [
"string"
],
"businessVerificationStatus": 0
}
}
Get Bank Name
Event: Get Banks Details
Method: POST
Endpoint: BaseURL/merchant-onboarding/api/v1/banks/accountName
Content-Type: application/json
Request Payload:
{
"accountNumber": "2010000000",
"bankCode": "035"
}
Response Payload:
Success Response:
{
"data": {
"accountName": "ABC XYZ",
"accountNumber": "2010000000",
"bankCode": "035"
},
"status": true,
"message": "Success"
}
Failure Response:
{
"data": null,
"status": false,
"message": "Failure message sample here.."
}
Get List of Banks
Event: Get Banks and Bank Codes
Method: GET
Endpoint: BaseURL/merchant-onboarding/api/v1/banks
Content-Type: application/json
Response Payload
{
"data": [
{
"bankName": "ALATbyWEMA",
"bankCode": "035"
},
{
"bankName": "WEMA BANK",
"bankCode": "035"
},
{
"bankName": "ACCESS BANK",
"bankCode": "044"
}
]
}
During and after business onboarding, an onboarded business could be rejected due one/more reasons (which will be duly communicated via the callback request). Please, base on the stages that were rejected, update such details here by providing the required info.
Event: business_onboarding update
Endpoint: BaseURL/merchant-onboarding/api/v1/merchants/{merchantId}/{onboarding_reference_id}/business-onboarding
Method: PUT
Content-Type: application/json
{
"name": "JohnJoe Store",//Optional
"shareHolders": [
{
"name": "string",//Optional
"phoneNumber": "string",//Optional
"email": "string",//Optional
"bvn": "string",//Optional
"sharesOwned": 0,//Optional
"idType": 1,//Optional
"fileUrlString": "string"//Optional
}
],
"businessLicenseFileUrl": "string",//Optional
"cacFileUrl": "string",//Required
"mermartFileUrl": "string",//Required
"paymentMethodIds": "*",//Required
"businessProjectionCurrency": "string",//Required
"businessProjectionValue": 0,//Required
"category": "Ecommerce",//Required
"bankAccountNumber": "2010000000",//Required
"bankName": "string",//Required
"usdBankAccountNumber": "2010000000",//Optional
"usdBankName": "string",//Optional
"usdBankAccountName": "string",//Optional
"bankCode": "035",//Required
"usdBankCode": "035",//Optional
"correspondentBank": "string",//Optional
"beneficiaryBankAddress": "string",//Optional
"bankSWIFTOrBICCode": "string",//Optional
"bankBranch": "string",//Optional
"callbackUrl": "string",//Optional
"businessWebsiteUrl": "string"//Optional
}
ALATPay provides a seamless onboarding process for merchants to register and manage businesses within their account. Upon successful onboarding of a new business and such business has been approved internally by ALATPay team, ALATPay triggers a callback to the merchant's specified endpoint to notify them of the completion of the onboarding process.
Event: business_onboarding callback
Method: POST
Content-Type: application/json
{
"status": true,
"message": "Success",
"data": {
"PrimaryApiKey": null,
"SecondaryApiKey": null,
"CallbackUrl": "https://callbackurl.com",
"BusinessId": "10834d8d-dc97-4d62-1eb2-08dbf2478fd1",
"RejectedStringifiedStagesJson": {
"StageTwo": "",
"StageFour": "",
"StageFive": "",
"StageSix": ""
},
"MerchantId": "7995670a-478a-47aa-151d-08dbec00f40c",
"BusinessName": "XYZ Business",
"OnboardingRequestReference": "10834d8d-dc97-4d62-1eb2-08dbf2478fd1",
"Status": "Rejected",
"OnboardingComments": [
"string"
],
"BusinessVerificationStatus": 4
}
}