openapi: 3.1.0 info: title: Onboarding version: "1" description: Onboarding status and hosted onboarding links for your merchants. tags: - name: Onboarding description: Onboarding progress and hosted onboarding links. - name: Onboarding status description: Check where a merchant is in onboarding and verification. paths: /v1/merchants/{merchantId}/onboarding: get: operationId: getMerchantOnboarding summary: Get onboarding status description: "Returns the merchant's onboarding record: section statuses, verification tier, the onboarding link, any outstanding missing details, and one merged list of onboarding errors. The `errors` list combines three sources (legacy errors, missing details and payment provider KYC errors) and keeps only the first occurrence of each field. Returns `data: {}` when the merchant has no onboarding record. The merchant must belong to your reseller, otherwise 404." tags: - Onboarding security: - ApiKeyAuth: [] parameters: - name: merchantId in: path required: true description: Numeric merchant id. Must be a positive integer belonging to your reseller. schema: type: integer minimum: 1 example: 123456 responses: "200": description: Onboarding status, or an empty object when there is no onboarding record. content: application/json: schema: $ref: "#/components/schemas/CpMerchantOnboardingResponse" examples: inProgress: summary: Onboarding with outstanding items value: data: merchant_id: 123456 merchant_name: Example Pizza Co onboarding_link: https://onboarding.example.com/start/abc123 overview_page: https://onboarding.example.com/overview/abc123 account_status: PENDING payout_status: PENDING business_status: VERIFIED owners_status: PENDING bank_status: Pending tos_status: ACCEPTED verification_tier: "1" missing_details: bank issues: - Upload a bank statement note: null country: United Kingdom errors: - title: Bank Issues field: Upload a bank statement reported_at: null - title: Individual field: identificationData.number reported_at: 2026-03-01T10:15:00.000Z noRecord: summary: Merchant without an onboarding record value: data: {} "401": $ref: "#/components/responses/Unauthorized" "403": $ref: "#/components/responses/Forbidden" "404": description: The merchant does not belong to your reseller. content: application/json: schema: $ref: "#/components/schemas/Error" examples: notFound: summary: Merchant not found or not in your reseller value: error: code: NOT_FOUND message: Merchant not found "422": description: The merchantId path segment is not a positive integer. content: application/json: schema: $ref: "#/components/schemas/Error" examples: invalidMerchantId: summary: Non-numeric merchant id value: error: code: VALIDATION_ERROR message: merchantId is required "429": $ref: "#/components/responses/RateLimited" "500": $ref: "#/components/responses/InternalError" "503": $ref: "#/components/responses/ServiceUnavailable" servers: - url: https://sandbox-portal.datmanlabs.com/api description: Sandbox /api/v1/merchants/merchant-account-status/{merchantId}: get: operationId: getMerchantAccountStatus summary: Get merchant account status description: Returns the onboarding, bank and account verification status of a merchant associated with the calling partner, plus outstanding verification issues and the merchant's fee tier. tags: - Onboarding status security: - ApiKeyAuth: [] parameters: - name: merchantId in: path required: true description: Datman merchant ID. schema: type: string pattern: ^\d+$ example: "1000001" responses: "200": description: Merchant status. content: application/json: schema: $ref: "#/components/schemas/MerchantAccountStatusResponse" examples: activeMerchant: summary: Active, fully verified merchant value: status: Active bank_verification_status: Verified account_verification_status: Verified verification_status: account_status: ACTIVE payout_status: ACTIVE issues: [] verification_tier: T1 feeTier: - id: 2 "401": description: Missing or invalid `api_key` header. content: application/json: schema: $ref: "#/components/schemas/UnauthorisedError" "404": description: Merchant does not exist or is not associated with the caller's customer type. content: application/json: schema: $ref: "#/components/schemas/MerchantNotFoundError" examples: merchantNotFound: summary: Merchant not found for this partner value: message: Merchant not found statusCode: 7001 "500": description: Unexpected server error. content: application/json: schema: $ref: "#/components/schemas/ServerError" servers: - url: https://portal-api-sandbox.datmancrm.com/merchants/sandbox description: Sandbox - url: https://portal-api.datmancrm.com/merchants/prod description: Production components: schemas: Error: type: object required: - error properties: error: type: object required: - code - message properties: code: type: string description: Machine-readable SCREAMING_SNAKE error code. examples: - UNAUTHORIZED - FORBIDDEN - VALIDATION_ERROR - RATE_LIMITED - INTERNAL_ERROR - DB_TIMEOUT - DB_CLIENT_CLOSED message: type: string description: Human-readable error message. details: description: Optional extra context about the error. CpOnboardingError: type: object description: One outstanding onboarding issue. Entries from missing details and the payment provider always have `title`, `field` and `reported_at`. Legacy entries are passed through as stored and may include `message` or other keys. additionalProperties: true properties: title: type: string description: Category, for example `Bank Issues` or `Individual`. field: type: string description: The field or requirement concerned. message: type: string reported_at: type: - string - "null" description: ISO-8601 timestamp when the error was reported, if known. CpMerchantOnboarding: type: object description: Onboarding record. Every listed property is present when the merchant has an onboarding record. Otherwise the object is empty. properties: merchant_id: type: integer merchant_name: type: - string - "null" onboarding_link: type: - string - "null" description: Link to the onboarding journey. overview_page: type: - string - "null" account_status: type: - string - "null" payout_status: type: - string - "null" business_status: type: - string - "null" owners_status: type: - string - "null" bank_status: type: - string - "null" tos_status: type: - string - "null" verification_tier: type: - string - integer - "null" missing_details: type: object description: Outstanding information, keyed by category. The keys are dynamic and lowercased (for example `bank issues`). Each value is usually an array of issue descriptions. additionalProperties: true note: type: - string - "null" country: type: - string - "null" errors: type: array description: Merged, de-duplicated onboarding errors from all sources. items: $ref: "#/components/schemas/CpOnboardingError" CpMerchantOnboardingResponse: type: object required: - data properties: data: $ref: "#/components/schemas/CpMerchantOnboarding" MerchantAccountStatusResponse: type: object properties: status: type: string description: Merchant status, for example `Not Submitted`, `Merchant pending`, `Verified`, `Active`, `Closed`, `Rejected` or `Watchlist`. bank_verification_status: type: string enum: - Unverified - Verified description: Bank account verification status. account_verification_status: type: string enum: - Unverified - Verified description: Merchant account verification status. verification_status: type: object description: Verification details from the payment provider. properties: account_status: type: - string - "null" description: Upper-cased account holder status (e.g. ACTIVE), or null if unavailable. payout_status: type: - string - "null" enum: - ACTIVE - INACTIVE - null description: Payout capability status, or null if unavailable. issues: type: array description: User-friendly descriptions of outstanding verification problems. items: type: string verification_tier: description: Verification tier, if configured. feeTier: type: array description: The merchant's current fee tier entry (filtered from the available fee tiers). items: type: object properties: id: description: Fee tier ID. UnauthorisedError: type: object properties: message: type: string example: UNAUTHORISED MerchantNotFoundError: type: object properties: message: type: string example: Merchant not found statusCode: type: integer description: Datman internal code. example: 7001 ServerError: type: object properties: message: type: string example: Internal server error responses: Unauthorized: description: Missing, invalid, expired or revoked credentials. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: code: UNAUTHORIZED message: Invalid, expired, or revoked API key Forbidden: description: The caller may not access this route or reseller (for example the API key has no reseller, or the body names a different reseller). content: application/json: schema: $ref: "#/components/schemas/Error" example: error: code: FORBIDDEN message: Reseller not allowed for this caller RateLimited: description: The per-reseller rate limit was exceeded. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: code: RATE_LIMITED message: Rate limit exceeded InternalError: description: The query or a required configuration failed. Underlying details are not returned. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: code: INTERNAL_ERROR message: Query failed ServiceUnavailable: description: The database timed out or closed the connection. Safe to retry. content: application/json: schema: $ref: "#/components/schemas/Error" example: error: code: DB_TIMEOUT message: The database did not respond in time. Please retry. securitySchemes: ApiKeyAuth: type: apiKey in: header name: api_key description: Partner API key issued by Datman.