Register New Merchant API

Register and onboard new merchants into the EdfaPay system using this API. It supports both Individual and Business onboarding flows.

POST https://api.edfapay.com/merchantonboarding/onboard/

🔑
Partner ID: You must use your own Partner ID in every request. Using someone else's Partner ID will result in failure. Obtain your Partner ID from your EdfaPay account or by contacting your account manager.

🌐
Host Domain: The partnerOrigin parameter must match the host configured in your EdfaPay account. Requests from unregistered domains will be rejected.

Overview

Onboard new merchants with Individual or Business flows
All required business and identity documents must be included
Request must be sent as multipart/form-data due to file uploads
Base URL (Production): https://api.edfapay.com
Content-Type: multipart/form-data

Request Parameters

Required Parameters

Parameter	Type	Description
`partnerId`	string	Your unique Partner ID. Do not use someone else's ID.
`partnerOrigin`	string	Partner origin domain. Must match the domain configured in your EdfaPay account.
`merchantName`	string	Merchant's personal name
`email`	string	Merchant email address (must be a valid email format)
`companyName`	string	Legal company name
`registeredMobileNumber`	string	Mobile number in E.164 format (e.g., `+9665XXXXXXXX`)
`crNumber`	string	Commercial Registration number
`ibanNumber`	string	Valid IBAN (for KSA, must start with `SA`)
`nationalId`	string	National ID number
`files`	file	Required PDF documents (see File Upload Rules below)

Optional Parameters

Parameter	Type	Description
`businessType`	string	Business type (e.g., `Business` / `Freelancer`)
`entityAddress`	string	Merchant address
`website`	string	Merchant website
`cityName`	string	City name
`countryName`	string (ISO-2)	Country code (e.g., `SA`)
`unifiedNumber`	string	Unified number
`freelancerCertificateNumber`	string	Freelancer certificate number

File Upload Rules

Rule	Detail
Parameter name	`files`
Content type	`multipart/form-data`
Accepted format	PDF only
Multiple files	Repeat the `files` key for each document

Business onboarding requires these 4 PDF files:

CR Certificate
IBAN Certificate
National ID
National Address Document

📎
All files must be uploaded using the same files key repeated for each document. Do not use different parameter names.

Validation Rules

Field	Rule
`email`	Must be a valid email format
`ibanNumber`	Must be a valid IBAN (KSA IBANs must start with `SA`)
`registeredMobileNumber`	Must follow E.164 format (e.g., `+9665XXXXXXXX`)
`files`	Only PDF files are accepted

Example Request

curl --location 'https://api.edfapay.com/merchantonboarding/onboard' \
--form 'partnerId="YOUR_OWN_PARTNER_ID"' \
--form 'partnerOrigin="yourdomain.com"' \
--form 'merchantName="TEST Merchant"' \
--form 'email="[email protected]"' \
--form 'registeredMobileNumber="+9665xxxxxxx"' \
--form 'businessType="Business"' \
--form 'companyName="Merchant Company"' \
--form 'entityAddress="RIYADH"' \
--form 'cityName="RIYADH"' \
--form 'countryName="SA"' \
--form 'crNumber="123456"' \
--form 'website="https://www.google.com"' \
--form 'ibanNumber="SA1910000001400014451005"' \
--form 'nationalId="1111111111111"' \
--form 'unifiedNumber="9200"' \
--form '[email protected]' \
--form '[email protected]' \
--form '[email protected]' \
--form '[email protected]'

⚠️
Replace YOUR_OWN_PARTNER_ID with your actual Partner ID and ensure partnerOrigin matches your configured EdfaPay domain.

Response

Success

{
    "response": {
        "code": 200,
        "message": "MerchantOnBoard has been created successfully"
    }
}

{
    "response": {
        "code": 400,
        "message": "<Parameter> is required"
    }
}

Error

🚫
Invalid Partner ID: The Partner ID is incorrect or does not belong to you.

🌐
Domain Mismatch: The partnerOrigin does not match the registered host.

📎
Missing Documents: Required files are missing or in an invalid format.

⚠️
Validation Failure: IBAN, email, or mobile number fails format validation.

Best Practices

✅
Before sending your request, verify the following:

Validate all PDF files before uploading

Confirm your Partner ID is correct — requests with invalid IDs are rejected

Ensure partnerOrigin exactly matches your EdfaPay configured host

Use proper PDF documents for business verification

Follow E.164 format for mobile numbers (e.g., +9665XXXXXXXX)