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
| Property | Value |
|---|---|
| API Name | Create Merchant |
| HTTP Method | POST |
| Endpoint | /api/v1/merchant |
| Production Base URL | https://app-api.edfapay.com |
| Content-Type | application/json |
| Accept | */* |
| Request Body | Required |
3. Authentication
Include the API key in the request headers, as required by the API configuration.
| Header | Value |
|---|---|
X-API-KEY | YOUR_API_KEY |
Content-Type | application/json |
Accept | */* |
4. Request Body
The endpoint expects a JSON object containing merchant information and configuration.
4.1 Merchant Profile
| Field | Type | Description |
|---|---|---|
emailAddress | String | Merchant email address. |
registeredMobileNumber | String | Registered mobile number. |
country | String | Merchant's country. |
city | String | Merchant's city. |
parentBusinessUnitId | UUID | Parent business unit identifier. |
businessCategoryId | UUID | Business category identifier. |
currencyCode | String | Merchant currency code. |
name | String | Merchant name. |
nameAR | String | Merchant name in Arabic. |
active | Boolean | Indicates whether the merchant is active. |
feeProfileId | Number | Fee profile identifier. |
settlementCycle | String | Settlement cycle, with T_PLUS_3 shown as the example value. |
enableMoyasar | Boolean | Indicates whether Moyasar integration is enabled. |
moyasarFeesPresentWhenEnabled | Boolean | Indicates whether Moyasar fee information is present when enabled. |
4.2 Merchant Logo
The logo object contains the merchant's logo metadata.
| Field | Type | Description |
|---|---|---|
logo.fileSize | Number | File size. |
logo.fileUrl | String | File URL. |
logo.fileName | String | File name. |
4.3 Fee Setup
The feeSetup object defines fee values for the payment methods and transaction types shown in the API schema.
| Field | Type | Description |
|---|---|---|
feeSetup.mada | Object | Mada fee configuration. |
feeSetup.visaMc | Object | Visa and Mastercard fee configuration. |
feeSetup.applePay | Object | Apple Pay fee configuration. |
feeSetup.refund | Object | Refund fee configuration. |
percentageRate | Number | Percentage-based fee rate. |
fixedAmount | Number | Fixed 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
| Field | Type | Description |
|---|---|---|
moyasar.type | String | Entity type; the example uses establishment. |
moyasar.name | String | Name associated with the Moyasar configuration. |
moyasar.country | String | Country associated with the configuration. |
moyasar.email | String | Contact email address. |
moyasar.adminEmail | String | Administrator email address. |
moyasar.ownersCount | Integer | Number of owners. |
moyasar.signatory | String | Signatory information. |
moyasar.activityLicenseRequired | Boolean | Indicates whether an activity license is required. |
moyasar.website | String | Website address. |
moyasar.publicName | String | Public-facing name. |
moyasar.signatoryCount | Integer | Number of signatories. |
moyasar.timeZone | String | Configured time zone. |
moyasar.statementDescriptor | String | Statement descriptor. |
Payment Configuration
| Field | Type | Description |
|---|---|---|
moyasar.enabledSchemes | Array of Strings | Enabled payment schemes. |
moyasar.paymentMethods | Array of Strings | Configured payment methods. |
moyasar.taxInclusive | Boolean | Indicates whether fees are tax-inclusive. |
Moyasar Fees
The moyasar.fees field is an array of fee configuration objects.
| Field | Type | Description |
|---|---|---|
moyasar.fees[].family | String | Fee family identifier or name. |
moyasar.fees[].rate | Number | Fee rate. |
moyasar.fees[].fixed | Number | Fixed fee amount. |
moyasar.fees[].cap | Number | Fee cap. |
Moyasar Documents
The moyasar.documents field is an array of document objects.
| Field | Type | Description |
|---|---|---|
moyasar.documents[].type | String | Document type. |
moyasar.documents[].file | Object | Document file metadata. |
moyasar.documents[].file.fileSize | Number | File size. |
moyasar.documents[].file.fileUrl | String | File URL. |
moyasar.documents[].file.fileName | String | File name. |
moyasar.documents[].info | Object | Additional 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
parentBusinessUnitIdandbusinessCategoryId. - 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, andpaymentMethods. - 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 Requestresponses 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.
Updated 25 days ago