> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dubupay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete merchant onboarding on Dubu Pay

> Submit your business application and supporting documents to verify your business and unlock full payment processing on Dubu Pay.

Before you can process payments or issue virtual bank accounts, you must complete merchant onboarding. Onboarding verifies your business details and lets Dubu Pay comply with financial regulations. Once your application is approved, all payment and trading features become available on your account.

## How onboarding works

The process has five stages: create an application, upload supporting documents, update any missing details, then submit for review. Dubu Pay's team reviews your submission and notifies you of the outcome.

<Steps>
  <Step title="Create your application">
    Start by creating an onboarding application. You must provide your country (`US` or `NG`) and your business type.

    **Nigeria (`NG`) business types:** `non_registered`, `business_name`, `registered_company`, `incorporated_trustee`

    **United States (`US`) business types:** `sole_proprietor`, `llc`, `corporation`, `nonprofit`

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.dubupay.com/api/v1/onboarding \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "country": "NG",
          "business_type": "registered_company"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.dubupay.com/api/v1/onboarding', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          country: 'NG',
          business_type: 'registered_company',
        }),
      });

      const { data } = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    A successful request returns your application object with a status of `draft`.

    ```json theme={null}
    {
      "success": true,
      "data": {
        "id": "app_01HXK...",
        "status": "draft",
        "country": "NG",
        "business_type": "registered_company",
        "created_at": "2026-05-21T10:00:00.000Z"
      }
    }
    ```
  </Step>

  <Step title="Upload supporting documents">
    Upload the documents required for your business type. Each file must be a PDF, JPG, JPEG, or PNG and must not exceed 10 MB. Send the file as `multipart/form-data` using the `file` field, and include a `document_type` describing what the document is (for example, `certificate_of_incorporation`, `utility_bill`, `id_card`).

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.dubupay.com/api/v1/onboarding/documents/upload \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -F "file=@/path/to/certificate.pdf" \
        -F "document_type=certificate_of_incorporation"
      ```

      ```javascript Node.js theme={null}
      import fs from 'fs';
      import FormData from 'form-data';

      const form = new FormData();
      form.append('file', fs.createReadStream('/path/to/certificate.pdf'));
      form.append('document_type', 'certificate_of_incorporation');

      const response = await fetch('https://api.dubupay.com/api/v1/onboarding/documents/upload', {
        method: 'POST',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          ...form.getHeaders(),
        },
        body: form,
      });

      const { data } = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    <Note>
      Accepted formats are PDF, JPG, JPEG, and PNG. Files larger than 10 MB are rejected. Make sure documents are legible and unobscured before uploading.
    </Note>

    You can view all uploaded documents at any time:

    <CodeGroup>
      ```bash cURL theme={null}
      curl https://api.dubupay.com/api/v1/onboarding/documents \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.dubupay.com/api/v1/onboarding/documents', {
        headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
      });

      const { data } = await response.json();
      console.log(data);
      ```
    </CodeGroup>

    To remove a document, pass its ID to the delete endpoint:

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X DELETE https://api.dubupay.com/api/v1/onboarding/documents/DOC_ID \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ```

      ```javascript Node.js theme={null}
      await fetch('https://api.dubupay.com/api/v1/onboarding/documents/DOC_ID', {
        method: 'DELETE',
        headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
      });
      ```
    </CodeGroup>
  </Step>

  <Step title="Update your application details">
    After creating your application, fill in the remaining business details using `PUT /onboarding`. All fields are optional in a single update — send only what you want to change.

    | Field                 | Type   | Description                                   |
    | --------------------- | ------ | --------------------------------------------- |
    | `business_name`       | string | Legal name of your business                   |
    | `business_address`    | string | Registered business address                   |
    | `business_phone`      | string | Business contact phone number                 |
    | `business_email`      | string | Business contact email address                |
    | `employee_count`      | string | Number of employees                           |
    | `registration_number` | string | Official registration or incorporation number |
    | `tax_number`          | string | Tax identification number                     |
    | `website_url`         | string | Your business website URL                     |
    | `social_media_url`    | string | Business social media profile URL             |
    | `description`         | string | Short description of your business            |

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X PUT https://api.dubupay.com/api/v1/onboarding \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
        -H "Content-Type: application/json" \
        -d '{
          "business_name": "Acme Stores Ltd",
          "business_address": "14 Marina Street, Lagos, Nigeria",
          "business_phone": "+2348012345678",
          "business_email": "finance@acmestores.ng",
          "registration_number": "RC1234567",
          "website_url": "https://acmestores.ng"
        }'
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.dubupay.com/api/v1/onboarding', {
        method: 'PUT',
        headers: {
          'Authorization': 'Bearer YOUR_ACCESS_TOKEN',
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          business_name: 'Acme Stores Ltd',
          business_address: '14 Marina Street, Lagos, Nigeria',
          business_phone: '+2348012345678',
          business_email: 'finance@acmestores.ng',
          registration_number: 'RC1234567',
          website_url: 'https://acmestores.ng',
        }),
      });

      const { data } = await response.json();
      console.log(data);
      ```
    </CodeGroup>
  </Step>

  <Step title="Submit for review">
    Once your application details are complete and your documents are uploaded, submit the application. You cannot make further changes after submission.

    <CodeGroup>
      ```bash cURL theme={null}
      curl -X POST https://api.dubupay.com/api/v1/onboarding/submit \
        -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
      ```

      ```javascript Node.js theme={null}
      const response = await fetch('https://api.dubupay.com/api/v1/onboarding/submit', {
        method: 'POST',
        headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
      });

      const { data } = await response.json();
      console.log(data.status); // "under_review"
      ```
    </CodeGroup>

    <Warning>
      Submitting your application is final. Double-check all business details and ensure every required document has been uploaded before calling this endpoint.
    </Warning>
  </Step>
</Steps>

## Check your application status

You can retrieve your current application at any time with `GET /onboarding`. Use this to monitor the review progress after submission.

<CodeGroup>
  ```bash cURL theme={null}
  curl https://api.dubupay.com/api/v1/onboarding \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.dubupay.com/api/v1/onboarding', {
    headers: { 'Authorization': 'Bearer YOUR_ACCESS_TOKEN' },
  });

  const { data } = await response.json();
  console.log(data.status);
  ```
</CodeGroup>

The `status` field progresses through the following values:

| Status         | Meaning                                                         |
| -------------- | --------------------------------------------------------------- |
| `draft`        | Application created but not yet submitted                       |
| `under_review` | Submitted and being reviewed by Dubu Pay                        |
| `approved`     | Onboarding complete — full API access enabled                   |
| `rejected`     | Application was not approved — see the `rejection_reason` field |

## After approval

Once your application status changes to `approved`, all payment processing features are unlocked on your account. If your application is rejected, the response includes a `rejection_reason` explaining what needs to be corrected. You can update your application and resubmit.

<Tip>
  Complete KYC verification after onboarding to raise your transaction limits. See the [KYC guide](/account/kyc) for details.
</Tip>