Guide

Merchant Onboarding

Get from sign-up to live verification keys. Sandbox access is instant; live access follows a quick business review. All endpoints below use your merchant JWT (Authorization: Bearer …).

1. Register

POST

/v1/merchants/register

Create a merchant account and owner user

curl -X POST 'https://api.mobid.io/v1/merchants/register' \
  -H 'Content-Type: application/json' \
  -d '{
    "businessName": "Acme Payments Ltd",
    "contactName": "Ada Obi",
    "email": "ada@acme.com",
    "password": "••••••••",
    "entityType": "Limited Liability Company",
    "registrationNumber": "RC1234567",
    "dateRegistered": "2021-03-01",
    "industry": "Fintech"
  }'

MID verifies the submitted RC number, registered name, and registration date with Mono before creating the account. A successful response returns a token (merchant JWT), sends a 6-digit phone OTP, and emails a one-time verification link.

2. Verify email and phone

POST

/v1/merchants/email/verify-link

Confirm the token from the emailed link

POST

/v1/merchants/email/resend

Send a new email verification link

POST

/v1/merchants/phone/verify

Confirm the 6-digit SMS code

POST

/v1/merchants/phone/resend

Send a new phone OTP

Verify phone

curl -X POST 'https://api.mobid.io/v1/merchants/phone/verify' \
  -H 'Authorization: Bearer <merchant_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "code": "123456" }'

ℹ

Dashboard status

The merchant dashboard marks work email, phone, and RC number as Verified or Pending. Both contact channels and the Mono registration check must pass before live approval.

3. Complete your business profile

PATCH

/v1/merchants/business

Save profile and run Corporate Affairs verification

MID verifies your registration number, registered name, and date against the Corporate Affairs registry. Include your representative's identity and your use case — both are required for approval.

Update business profile

curl -X PATCH 'https://api.mobid.io/v1/merchants/business' \
  -H 'Authorization: Bearer <merchant_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "registeredName": "Acme Payments Ltd",
    "registrationNumber": "RC1234567",
    "dateRegistered": "2021-03-01",
    "address": "12 Marina Road, Lagos",
    "usecase": "Verify customers during account opening",
    "description": "Acme provides digital payments to SMEs…",
    "identityType": "nin",
    "identityNumber": "12345678901"
  }'

4. Upload documents

POST

/v1/merchants/documents

Upload verification documents

type	Document
business_registration	Business registration certificate (required)
representative_id	Representative's government ID (required)
tax_document	Tax document (optional)
address_proof	Proof of address (optional)

Upload

curl -X POST 'https://api.mobid.io/v1/merchants/documents' \
  -H 'Authorization: Bearer <merchant_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "business_registration",
    "fileName": "cac-certificate.pdf",
    "mimeType": "application/pdf",
    "size": 184320,
    "contentBase64": "<base64>"
  }'

5. Create an application

POST

/v1/merchants/applications

Get instant sandbox API keys

Applications are the unit of API access. Each application has its own client ID, callback configuration, enabled request types, and sandbox/live credentials. Include OAUTH in requestTypes to enable QR + biometric claim sharing.

Field	Type	Required	Description
name	string	Yes	A recognizable name for the integration
callbackUrl	string	Yes	Default signed webhook destination
redirectUris	string[]	No	Allowed browser return URLs
requestTypes	string[]	No	LOGIN, TRANSACTION, SIGNATURE, and/or OAUTH; all four by default

Create application

curl -X POST 'https://api.mobid.io/v1/merchants/applications' \
  -H 'Authorization: Bearer <merchant_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Acme Onboarding",
    "callbackUrl": "https://acme.com/api/mid/webhook",
    "redirectUris": ["https://acme.com/mid/callback"],
    "requestTypes": ["LOGIN", "OAUTH"]
  }'

Response

{
  "error": false,
  "message": "Application created",
  "application": {
    "id": "665f…",
    "merchantId": "665e…",
    "clientId": "acmeonboar_a1b2c3d4e5",
    "name": "Acme Onboarding",
    "callbackUrl": "https://acme.com/api/mid/webhook",
    "redirectUris": ["https://acme.com/mid/callback"],
    "requestTypes": ["LOGIN", "OAUTH"],
    "environment": "sandbox",
    "liveStatus": "sandbox",
    "credentials": {
      "sandbox": {
        "apiKey": "mk_test_…",
        "secret": "…",
        "generatedAt": "2026-06-19T10:30:00.000Z"
      },
      "live": { "apiKey": null, "generatedAt": null }
    },
    "createdAt": "2026-06-19T10:30:00.000Z",
    "updatedAt": "2026-06-19T10:30:00.000Z"
  }
}

⚠

Save the secret now

The application secret is returned when the application is created, but is omitted from later dashboard responses. Store it in a secrets manager and never send it to a browser or mobile app.

6. Rotate an API key

POST

/v1/merchants/applications/:id/rotate-key

Replace an active sandbox or live API key

Owners, admins, and developers can rotate an application key. Rotation invalidates the old key immediately and keeps the existing secret, so update the API key used in both the request header and HMAC payload.

Rotate a sandbox key

curl -X POST 'https://api.mobid.io/v1/merchants/applications/665f…/rotate-key' \
  -H 'Authorization: Bearer <merchant_jwt>' \
  -H 'Content-Type: application/json' \
  -d '{ "environment": "sandbox" }'

Response

{
  "error": false,
  "message": "API key rotated successfully",
  "credential": {
    "environment": "sandbox",
    "apiKey": "mk_test_…",
    "generatedAt": "2026-06-19T11:15:00.000Z"
  }
}

environment	Availability	Result
sandbox	Available immediately	Returns a new mk_test_… key
live	Only after live credentials are active	Returns a new mk_live_… key

ℹ

Rotation does not reveal or replace the secret

Continue signing with the application's existing secret. The new payload is `${newApiKey}:${timestamp}:${JSON.stringify(body)}`; requests signed with the old API key fail with 401 Invalid API key.

7. Request live access

POST

/v1/merchants/go-live

Submit for review

An admin can approve live access only once all of the following are complete:

Requirement	From
Business description	Business profile
Use case	Business profile
Verified registration number	Corporate Affairs verification
Business address	Business profile
Business registration certificate	Documents
Representative identity type & number	Business profile
Representative identity document	Documents
Verified email	Email verification link
Verified phone	SMS OTP

✓

On approval

Live credentials (mk_live_…) are issued for each application and your documents are marked verified. Swap your sandbox keys for live keys and start verifying real customers.