The Onboarding API is designed to the process of the onboarding of sub-accounts and related consumers/customers of a business into PayMongo via API to initiate the onboarding process and submit necessary requirements via API on behalf of their sub-accounts.

Implementation

🚧

Account configuration is required before development

We need to configure your account before your developers can start testing and integration. Kindly message [email protected] to request for the Seeds feature.

Furthermore, please note that only live secret keys are used for the entire onboarding API process. For more information see the Authentication page.

Definition of Terms

Parent Merchant
A merchant who oversees its child merchants and related consumers. This typically refers to a Business account with PayMongo, where PayMongo interacts directly with the primary business managing these accounts.

Child Merchant
A merchant whose PayMongo account is connected to a Parent Merchant. Child merchants can use features or functionalities that their parent has enabled for them.

Merchant Related Consumer
These are individual consumers or customers of the parent merchant who are onboarded onto the PayMongo platform.

Sub-accounts
This is an alternative term for child merchants and merchant related consumers.

Optional prerequisite

To track or receive notifications of a sub-account's onboarding result, webhooks can be set up to receive the onboarding result when the PayMongo onboarding team has completed the review process. Parent merchants can receive events for both activated and declined onboarding results. See Seeds Webhook for more information.

1. Initiate the onboarding

To start the onboarding process, use your live secret key to authenticate the request. Ensure you have the resource ID, as it will be needed for subsequent steps. Fields specified in this request can also be updated later if needed. Select the type of entity you wish to onboard:

• For Child Merchants: Create a Child Merchant endpoint. Required fields include business.trade_name, business.type, and features.
• For Consumers: Create a Consumer endpoint. Required fields include email_address, features, first_name, last_name, and mobile_number.

For a complete list of features, please refer to the Appendix in the Onboarding API documentation.

2. Get Requirements

Retrieve the list of requirements for submitting details by using the following endpoints:

• For Child Merchants: Retrieve Child Merchant Requirement endpoint
• For Consumers: Retrieve Consumer Requirements endpoint

The list of requirements may vary depending on the selected features for the sub-accounts. Additionally, changes to the child merchant's business type may also impact the requirements.

3. Send details

Update the details of the sub-accounts as needed. The update endpoints can be called multiple times until the merchant or consumer is ready for review. Complete the details by sending an API request to the following:

• For Child Merchants: Update a Child Merchant endpoint
• For Consumers: Update a Consumer endpoint

Non-required fields will be automatically ignored. Additionally, certain fields require specific values. Please refer to the Appendix

4. Upload files

Upload the necessary files for the child merchant or consumer. Keep in mind that the required files vary depending on the business type and selected features.

• For Child Merchants:
  • Create a File Record for a Child Merchant
  • List File Records for a Child Merchant
  • Delete a File Record for a Child Merchant
• For Consumers:
  • Create a File Record for a Consumer
  • List File Records for a Consumer
  • Delete a File Record for Consumer

5. Submit for review

Submit the sub-account for review. If any required details or documents are missing, the API will return an error indicating the incomplete items.

• For Child Merchants: Submit a Child Merchant for Review endpoint
• For Consumers: Submit a Consumer for Review endpoint

⚠️

Once submission is successful, you will no longer be able to edit details or documents for the sub-account.

6. Sub-account onboarding review

Our onboarding team will review the submitted details and documents of the sub-account. This process may take up to 14 business days. PayMongo will reach out in case of any clarifications or additional requirements.

Once the review is complete, the sub-account will either be:

• Approved: The sub-account will be activated, and you can proceed with using PayMongo's services.
• Declined: The sub-account will not be activated. If you have any questions or concerns during the onboarding process, please don't hesitate to contact our support team.

7. Receiving the onboarding result via a webhook event (optional)

If a webhook has been set up, the onboarding results, including API keys for the activated sub-account, will be sent to the specified URL via a POST request. Refer to the Seeds Webhook for more details.