Approve Merchant Creation API

Approve a pending merchant creation request by providing the onboarding request ID and the required merchant configuration. Available to authorized Super Admin and Partner users.

Overview

The Approve Merchant Creation API is used to approve a merchant creation request during the onboarding process. It accepts the onboarding request ID in the URL and the merchant configuration in the request body.

HTTP Method: POST

Endpoint: /api/v1/merchant-onboard/approve/{id}

Access Levels: SUPER_ADMIN, PARTNER

Authentication

Include your API key in the request headers.

HeaderValue
X-API-KEYYOUR_API_KEY
Accept*/*
Content-Typeapplication/json

Path Parameters

ParameterTypeRequiredDescription
idUUIDYesIdentifier of the merchant onboarding request to approve.

Request Body

The request body must be provided in JSON format and contains merchant details, business information, fee configuration, settlement settings, and optional Moyasar configuration.

Merchant Information

FieldTypeDescription
emailAddressStringMerchant email address.
registeredMobileNumberStringRegistered mobile number.
countryStringMerchant's country.
cityStringMerchant's city.
parentBusinessUnitIdUUIDIdentifier of the parent business unit.
businessCategoryIdUUIDIdentifier of the merchant's business category.
currencyCodeStringCurrency code associated with the merchant.
nameStringMerchant name.
nameARStringMerchant name in Arabic.
activeBooleanIndicates whether the merchant is active.
feeProfileIdIntegerIdentifier of the applicable fee profile.

Logo Object

The logo object contains the merchant's logo file information.

FieldTypeDescription
fileSizeNumberFile size.
fileUrlStringFile URL.
fileNameStringFile name.

Fee Configuration

The feeSetup object defines percentage-based and fixed fees for supported payment categories.

Each fee object contains:

FieldTypeDescription
percentageRateNumberPercentage fee rate.
fixedAmountNumberFixed fee amount.

Supported fee configuration objects:

  • mada
  • visaMc
  • applePay
  • refund

Settlement and Moyasar Settings

FieldTypeDescription
settlementCycleStringSettlement cycle. The documented example uses T_PLUS_0.
enableMoyasarBooleanIndicates whether Moyasar integration is enabled.
moyasarObjectMoyasar configuration, including business details, payment methods, fees, and documents.
moyasarFeesPresentWhenEnabledBooleanIndicates whether Moyasar fees are present when Moyasar is enabled.

Moyasar Object

The moyasar object includes the following fields:

FieldTypeDescription
typeStringBusiness or entity type.
nameStringBusiness name.
countryStringCountry.
emailStringEmail address.
adminEmailStringAdministrator email address.
ownersCountIntegerNumber of owners.
signatoryStringSignatory information.
activityLicenseRequiredBooleanIndicates whether an activity license is required.
websiteStringBusiness website.
publicNameStringPublic-facing business name.
signatoryCountIntegerNumber of signatories.
timeZoneStringConfigured time zone.
statementDescriptorStringStatement descriptor.
enabledSchemesArray of StringsEnabled card schemes.
paymentMethodsArray of StringsConfigured payment methods.
feesArray of ObjectsFee configuration for Moyasar.
taxInclusiveBooleanIndicates whether fees or prices are tax-inclusive, as defined by the integration.
documentsArray of ObjectsBusiness documents and associated metadata.

Each object in the fees array contains:

  • family — String
  • rate — Number
  • fixed — Number
  • cap — Number

Each object in the documents array contains:

  • type — String
  • file — Object containing fileSize, fileUrl, and fileName
  • info — Object containing additional document information

cURL Example

curl -X POST "https://app-api.edfapay.com/api/v1/merchant-onboard/approve/{id}" \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: */*" \
  -H "Content-Type: application/json" \
  -d '{
    "emailAddress": "[email protected]",
    "registeredMobileNumber": "+966500000000",
    "country": "Saudi Arabia",
    "city": "Riyadh",
    "parentBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "businessCategoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "logo": {
      "fileSize": 0,
      "fileUrl": "https://example.com/logo.png",
      "fileName": "logo.png"
    },
    "currencyCode": "SAR",
    "name": "Example Merchant",
    "nameAR": "متجر تجريبي",
    "active": true,
    "feeProfileId": 0,
    "feeSetup": {
      "mada": {
        "percentageRate": 0,
        "fixedAmount": 0
      },
      "visaMc": {
        "percentageRate": 0,
        "fixedAmount": 0
      },
      "applePay": {
        "percentageRate": 0,
        "fixedAmount": 0
      },
      "refund": {
        "percentageRate": 0,
        "fixedAmount": 0
      }
    },
    "settlementCycle": "T_PLUS_0",
    "enableMoyasar": false,
    "moyasarFeesPresentWhenEnabled": false
  }'

Important: This cURL is an illustrative request template, not a guaranteed valid production payload. Replace the path ID and example values with the actual onboarding request ID and merchant data. The complete request schema includes the moyasar object; provide its fields according to the merchant's configuration and the API's validation requirements.

Responses

200 — OK

The API returns a response envelope containing the response code, message, error code, and data.

Example response:

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": "string"
}
FieldDescription
codeResponse code.
messageResponse message.
errorCodeError identifier, if provided.
dataResponse data returned by the API. The documented example represents this field as a string.

400 — Bad Request

Returned when the request cannot be processed, such as when the request data is invalid or fails validation.

Example response:

{
  "code": 0,
  "message": "string",
  "errorCode": "string",
  "data": {}
}

Implementation Notes

  • Use the onboarding request UUID as the id path parameter.
  • Send the request body as JSON.
  • Ensure the merchant, business category, parent business unit, fee profile, and fee configuration values match the intended setup.
  • Configure Moyasar-related fields according to the intended integration setup.
  • The provided API specification does not define the exact approval business rules or the detailed validation requirements for every field. Confirm these requirements against the implementation before using the endpoint in production.

Did this page help you?