Datman glossary
This glossary contains the terms used in the Datman API and in the payments industry, and should help to demystify the world of payments.
3D Secure (3DS)
An authentication step in which the card issuer checks that the person paying is the cardholder, for example with a challenge in their banking app. When a payment needs 3D Secure, the shopper is redirected to complete the check, and the result of the payment comes back after they complete it.
Acquirer
A bank or financial institution that receives funds for a merchant from a shopper.
Datman processes your merchants' payments through multiple acquirers, so that you integrate once with Datman instead of with each acquirer separately.
Adjustment
A modification that changes the authorised amount of a pre-authorised payment before it is captured. You identify the payment with its xref. See Adjust the amount of a pre-authorised payment.
API key
The credential that identifies your reseller account in API requests. You send it in the api_key header. Some endpoints take the same key in the X-API-Key header, which is case-sensitive. See Authentication.
Your API key only gives access to your own merchants. Keep it on your server, and never put it in a browser or mobile app.
Authorisation reversal
A modification that releases the funds reserved by a pre-authorised payment, so that the shopper is not charged. You can only reverse a payment that has not been captured. See Reverse a pre-authorisation.
Balance
The amount held for a merchant in their Datman account. The available balance is in major currency units, for example 24.50 for GBP 24.50. See Get account balance.
Capture
A modification that completes a pre-authorised payment, so that the reserved funds are transferred from the shopper to the merchant. You identify the payment with its xref, and you can send new split instructions with the capture.
Capture is asynchronous. Datman sends a paymentStatus webhook when it is done. See Capture a pre-authorised payment.
Chargeback
A shopper's request to their card issuer to return funds paid to a merchant. Typically, chargebacks occur after the merchant has refused a refund.
The chargebacks of a payment are listed with its transaction details.
Datman account
The account in which a merchant's funds are held from the moment the shopper pays until they are paid out. You can check how much it holds with the merchant's balance.
Delivery partner
A merchant that has no shop, for example a delivery company. You create it with isPartner set to true and no storeId. A delivery partner can receive part of another merchant's payment as a split, for example a delivery fee.
Embedded dashboard
A Datman merchant dashboard that you can show inside your own website or app. Your server requests a dashboard URL for a merchant and a page (overview, payment or payout), and the session is valid for 10 minutes.
Fee tier
The pricing plan assigned to a merchant: a percentage and a fixed amount charged for each transaction. You can see it in the merchant's payment configuration, together with your own reseller pricing on top of the tier.
HMAC signature
A signature that proves a webhook came from Datman. It is the HMAC-SHA256 of the request body, computed with your webhook secret and hex-encoded. Payment webhooks carry it in the HMACSignature header, and internal transfer webhooks in the X-Datman-Signature header. See Webhooks.
Hosted payment page
A card form that Datman hosts. Instead of sending an API request, your server encrypts the payment details and sends the shopper's browser to Datman. Datman takes the payment, sends the shopper back to you, and tells your server the result with a webhook. See Hosted payment page.
Internal transfer
A movement of funds from one merchant's Datman account to another's. Note that the amount of an internal transfer is in minor units, for example 350 for GBP 3.50, unlike other amounts in the API. Datman sends a webhook when the transfer succeeds or fails. See Transfer funds between two merchants.
Know Your Customer (KYC)
The process of identifying and verifying a merchant's business and owners. This is required by payment industry regulations before merchants can be paid out.
You collect the merchant's business, owner and bank details and documents, and Datman runs the verification checks. You can follow the progress with the merchant's account status.
Liable account
A merchant account, with its own MID, that belongs to you rather than to one of your merchants. It is where you keep your share of the money, for example the splits or charges you collect. Every other MID is a normal merchant account. You can ask Datman for several liable accounts, to reconcile different splits or charges separately.
Merchant
The party selling goods or services to shoppers, for example a restaurant or a takeaway. In Datman, each merchant has a MID, a verification status, a bank account, a fee tier and a payout schedule.
The merchants you bring to Datman remain yours: you own the relationship with them. These docs call them "your merchants".
Merchant portal
The app where your merchants log in to see their balance, payouts, transactions and reports. With the merchant portal, you do not need to build your own app for your merchants to see their payments. You can also use the APIs and webhooks to build these views for your merchants yourself.
MID (Merchant ID)
The number that identifies a merchant in Datman, for example 12345678. One shop is one merchant with one MID. Datman issues the MID when you create the merchant.
The MID appears in the API as merchant_id, merchantId or mid. All three are the same number.
Modifications
Actions that change a payment after it was made: capture, adjustment, authorisation reversal and refund. They are called modifications, because they modify the state of a payment.
You make a modification with an API request, and the response only acknowledges it. Datman sends the result asynchronously with a webhook.
Onboarding link
A link that you send to a merchant so that they can complete onboarding themselves, for example to add missing details or upload documents. Send your merchant the hosted onboarding link, which is returned in the merchant's onboarding record.
Order reference
Your own identifier for an order, sent as order_id when you take a payment. Datman echoes it back in webhooks and you can use it to search transactions. Datman's own reference for the payment is orderRef.
Outcome
The result of a payment or modification request, in the outcome field of the response: success or failed.
Payment service provider (PSP)
A company that combines the functions of a payment gateway and a payment processor, and connects to multiple acquiring and payment networks.
Datman is a PSP and gateway that sits on top of multiple acquirers. For resellers and platforms, it is often more convenient to use one PSP than to have separate contracts with different gateways, processors and acquirers.
Payout
A transfer of a merchant's settled funds from their Datman account to their verified bank account. When payouts happen depends on the merchant's payout schedule. See List payouts.
Payout schedule
The rule that decides when a merchant's funds are paid out, for example every weekday at 07:00. It is set as a cron expression in the timezone of the merchant's account. See the payout schedule.
Platform
A business, such as an ordering platform, that brings its own merchants to Datman and takes payments on their behalf.
Pre-authorisation
A payment that is only authorised: the funds are reserved on the shopper's card, but not yet transferred. You can then capture it, adjust its amount, or reverse it.
Refund
A modification that returns the funds of a payment to the shopper, after the payment was completed. You identify the payment with your order_id and the MID. If the payment was split, you can also say how much to take back from each merchant that received part of it. See Refund a payment.
If a merchant refuses to make a refund, a shopper can ask their issuer for a chargeback.
Reseller (or ISO)
A business, such as an independent sales organisation (ISO), that brings merchants to Datman. A reseller owns the relationship with its merchants and earns commission on their payments. Your API key belongs to your reseller account, and only gives access to your own merchants. See Resellers.
Settlement
The moment when Datman makes a payment's funds available to the merchant, after the settlement delay. Settled funds are then paid out. See Flow of funds.
Settlement delay
The waiting period between a payment and its settlement. It is usually two business days (T+2), and can be one (T+1) or four (T+4), depending on what was agreed when the merchant was onboarded. Weekends and bank holidays are not counted. It is returned as settlement_delay in the merchant's payout schedule.
Shop
The physical location or outlet of a merchant's business, such as one takeaway. One shop is one merchant with one MID. When you create the merchant, you send storeId: your own identifier for the shop.
We recommend creating one merchant, with its own MID, for each shop. You can use one MID for several shops, but this makes reconciliation harder. When a business has several shops, you can create the merchant for each new shop with the same business documents. The new merchant then does not need to be verified again, and is approved quickly.
This feature is in beta. Contact Datman support before you go live with it.
Shopper
A customer who buys goods or services from a merchant. In these docs, a shopper pays by card or digital wallet.
Split commission type
The label that says what a split is for, sent as type_id. Datman provides global types: 1 Food/Goods, 2 Marketplace Fee, 3 Delivery Fee, 4 Delivery Tip, 5 Restaurant Tip and 6 Service Charge. You can also create your own types. See Split commission types.
Split payment
A payment that is divided between the merchant that took it and one or more other merchants, for example a delivery fee for a delivery partner. Each split names the receiving partner_merchant_id, a split commission type, and a value as an amount or a percentage. See Get the revenue split breakdown for a transaction.
Staggered onboarding
A way of onboarding where only the minimum verification information is collected before a merchant starts taking payments. More information is needed as the merchant's total processed amount grows: up to 1,000 on Tier 1, up to 5,000 on Tier 2, and fully verified above that. The merchant can always take payments, but their payouts are blocked until they submit the information for their tier. See Staggered onboarding.
A way of onboarding in which a merchant can start taking payments with minimal details, and completes verification later. The reseller summary shows how many of your merchants are fully verified and how many are in staggered onboarding.
Webhooks
HTTP callbacks that Datman sends to an endpoint on your server. They inform you about payments, modifications and internal transfers. You send the URL of the endpoint as webhook_url with the request.
Webhooks are crucial for a successful integration, because many results, such as a capture, only arrive asynchronously. Always verify the HMAC signature before trusting a webhook. See Webhooks.
xref
Datman's cross-reference for a payment, in the format O<order_id>M<merchant_id>T<payment_id>. You need it to capture, adjust or reverse a pre-authorised payment. It is returned in the paymentStatus webhook.