Manage merchant details
View and manage your merchants' business, owner and bank details.
Merchant details describe the business behind a merchant: its legal and trading names, registration number and addresses, its owner, and the bank account it is paid out to. Datman uses these details to run verification checks, as required by payment industry regulations.
The details are grouped in five objects:
businessDetails: the business type, company registration number, registered address and contact details.ownerDetails: the owner's name, date of birth, nationality, tax and identity numbers, home address and contact details.bankDetails: the bank account that the merchant is paid out to.tradingDetails: the trading name and trading address.businessDealDetails: the commercial terms you agreed with the merchant, such as the setup fee and the fee per transaction.
To manage merchant details, use the Merchants API and the KYC & Verification API.
This page contains instructions for common operations on merchant details. These operations are part of a larger process, which includes onboarding and verification.
Requirements
Before you begin, take into account the following requirements, limitations, and preparations.
| Requirement | Description |
|---|---|
| Integration type | A reseller or platform integration with Datman. |
| API credentials | Your partner API key, sent in the api_key header. To upload documents with a multipart request, you need the separate document upload key. See Authentication. |
Send merchant details
Sending complete and correct details is the first step in moving your merchant through verification. You send the details when you create the merchant.
The details that apply depend on the merchant's country. On create, every key in each object must be present. Send an empty string for any detail that doesn't apply to the merchant's country. Note that if a value fails its format check, Datman stores it as an empty string instead of rejecting the request, so check the formats below before you send.
Bank details
| Country | Bank details |
|---|---|
| United Kingdom | bankSortCode (6 digits) and accountNumber (8 digits) |
| Ireland | ibanNumber (22 characters) |
| Australia | bsbNumber (6 digits) and accountNumber (5–9 digits) |
| New Zealand | accountNumber (15–16 digits) |
| Canada | transitNumber (5 digits), financialInstitutionNumber (3 digits) and accountNumber (7–12 digits) |
| United States | routingNumber (9 digits) and accountNumber (3–17 digits) |
| Mexico | accountNumber (18 digits) |
You can also send bankDetails encrypted, as { "encryptedData": "..." }. Datman decrypts it with your encryption key.
Owner identifiers
| Country | Identifier |
|---|---|
| United Kingdom | vatNumber: GB followed by 9 digits, if the owner has a VAT number (vatExists true) |
| Ireland | ppsNumber: 7 digits followed by 1 or 2 letters |
| Australia | abnNumber: 11 digits |
| United States | einNumber or ssnNumber: 9 digits |
| Mexico | personalId: letters and digits |
Addresses
For merchants in Australia and the United States, state is required in the business and owner addresses, and must be a valid state code. For other countries, state is free text and can be empty.
Upload KYC documents
Your merchant may need to provide documents, for example an identity document or a bank statement. You can upload them in a JSON request or as a file upload.
Send an Upload documents request with action uploadDocuments, the merchantId, and an attachments array. For each document, send:
| Parameter | Required | Description |
|---|---|---|
documentTypeId | Required | The document type. You can send one document per type. |
filename | Required | The file name, ending in .pdf, .jpg, .jpeg or .png. File names must not repeat. |
content | Required | The file, base64-encoded. Up to 10 MB decoded. The content must match the file extension. |
You can send up to 5 documents in one request, up to 25 MB in total.
The response is HTTP 202 with statusCode 10005: Datman has accepted the documents and attaches them to the merchant shortly. If you sent only one side of a two-sided document, statusCode is 10006 and reminder tells you which side is still needed.
Document types
documentTypeId | Document |
|---|---|
| 1 | Bank statement |
| 2 | Business rates bill |
| 3 | Driving licence (front) |
| 4 | Passport |
| 5 | Rental agreement |
| 6 | Residency permit |
| 7 | Utility bill |
| 8 | Void cheque |
| 9 | Identity card (front) |
| 10 | Identity card (back) |
| 11 | Business registration certificate |
| 12 | Street view |
| 13 | Food hygiene certificate |
| 14 | Proof of organisation tax information |
| 15 | VAT document |
| 16 | Proof of director |
| 17 | Driving licence (back) |
For a driving licence or identity card, upload the front and the back as separate documents.
To check which documents are on file, see View KYC documents.
View merchant details
After you create a merchant, you can view its details at any time with the following requests. Use the merchant ID as a path parameter.
| Details | API reference | Response contains |
|---|---|---|
| Business | Get business details | Legal and trading names, company and VAT numbers, legal entity type, industry, contact details, and the registered and trading addresses. |
| Owner | Get primary owner details | The primary owner's name, contact details, date of birth, nationality, ownership percentage and home address. owner_details is null when there is no primary owner on file. |
| Bank | Get bank details | The payout bank account. Account identifiers are masked: only the last 3 characters are shown, for example ****234. status shows whether the account is verified, and verified_on is set only when status is Verified. |
Note that the owner details response contains the owner's personal data unmasked. Show it only to people who need it.
Update merchant details
When your merchant's details change, or when details were missing at onboarding, update them. To update merchant details:
-
Send a Patch merchant details request with
actionpatch, themerchantId, and only the objects and keys you want to change. You can also send:overrideDetails: false (default) to fill in only details that are empty. true to overwrite details that already have a value.isSyncEnabled: true (default) to send the updated details on for verification. false to only update them in Datman.
The API Explorer has the full request, with examples you can try.
-
The response contains a
messageand themerchantId. It can also contain:skippedFields: details that were not updated because they already have a value andoverrideDetailswas false.ignoredFields: details that you can't change with a patch. These arebusinessDetails.businessType,businessDetails.organisationTypeandbusinessDetails.trustType.
Note that a patch that fails, for example because the merchant isn't found or a value is invalid, still returns HTTP 200. Check the message: for validation errors it is an array of key and error pairs. Also note that a patch validates businessDealDetails but doesn't store it.
Copy details to another platform
If your merchant is onboarded on Mypay and on another platform, you can copy its legal entity details from Mypay to that platform. Send a Trigger a legal entity sync between platforms request with the merchantId, and your API key in the X-API-Key header. The response contains message Your request is initiated: Datman queues the sync.
Sync must be enabled for your reseller. If it isn't, the response is HTTP 403.