Create, reactivate, update, patch or upload documents for a merchant (V2)
/api/v1/merchants/merchant-associationV2Version 2 of the merchant association endpoint. The action field picks the operation. create onboards a merchant and also accepts full onboarding sections (bankDetails, businessDetails, ownerDetails, tradingDetails, businessDealDetails). reactivate extends an expired signup link. update changes the credentials of a user who has not yet completed signup. patch fills in onboarding data for an existing merchant. uploadDocuments queues up to 5 base64-encoded KYC documents for the merchant and returns HTTP 202.
Endpoint destination URL
https://portal-api-sandbox.datmancrm.com/merchants/sandbox/api/v1/merchants/merchant-associationV2ApiKeyAuthapi_key<token>Partner API key issued by Datman.
Request Parameters
application/json- body
Fields depend on action. The onboarding sections (bankDetails, businessDetails, ownerDetails, tradingDetails, businessDealDetails) are required on create and optional on patch. Other top-level fields follow the same per-action rules as the V1 endpoint, and fields not allowed for an action are rejected. uploadDocuments accepts only action, merchantId and attachments.
action*stringOperation to perform.
"create""reactivate""update""patch""uploadDocuments"storeId?stringNumeric store identifier. create only. Required unless isPartner is true, and not allowed when isPartner is true.
^\d+$length <= 10isPartner?booleancreate only (required). Set true to onboard a delivery partner without a storeId. Must be true when storeId is omitted.
webhookUrl?stringHTTPS URL that receives onboarding webhooks for the merchant created with create.
^https://urilength <= 200email?stringMerchant owner email. create only (required). The server converts it to lower case.
emaillength <= 254phoneNumber?stringMerchant owner phone number. create only (required).
^\+\d{7,15}$country?stringMerchant country. create only (required). Also decides the country-specific rules for the onboarding sections.
"United Kingdom""Ireland""Australia""New Zealand""Canada""United States""Mexico"firstName?stringOwner first name. create only (required).
1 <= length <= 80lastName?stringOwner last name. create only (required).
1 <= length <= 80businessName?stringLegal business name. create only (required).
1 <= length <= 80tradingName?|Trading name. create only, optional. Empty string or null is allowed.
length <= 80changeOfownership?booleanWhether this is a change of ownership of an existing store. create only (required).
isReseller?booleanWhether the merchant is a reseller. create only (required).
merchantId?stringDatman merchant ID. Required for reactivate, patch and uploadDocuments. Must be sent as a string.
^\d+$length <= 100resellerId?stringOptional reseller ID (2-7 digits).
^\d{2,7}$countryOverride?booleancreate only, optional. When true, skips the check that country matches the reseller's configured country.
platform?array<>IDs of the platforms to onboard on, as agreed with Datman. If omitted, the merchant is onboarded on all platforms.
businessType?|create only, optional. Allowed values depend on country (same rules as V1).
"Limited""Partnership""Sole Trader""Individual""Trust""Other""Corporation"""nulloldCredentials?Current user credentials. update only (required).
newCredentials?New user credentials. update only (required). Must differ from oldCredentials.
overrideDetails?|patch only. When false (default), only fields that are empty on the merchant are filled in. Fields that already have a value are skipped and listed in skippedFields. When true, existing values are overwritten.
falsetruefalse"true""false"isSyncEnabled?|patch only. When true (default), the patched data is synced to the payment provider (transfer instrument, legal entity and business line updates).
truetruefalse"true""false"attachments?array<>uploadDocuments only (required). At most one attachment per documentTypeId. File names must not repeat, and the decoded total must be 25 MB or less.
1 <= items <= 5bankDetails?|Bank account details. Required on create, optional on patch. May be sent encrypted as { "encryptedData": "..." }.
businessDetails?Business details. Required on create, optional on patch. businessType, organisationType and trustType can't be changed with patch; they are ignored and listed in ignoredFields.
ownerDetails?Owner details. Required on create, optional on patch.
tradingDetails?Trading details. Required on create, optional on patch.
businessDealDetails?Commercial terms agreed with the reseller. Required on create. Validated on patch but not stored by it.
Response parameters & Errors
Action processed (create, reactivate, update or patch). Some business-rule outcomes also come back as HTTP 200: update with a Datman internal statusCode 4005-4009, reactivate when the merchant or link isn't found, and every patch failure (merchant not found, nothing to update, validation errors).
application/json- response
Result of the action. create returns the merchant fields. reactivate returns message. update returns message and statusCode. patch returns message, merchantId and optionally the skipped and ignored field lists.
message?|array<>Human-readable outcome. For a patch that fails validation, this is an array of field errors.
statusCode?integerDatman internal outcome code (not an HTTP status), e.g. 6003 credentials updated, 4005-4009 update not possible.
merchantId?|Datman merchant ID. An integer on create, a string on patch.
merchant_status?unknownMerchant status value stored on the merchant record (create).
account_verification_status?booleanWhether the merchant account is verified (create).
bank_verification_status?booleanWhether the merchant bank account is verified (create).
email?stringOwner email (create).
emailresponseCode?integerOnboarding flow indicator (create). 1001 = staggered onboarding only. 1002 = owner or business details were supplied and will be applied after onboarding, so the account might become unverified.
10011002businessName?stringLegal business name (create).
tradingName?stringTrading name (create).
signup_link?stringPortal link for the new user to complete signup. Only present when a new user was created.
skippedFields?array<string>patch only. Dot-notation paths of fields not updated because they already have a value and overrideDetails was false.
skippedMessage?stringpatch only. Explains skippedFields.
ignoredFields?array<string>patch only. Fields that can't be changed with patch and were ignored (e.g. businessDetails.businessType).
ignoredMessage?stringpatch only. Explains ignoredFields.