Manage merchants

A merchant is the main resource that represents a business you bring to Datman. Each shop is one merchant, with one merchant ID (MID). The merchant holds the business, owner, bank and trading details that Datman uses to verify the business, and its onboarding and verification status. To manage merchants, use the Merchants API.

This page contains instructions for common merchant operations. These operations are part of a larger process, which includes onboarding and verification.

Create a merchantCopy Anchor Link

To create a merchant:

1. Send a Create a merchant request with action create and the following parameters:

   Parameter	Required	Description
   action	Required	create
   storeId	Conditionally required	Required unless isPartner is true. Your own numeric ID for the shop. Datman links one active merchant to each store.
   isPartner	Required	true to onboard a delivery partner that has no storeId. Otherwise false.
   email, phoneNumber, firstName, lastName	Required	The owner's contact details and name. phoneNumber is in E.164 format, for example +447700900000.
   country	Required	The merchant's country, as a name, for example United Kingdom. This also sets the country rules for the other details.
   businessName	Required	The legal business name.
   tradingName	Optional	The name the business trades under.
   businessType	Optional	The business type.
   changeOfownership	Required	true if a new owner is taking over a store that already had a merchant.
   isReseller	Required	true if the merchant is itself a reseller.
   platform	Optional	The platforms to onboard the merchant on, by ID, for example 1 for Mypay, the Datman platform. If you leave it out, the merchant is onboarded on all platforms.
   webhookUrl	Optional	An HTTPS URL that receives onboarding webhooks for this merchant.
   bankDetails, businessDetails, ownerDetails, tradingDetails, businessDealDetails	Required	The merchant's onboarding details. Every key in these objects must be present, but you can send an empty string for details you don't have yet or that don't apply to the merchant's country. See Manage merchant details.

   The API Explorer has the full Create a merchant request, with examples you can try.

2. The response contains the new merchant's merchantId. This is the merchant's MID. Save it, because you need it to:

   • Check the merchant's onboarding and verification status.
   • Update the merchant's details and upload their KYC documents.
   • Take payments for the merchant.

   Response

   Copy Text

   {
     "message": "New merchant account has been created and has been added to the [email protected]",
     "merchantId": 1000001,
     "merchant_status": 0,
     "account_verification_status": false,
     "bank_verification_status": false,
     "email": "[email protected]",
     "responseCode": 1002,
     "businessName": "Example Pizza Ltd",
     "tradingName": "Example Pizza",
     "signup_link": "https://portal.example.com/example-partner"
   }

   The response also contains:

   • responseCode: 1001 means the merchant is on staggered onboarding only. 1002 means the owner or business details you sent are applied after onboarding, so the merchant's account might become unverified.
   • signup_link: a link for your merchant to complete sign-up for the merchant portal. It is only present when Datman created a new user.

3. Check the onboarding status of the merchant to see the result of the verification checks.

Note that if the store is already linked to an active merchant, the response is HTTP 400 and contains the existing merchantId. Repeated requests for the same store ID or from the same IP address can return HTTP 429.

We recommend using this request instead of the older Create, reactivate or update a merchant association request, because only version 2 accepts the full onboarding details and KYC documents.

View merchantsCopy Anchor Link

To view a merchant, get the merchant summary with the merchant ID as a path parameter. The response shows information such as:

• The merchant's name and country, and the ID of the reseller that owns it (canonical_reseller_id).
• The status of each onboarding area: account_status, payout_status, business_status, owners_status, bank_status and tos_status.
• Whether the merchant is itself a reseller (is_reseller), and whether it is liable (is_liable).

You can only view merchants that belong to your reseller. For any other merchant ID, the response is HTTP 404.

To view the merchant's details, see View merchant details. To view the merchant's fee tier, your reseller fees on top of it, and the merchant's transaction limits, get the payment configuration of the merchant.

Filter and searchCopy Anchor Link

To find merchants in your portfolio, list the onboarding status of your merchants with enablePagination true, and search set to a merchant name, trading name or merchant ID. See Reseller onboarding insights.

Liable merchantsCopy Anchor Link

A liable merchant is a merchant account that is owned by your business, not by one of your merchants. It is where you keep your share of the money: for example, the splits or charges that you collect. Every other MID is a normal merchant account for one of your merchants.

You can ask Datman for several liable accounts, so that you can reconcile different splits or charges separately.

To list only liable merchants, send isLiableOnly true in the same request.

Update a merchantCopy Anchor Link

After you create a merchant, you can change the sign-in details of its user, or extend its signup link.

• To change the email address or phone number of a user who has not completed sign-up yet, send an Update a merchant request with action update, the current details in oldCredentials, and the new details in newCredentials. When the update succeeds, the response contains statusCode 6003.
• To extend an expired signup link, make the same request with action reactivate and the merchantId.

Note that some outcomes come back with HTTP 200 but did not succeed, for example when the user can't be found. In that case, the response contains a message and a Datman statusCode between 4005 and 4009.

To update the merchant's business, owner, bank or trading details, see Update merchant details.

View the account and payout statusCopy Anchor Link

You can see whether your merchant's account is active and whether payouts are enabled. Get the merchant account status. In the verification_status object of the response, note the following parameters:

• account_status: the status of the merchant's account, for example ACTIVE.
• payout_status: ACTIVE when payouts are enabled for the merchant, INACTIVE when they are not.
• issues: a list of outstanding verification problems. When this list is not empty, there are problems that your merchant must fix.

For all possible values, see Verification statuses.

Manage KYCCopy Anchor Link

The Know Your Customer (KYC) checks are part of the verification process. Datman runs them to make sure that your merchants have provided accurate information about their businesses.

View the KYC summaryCopy Anchor Link

You can see where your merchant is in the verification process, and which issues are outstanding. Use this to help your merchant fix problems during onboarding.

Get the onboarding status of the merchant. The response shows the status of each check (business, owners, bank and terms of service), and an errors array. Each entry in errors has:

• title: the category of the issue, for example Bank Issues.
• field: the field or requirement concerned, for example Upload a bank statement.
• reported_at: when the issue was reported, if known.

For the meaning of each status, see Verification statuses.

View KYC documentsCopy Anchor Link

You can view which documents are on file for your merchant. This covers the merchant's own documents, those of its associated people (for example owners and signatories), and those for its bank account.

List the KYC documents of the merchant. For each document, the response contains its file name and uploaded_at time. The response never contains the document itself.

Use this to help your merchants fix verification issues, for example a missing bank statement. Note that the list is empty if the merchant has no documents yet, or if Datman can't retrieve them at that moment.

See alsoCopy Anchor Link

• Manage merchant details
• Verification statuses
• Onboard and verify merchants