openapi: 3.1.0 info: title: Payouts version: "1" description: Merchant payouts, payout totals and payout schedules. tags: - name: Payouts description: A merchant's payouts and payout totals. paths: /v1/merchants/{merchantId}/payouts: get: operationId: listMerchantPayouts summary: List payouts description: Lists the merchant's most recent payouts across all payout providers, newest first. Finalised batches are excluded, and provider payout transactions are included only when their status is `SENT` or `FAILED`. Amounts are in major currency units (for example pounds). Use `limit` to cap the number of rows. There is no cursor or offset. The merchant must belong to your reseller, otherwise 404. tags: - Payouts 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 - name: limit in: query required: false description: Maximum number of payouts to return. Defaults to 50 and is capped at 200. Missing, zero or non-numeric values use the default. schema: type: integer minimum: 1 maximum: 200 default: 50 example: 50 responses: "200": description: Recent payouts, newest first. content: application/json: schema: $ref: "#/components/schemas/CpMerchantPayoutsResponse" examples: payouts: summary: Recent payouts value: data: - id: 778899 total: 1250.75 status: SENT expected_date: 2026-03-03T00:00:00.000Z sort_date: 2026-03-02T07:00:12.000Z payment_provider: DATMAN - id: 445566 total: 980.4 status: PENDING expected_date: 2026-02-24T00:00:00.000Z sort_date: 2026-02-24T00:00:00.000Z payment_provider: DATMAN "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 /v1/merchants/{merchantId}/payout-stats: get: operationId: getMerchantPayoutStats summary: Get payout statistics description: Returns the merchant's provider payout transactions grouped by status, with the number of payouts and the total amount (in major currency units) for each status. This covers all time. Payout batches are not counted. Returns an empty list when the merchant has no payout transactions. The merchant must belong to your reseller, otherwise 404. tags: - Payouts 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: Payout counts and totals by status. content: application/json: schema: $ref: "#/components/schemas/CpMerchantPayoutStatsResponse" examples: stats: summary: Sent and failed payouts value: data: - status: SENT order_count: 42 total_amount: 18250.5 - status: FAILED order_count: 1 total_amount: 310 "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 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. CpMerchantPayout: type: object required: - id - total - status - expected_date - sort_date - payment_provider properties: id: type: - integer - string description: Payout batch id or payout transaction id, depending on the provider. Not unique across providers. total: type: number description: Payout amount in major currency units. status: type: string description: Provider payout status, for example `SENT` or `FAILED`. expected_date: type: - string - "null" description: Expected payout date as an ISO-8601 timestamp. sort_date: type: - string - "null" description: Timestamp used to order the list (pending date for batches, creation time for payout transactions). payment_provider: type: string description: Code of the provider that made the payout, for example `DATMAN`. CpMerchantPayoutsResponse: type: object required: - data properties: data: type: array items: $ref: "#/components/schemas/CpMerchantPayout" CpMerchantPayoutStat: type: object required: - status - order_count - total_amount properties: status: type: string description: Payout status, for example `SENT` or `FAILED`. order_count: type: integer description: Number of payouts with this status. total_amount: type: number description: Total amount in major currency units. CpMerchantPayoutStatsResponse: type: object required: - data properties: data: type: array items: $ref: "#/components/schemas/CpMerchantPayoutStat" 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.