MID Creation & Association

Merchant Creation and Association API Request ( V2 )

The Merchant Creation and Association API is used to register a new merchant on the platform and link (associate) the merchant with the appropriate configuration, such as a payment provider, business group, or partner entity.

Things to note

Top-level (request)

action — string; required: must be exactly "create".

storeId — numeric string (0–10 digits); optional: any numeric value up to 10 digits. Do not send when isPartner is true.

isPartner — boolean; required for partner identification: true for delivery partners, false for merchants. If true, storeId must not be present.

email — string; required: valid merchant email. Must be unique for merchant creation; if the email already exists it will be associated with the same storeId but a new merchantId will be created.

phoneNumber — string; required: must include country code, e.g. +441234567890.

country — string; required: allowed values: UK, Ireland, NZ, Australia, US, Canada, Mexico.

firstName — string; required: value provided by merchant / FH team (≤ 100 chars).

lastName — string; required: value provided by merchant / FH team (≤ 100 chars).

businessName — string; required: value provided by merchant / FH team (≤ 100 chars).

changeOfownership — boolean; required: true means the provided email denotes ownership; if false and you try to associate the same email to another owner, an error is thrown.

isReseller — boolean; required: stored for possible future requirements.

resellerId — string; optional: accepts 77 (O2M) or 278 (BigTable). If left blank, defaults to normal merchant.

Business rules / behavior

Only action = "create" is accepted by this endpoint for merchant creation.

If an email duplicates an existing merchant email, the system associates that email with the same storeId and returns/creates a new merchantId.

When isPartner: true (delivery partner), do not pass storeId.

changeOfownership controls ownership enforcement — setting it to true marks the email as owner; setting to false and attempting re-association will raise an error.

bankDetails

accountName — string; ≤ 100 chars: uppercase allowed, alphanumeric + permitted special chars.

bankSortCode — string; 6 digits.

ibanNumber — string; required: format depends on country (Ireland: exactly 22 chars; others: up to 36 chars).

bsbNumber — string; 6 digits (Australia).

transitNumber — string; 5 digits (Canada).

financialInstitutionNumber — string; 3 digits (Canada).

routingNumber — string; 9 digits (US).

accountNumber — string; numeric:

UK = exactly 8 digits

Australia = 5–9 digits

New Zealand = 15–16 digits

US = 3–17 digits

Mexico = exactly 18 digits

Canada = 7–12 digits

Others = up to 30 digits

bankName — string; ≤ 100 chars: alphanumeric + limited special chars.

addressLine1 / addressLine2 — string; ≤ 100 chars: alphanumeric + permitted special chars.

businessDetails

businessType — string; required: must match allowed types for the selected country.

companyRegistrationNumber — string; numeric; ≤ 30 chars.

organisationType — string; required: must be one of organisationTypeEnum.

trustType — string; required: must be one of trustTypeEnum.

addressLine1 / addressLine2 — string; ≤ 100 chars.

state — string: must be valid state code for Australia/US (when country is those), otherwise free text ≤ 100 chars.

city / county — string; ≤ 100 chars.

country — string; ≤ 80 chars: alphanumeric + hyphen.

postCode — string; ≤ 100 chars.

contact.phoneNumber — string; optional: valid international phone number or empty.

contact.email — string; required: valid email.

contact.website — string; required: valid http:// or https:// URL.

ownerDetails

title — string; required: one of ownerTitle.

firstName / lastName — string; ≤ 100 chars: alphanumeric + permitted special chars.

citizenship — string; required: one of nationalities.

dateOfBirth — string; required: format YYYY-MM-DD.

abnNumber — string; 11 digits (Australia).

einNumber — string; 9 digits (US).

ssnNumber — string; 9 digits: must not match invalid SSN patterns.

personalId — string; ≤ 100 chars: alphanumeric.

ppsNumber — string; 7 digits + 1–2 uppercase letters (Ireland).

irdNumber — string; 8-9 digit (New Zealand). //new changes to be released soon

vatNumber — string; required/conditional: UK format must start with GB + 9 digits and pass checksum validation.

vatExists — boolean or empty string.

addressLine1 / addressLine2 — string; ≤ 100 chars.

state — string: must be valid AU/US state if applicable, otherwise free text ≤ 100 chars.

city / county / country / postCode — string; ≤ 100 chars.

contact.phoneNumber — string; required: valid international phone number.

contact.email — string; required: valid email.

tradingDetails

name — string; ≤ 100 chars: trading name.

addressLine1 / addressLine2 — string; ≤ 100 chars.

state — string: valid AU/US state if applicable, otherwise free text.

