Merchant Onboarding API

Overview

The Merchant Onboarding API handles the full registration and approval flow for new merchants. The process consists of three sequential steps:

Signup — Submit merchant details and documents
Search Merchant — Retrieve the merchant record by email
Approve Merchant — Approve the merchant and activate their account

Base URL

https://app-api.edfapay.com

Authentication

All endpoints (except Signup) require a Bearer Token in the Authorization header.

Authorization: Bearer <your_token>

Endpoints

1. Signup

POST /public/signup

Headers

Header	Value
`Accept`	`application/json`
`Content-Type`	`application/json`
`x-lang`	`en`

Request Body

{
  "fullName": "John Doe",
  "companyName": "My Company",
  "address": "Riyadh",
  "companyWebsite": "https://example.com",
  "domainUrl": "app.edfapay.com",
  "email": "[email protected]",
  "ibanNumber": "SA0380000000608010167510",
  "freelancerCertificateNumber": "324321432",
  "isFreeLance": true,
  "mobileNumber": "+966-501234525",
  "nationalId": "34324234321432",
  "userType": "FreeLance",
  "MethodType": [],
  "unViewed": 0,
  "merchantOnboardDocumentsRequests": [
    {
      "name": "CR_CERTIFICATE_doc",
      "type": "CR_CERTIFICATE",
      "data": {
        "fileSize": 469513,
        "fileName": "cr_certificate.pdf",
        "contentType": "application/pdf",
        "base64": "<base64_encoded_file>"
      }
    },
    {
      "name": "IBAN_CERTIFICATE_doc",
      "type": "IBAN_CERTIFICATE",
      "data": {
        "fileSize": 469513,
        "fileName": "iban_certificate.pdf",
        "contentType": "application/pdf",
        "base64": "<base64_encoded_file>"
      }
    },
    {
      "name": "NATION_ID_doc",
      "type": "NATION_ID",
      "data": {
        "fileSize": 469513,
        "fileName": "national_id.pdf",
        "contentType": "application/pdf",
        "base64": "<base64_encoded_file>"
      }
    },
    {
      "name": "NATION_ADDRESS_doc",
      "type": "NATION_ADDRESS",
      "data": {
        "fileSize": 469513,
        "fileName": "national_address.pdf",
        "contentType": "application/pdf",
        "base64": "<base64_encoded_file>"
      }
    }
  ]
}

Body Parameters

Parameter	Type	Required	Description
`fullName`	`string`	✅ Yes	Full name of the merchant owner.
`companyName`	`string`	✅ Yes	Name of the company.
`address`	`string`	✅ Yes	Physical address of the merchant.
`companyWebsite`	`string`	No	Company website URL.
`domainUrl`	`string`	✅ Yes	The domain URL used for the partner's platform.
`email`	`string`	✅ Yes	Merchant's email address. Used to look up the merchant later.
`ibanNumber`	`string`	✅ Yes	Merchant's IBAN number for payouts.
`isFreeLance`	`boolean`	✅ Yes	`true` if the merchant is a freelancer, `false` for a company.
`freelancerCertificateNumber`	`string`	Conditional	Required if `isFreeLance` is `true`.
`crNumber`	`string`	Conditional	Commercial Registration number. Required if `isFreeLance` is `false`.
`mobileNumber`	`string`	✅ Yes	Mobile number in E.164 format (e.g. `+966-501234525`).
`nationalId`	`string`	✅ Yes	National ID number of the merchant owner.
`userType`	`string`	✅ Yes	Merchant type. Values: `FreeLance`, `Company`.
`MethodType`	`array`	No	Payment method types. Pass empty array `[]` if not applicable.
`merchantOnboardDocumentsRequests`	`array`	✅ Yes	List of required documents. See Documents below.

Documents

Each document in merchantOnboardDocumentsRequests must follow this structure:

Field	Type	Description
`name`	`string`	Internal document name identifier.
`type`	`string`	Document type. See supported types below.
`data.fileSize`	`number`	File size in bytes.
`data.fileName`	`string`	Original file name with extension.
`data.contentType`	`string`	MIME type (e.g. `application/pdf`, `image/jpeg`).
`data.base64`	`string`	Base64-encoded file content.

Supported Document Types:

Type	Description
`CR_CERTIFICATE`	Commercial Registration Certificate
`IBAN_CERTIFICATE`	IBAN Bank Certificate
`NATION_ID`	National ID document
`NATION_ADDRESS`	National Address document

Response

Success — `200 OK`

{
  "status": "success",
  "message": "Merchant registered successfully."
}

Error Responses

Status Code	Description
`400 Bad Request`	Missing or invalid fields in the request body.
`409 Conflict`	A merchant with this email already exists.

Example

curl -X 'POST' \
  'https://app-api.edfapay.com/public/signup' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-lang: en' \
  -d '{
    "fullName": "John Doe",
    "companyName": "My Company",
    "email": "[email protected]",
    "isFreeLance": true,
    ...
  }'

2. Search Merchant

Search for a merchant by email to retrieve their record and ID. This is typically called after Signup to get the merchant_id needed for the Approve step.

GET /merchant-onboard/search

Headers

Header	Value
`Authorization`	`Bearer <your_token>`

Query Parameters

