Create Merchant API

Creates a merchant with profile details, business unit association, contact information, currency, fee configuration, settlement cycle, and Moyasar integration settings, including payment schemes, fees, and supporting documents. Supports SUPER_ADMIN, PARTNER, and MERCHANT access levels.

1. Overview

The Create Merchant API allows authorized users to create a new merchant in the EdfaPay system.

The endpoint accepts merchant profile information, contact details, business unit association, business category, logo metadata, currency configuration, fee settings, settlement preferences, and Moyasar integration details.

The API supports merchant creation with configurable payment method fees and optional Moyasar-related settings, including payment schemes, payment methods, fee structures, and supporting documents.

Access Levels: SUPER_ADMIN, PARTNER, MERCHANT

2. Endpoint Details

PropertyValue
API NameCreate Merchant
HTTP MethodPOST
Endpoint/api/v1/merchant
Production Base URLhttps://app-api.edfapay.com
Content-Typeapplication/json
Accept*/*
Request BodyRequired

3. Authentication

Include the API key in the request headers, as required by the API configuration.

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

4. Request Body

The endpoint expects a JSON object containing merchant information and configuration.

4.1 Merchant Profile

FieldTypeDescription
emailAddressStringMerchant email address.
registeredMobileNumberStringRegistered mobile number.
countryStringMerchant's country.
cityStringMerchant's city.
parentBusinessUnitIdUUIDParent business unit identifier.
businessCategoryIdUUIDBusiness category identifier.
currencyCodeStringMerchant currency code.
nameStringMerchant name.
nameARStringMerchant name in Arabic.
activeBooleanIndicates whether the merchant is active.
feeProfileIdNumberFee profile identifier.
settlementCycleStringSettlement cycle, with T_PLUS_3 shown as the example value.
enableMoyasarBooleanIndicates whether Moyasar integration is enabled.
moyasarFeesPresentWhenEnabledBooleanIndicates whether Moyasar fee information is present when enabled.

4.2 Merchant Logo

The logo object contains the merchant's logo metadata.

FieldTypeDescription
logo.fileSizeNumberFile size.
logo.fileUrlStringFile URL.
logo.fileNameStringFile name.

4.3 Fee Setup

The feeSetup object defines fee values for the payment methods and transaction types shown in the API schema.

FieldTypeDescription
feeSetup.madaObjectMada fee configuration.
feeSetup.visaMcObjectVisa and Mastercard fee configuration.
feeSetup.applePayObjectApple Pay fee configuration.
feeSetup.refundObjectRefund fee configuration.
percentageRateNumberPercentage-based fee rate.
fixedAmountNumberFixed fee amount.

Each of the four nested fee objects contains percentageRate and fixedAmount.

4.4 Moyasar Configuration

The moyasar object contains configuration details for the Moyasar integration.

Merchant Information

FieldTypeDescription
moyasar.typeStringEntity type; the example uses establishment.
moyasar.nameStringName associated with the Moyasar configuration.
moyasar.countryStringCountry associated with the configuration.
moyasar.emailStringContact email address.
moyasar.adminEmailStringAdministrator email address.
moyasar.ownersCountIntegerNumber of owners.
moyasar.signatoryStringSignatory information.
moyasar.activityLicenseRequiredBooleanIndicates whether an activity license is required.
moyasar.websiteStringWebsite address.
moyasar.publicNameStringPublic-facing name.
moyasar.signatoryCountIntegerNumber of signatories.
moyasar.timeZoneStringConfigured time zone.
moyasar.statementDescriptorStringStatement descriptor.

Payment Configuration

FieldTypeDescription
moyasar.enabledSchemesArray of StringsEnabled payment schemes.
moyasar.paymentMethodsArray of StringsConfigured payment methods.
moyasar.taxInclusiveBooleanIndicates whether fees are tax-inclusive.

Moyasar Fees

The moyasar.fees field is an array of fee configuration objects.

FieldTypeDescription
moyasar.fees[].familyStringFee family identifier or name.
moyasar.fees[].rateNumberFee rate.
moyasar.fees[].fixedNumberFixed fee amount.
moyasar.fees[].capNumberFee cap.

Moyasar Documents

The moyasar.documents field is an array of document objects.

FieldTypeDescription
moyasar.documents[].typeStringDocument type.
moyasar.documents[].fileObjectDocument file metadata.
moyasar.documents[].file.fileSizeNumberFile size.
moyasar.documents[].file.fileUrlStringFile URL.
moyasar.documents[].file.fileNameStringFile name.
moyasar.documents[].infoObjectAdditional document information.

The info object is represented by generic properties in the supplied Swagger example. Its exact structure is not specified.

5. Example Request

The following JSON follows the supplied Swagger example. Replace the placeholder values with valid merchant information and configuration.

{
  "emailAddress": "[email protected]",
  "registeredMobileNumber": "+31-09942731692787",
  "country": "string",
  "city": "string",
  "parentBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "businessCategoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "logo": {
    "fileSize": 0,
    "fileUrl": "string",
    "fileName": "string"
  },
  "currencyCode": "string",
  "name": "string",
  "nameAR": "string",
  "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_3",
  "enableMoyasar": true,
  "moyasar": {
    "type": "establishment",
    "name": "string",
    "country": "string",
    "email": "string",
    "adminEmail": "string",
    "ownersCount": 1,
    "signatory": "string",
    "activityLicenseRequired": true,
    "website": "string",
    "publicName": "string",
    "signatoryCount": 1,
    "timeZone": "string",
    "statementDescriptor": "string",
    "enabledSchemes": [
      "string"
    ],
    "paymentMethods": [
      "string"
    ],
    "fees": [
      {
        "family": "string",
        "rate": 1,
        "fixed": 0,
        "cap": 0
      }
    ],
    "taxInclusive": true,
    "documents": [
      {
        "type": "string",
        "file": {
          "fileSize": 0,
          "fileUrl": "string",
          "fileName": "string"
        },
        "info": {
          "additionalProp1": {},
          "additionalProp2": {},
          "additionalProp3": {}
        }
      }
    ]
  },
  "moyasarFeesPresentWhenEnabled": true
}

Important: The values above are illustrative Swagger examples. They do not establish which fields are mandatory or which fee values are valid.

6. cURL Example

curl --request POST \
  --url 'https://app-api.edfapay.com/api/v1/merchant' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'Accept: */*' \
  --data '{
    "emailAddress": "[email protected]",
    "registeredMobileNumber": "+31-09942731692787",
    "country": "string",
    "city": "string",
    "parentBusinessUnitId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "businessCategoryId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "logo": {
      "fileSize": 0,
      "fileUrl": "string",
      "fileName": "string"
    },
    "currencyCode": "string",
    "name": "string",
    "nameAR": "string",
    "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_3",
    "enableMoyasar": true,
    "moyasar": {
      "type": "establishment",
      "name": "string",
      "country": "string",
      "email": "string",
      "adminEmail": "string",
      "ownersCount": 1,
      "signatory": "string",
      "activityLicenseRequired": true,
      "website": "string",
      "publicName": "string",
      "signatoryCount": 1,
      "timeZone": "string",
      "statementDescriptor": "string",
      "enabledSchemes": ["string"],
      "paymentMethods": ["string"],
      "fees": [
        {
          "family": "string",
          "rate": 1,
          "fixed": 0,
          "cap": 0
        }
      ],
      "taxInclusive": true,
      "documents": [
        {
          "type": "string",
          "file": {
            "fileSize": 0,
            "fileUrl": "string",
            "fileName": "string"
          },
          "info": {
            "additionalProp1": {},
            "additionalProp2": {},
            "additionalProp3": {}
          }
        }
      ]
    },
    "moyasarFeesPresentWhenEnabled": true
  }'

7. Responses

7.1 HTTP 200 — OK

Description: The request was processed successfully.

Example response:

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

7.2 HTTP 400 — Bad Request

Description: The request could not be processed because of invalid input or another request-related issue.

Example response:

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

The values shown are Swagger placeholders and may differ from actual runtime responses.

8. Implementation Notes

  • Provide valid UUIDs for parentBusinessUnitId and businessCategoryId.
  • Confirm that the selected business unit, business category, and fee profile are valid for the intended merchant.
  • Use valid email addresses, mobile numbers, currency codes, and logo metadata.
  • Verify the accepted values for settlementCycle, moyasar.type, enabledSchemes, and paymentMethods.
  • Confirm the required Moyasar fields and document requirements before enabling the integration.
  • Validate fee values according to the applicable merchant configuration.
  • The supplied schema does not specify the full list of allowed enum values, field-level validation rules, or additional HTTP response codes.
  • Handle 400 Bad Request responses using the returned error details.

9. Summary

The Create Merchant API creates a merchant record with profile and contact information, business associations, currency, fee configuration, settlement preferences, and Moyasar integration settings.

Refer to the API schema for the exact request structure and to the live implementation for validation rules and supported configuration values.


Did this page help you?