city / county / country / postCode — string; ≤ 100 chars.

businessDealDetails

setupFee — string: numeric (float allowed) as string.

monthlyRent — string: numeric (float allowed) as string.

fixedTransactionFee — string: numeric (float allowed) as string.

interchangeRate — string: numeric (float allowed) as string.

contractDurationMonths — string: integer numeric string only.

Responses

🟢200Success

application/json

Body

🟢200Create store with mid already created

🟢200Store id greater than 10 characters

🟢200Empty Fields(store_id,email,phone_number,firstname,lastname,businessName,resellerID)

🟢200Empty Country

🟢200Empty Boolean fields(isPartner,isReseller,changeOfownership)

curl --location --request POST 'https://sandbox-portal-api.datmancrm.com/merchants/sandbox/api/v1/merchants/merchant-associationV2' \ --header 'api_key: {{PLATFORM_API_KEY}}' \ --header 'Content-Type: application/json' \ --data-raw '{ "storeId": "{{store_id}}", "email": "{{merchant_email}}", "phoneNumber": "{{phone_number_with_country_code}}", "country": "{{country_code}}", // UK | Ireland | NZ | Australia | US | Canada | Mexico "firstName": "{{first_name}}", "lastName": "{{last_name}}", "businessName": "{{business_name}}", "changeOfownership": { {true_or_false } }, // true = ownership, false = error if reused "isReseller": { {true_or_false } }, "action": "create", "isPartner": { {true_or_false } }, // true = delivery partner (omit storeId), false = merchant "resellerId": "{{reseller_id_optional}}", "bankDetails": { "accountName": "{{account_name}}", "bankSortCode": "{{bank_sort_code}}", "ibanNumber": "{{iban_number}}", "bsbNumber": "{{bsb_number}}", "transitNumber": "{{transit_number}}", "financialInstitutionNumber": "{{financial_institution_number}}", "routingNumber": "{{routing_number}}", "accountNumber": "{{account_number}}", "bankName": "{{bank_name}}", "address": { "addressLine1": "{{bank_address_line1}}", "addressLine2": "{{bank_address_line2}}" } }, "businessDetails": { "businessType": "{{business_type}}", "companyRegistrationNumber": "{{company_registration_number}}", "organisationType": "{{organisation_type}}", "trustType": "{{trust_type}}", "address": { "addressLine1": "{{business_address_line1}}", "addressLine2": "{{business_address_line2}}", "state": "{{business_state}}", "city": "{{business_city}}", "county": "{{business_county}}", "country": "{{business_country}}", "postCode": "{{business_postcode}}" }, "contact": { "phoneNumber": "{{business_contact_number}}", "email": "{{business_contact_email}}", "website": "{{business_website}}" } }, "ownerDetails": { "title": "{{owner_title}}", "firstName": "{{owner_first_name}}", "lastName": "{{owner_last_name}}", "citizenship": "{{owner_citizenship}}", "dateOfBirth": "{{owner_dob}}", // format YYYY-MM-DD "abnNumber": "{{owner_abn_number}}", "einNumber": "{{owner_ein_number}}", "ssnNumber": "{{owner_ssn_number}}", "personalId": "{{owner_personal_id}}", "ppsNumber": "{{owner_pps_number}}", "vatNumber": "{{owner_vat_number}}", // "irdNumber": "{{owner_ird_number}}", "vatExists": { {true_or_false } }, "address": { "addressLine1": "{{owner_address_line1}}", "addressLine2": "{{owner_address_line2}}", "state": "{{owner_state}}", "county": "{{owner_county}}", "city": "{{owner_city}}", "country": "{{owner_country}}", "postCode": "{{owner_postcode}}" }, "contact": { "phoneNumber": "{{owner_contact_number}}", "email": "{{owner_contact_email}}" } }, "tradingDetails": { "name": "{{trading_name}}", "address": { "addressLine1": "{{trading_address_line1}}", "addressLine2": "{{trading_address_line2}}", "state": "{{trading_state}}", "city": "{{trading_city}}", "county": "{{trading_county}}", "country": "{{trading_country}}", "postCode": "{{trading_postcode}}" } }, "businessDealDetails": { "setupFee": "{{setup_fee}}", "monthlyRent": "{{monthly_rent}}", "contractDurationMonths": "{{contract_duration_months}}", "fixedTransactionFee": "{{fixed_transaction_fee}}", "interchangeRate": "{{interchange_rate}}" } }'

{ "message": "New Merchant association is successfull!", "merchantId": "{{merchant_id}}", "account_verification_status": false, "bank_verification_status": false, "email": "{{email}}", "responseCode": 1001 }