Parameter	Type	Required	Description
`text`	`string`	✅ Yes	The merchant's email address to search for.
`pageNumber`	`integer`	No	Page number for pagination. Default: `0`.
`pageSize`	`integer`	No	Number of results per page. Default: `1`.

Response

Success — `200 OK`

{
  "data": {
    "content": [
      {
        "id": "d90200e2-1811-4094-a3a4-a85e30fb0898",
        "fullName": "John Doe",
        "email": "[email protected]",
        "mobileNumber": "+966-501234525"
      }
    ]
  }
}

Field	Type	Description
`data.content[].id`	`string (UUID)`	Merchant's unique ID. Use this as `merchant_id` in the Approve request.
`data.content[].fullName`	`string`	Merchant's full name.
`data.content[].email`	`string`	Merchant's email address.
`data.content[].mobileNumber`	`string`	Merchant's mobile number.

Error Responses

Status Code	Description
`200 OK` with empty `content`	No merchant found for the given email.
`401 Unauthorized`	Missing or invalid Bearer token.

Example

curl -X 'GET' \
  'https://app-api.edfapay.com/merchant-onboard/search?pageNumber=0&pageSize=1&[email protected]' \
  -H 'Authorization: Bearer <your_token>'

3. Approve Merchant

Approve a registered merchant and activate their account. This finalizes the onboarding process.

POST /merchant-onboard/approve/{merchant_id}

Headers

Header	Value
`Content-Type`	`application/json`
`Authorization`	`Bearer <your_token>`
`x-lang`	`en`

Path Parameters

Parameter	Type	Required	Description
`merchant_id`	`string (UUID)`	✅ Yes	The merchant's unique ID retrieved from the Search step.

Request Body

{
  "name": "John Doe",
  "feeProfileId": null,
  "emailAddress": "[email protected]",
  "mobileNumber": "+966-501234525",
  "nameAR": "جون دو",
  "country": "682",
  "city": "1",
  "state": "",
  "active": true,
  "logo": null,
  "registeredMobileNumber": "+966-501234525",
  "currencyCode": "1",
  "businessCategoryId": "e28ae68c-87d3-478d-afdd-f6020f0182a8"
}

Body Parameters

Parameter	Type	Required	Description
`name`	`string`	✅ Yes	Merchant's full name (English).
`nameAR`	`string`	✅ Yes	Merchant's full name (Arabic).
`emailAddress`	`string`	✅ Yes	Merchant's email address.
`mobileNumber`	`string`	✅ Yes	Merchant's mobile number.
`registeredMobileNumber`	`string`	✅ Yes	Mobile number used during registration.
`country`	`string`	✅ Yes	Country code ID (e.g. `682` for Saudi Arabia).
`city`	`string`	✅ Yes	City code ID.
`state`	`string`	No	State/region.
`active`	`boolean`	✅ Yes	Set to `true` to activate the merchant account.
`currencyCode`	`string`	✅ Yes	Currency code ID (e.g. `1` for SAR).
`businessCategoryId`	`string (UUID)`	✅ Yes	UUID of the business category.
`feeProfileId`	`string / null`	No	Fee profile UUID, or `null` to use the default profile.
`logo`	`string / null`	No	Logo URL or `null`.

Response

Success — `200 OK`

{
  "status": "success",
  "message": "Merchant approved successfully."
}

Error Responses

Status Code	Description
`400 Bad Request`	Missing or invalid fields.
`401 Unauthorized`	Missing or invalid Bearer token.
`404 Not Found`	Merchant with the given ID does not exist.

Example

curl -X 'POST' \
  'https://app-api.edfapay.com/merchant-onboard/approve/d90200e2-1811-4094-a3a4-a85e30fb0898' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  -H 'x-lang: en' \
  -d '{
    "name": "John Doe",
    "emailAddress": "[email protected]",
    "mobileNumber": "+966-501234525",
    "nameAR": "جون دو",
    "country": "682",
    "city": "1",
    "active": true,
    "registeredMobileNumber": "+966-501234525",
    "currencyCode": "1",
    "businessCategoryId": "e28ae68c-87d3-478d-afdd-f6020f0182a8",
    "parentBusinessUnitId": "1d1ff5cb-e945-4d5e-a461-ac217f09ed23"
  }'

Full Onboarding Flow

1. POST /public/signup              → Submit merchant details & documents
          ↓
2. GET  /merchant-onboard/search    → Find merchant by email → get merchant_id
          ↓
3. POST /merchant-onboard/approve/{merchant_id}  → Approve & activate merchant

Notes

The email field is the primary identifier used to link steps 1 → 2 → 3.
All document files must be base64-encoded before submission.
The merchant_id returned in the Search response is required for the Approve call.
Steps 2 and 3 require a valid Bearer token with admin/operator privileges.

Overview

Base URL

Authentication

Endpoints

1. Signup

Headers

Request Body

Body Parameters

Documents

Response

Success — 200 OK

Error Responses

Example

2. Search Merchant

Headers

Query Parameters

Response

Success — 200 OK

Error Responses

Example

3. Approve Merchant

Headers

Path Parameters

Request Body

Body Parameters

Response

Success — 200 OK

Error Responses

Example

Full Onboarding Flow

Notes

Success — `200 OK`

Success — `200 OK`

Success — `200 OK`