> ## Documentation Index > Fetch the complete documentation index at: https://docs.mnai.com/llms.txt > Use this file to discover all available pages before exploring further. # Submit a payout request > Accepts a Base64-encoded payout request in the format specified by the `format` path parameter. Supported values: - `pacs008` for ISO 20022 `pacs.008.*` XML messages - `json` for a JSON payload where `entityId`, `beneficiaryId`, `amount`, `currency`, and `reference` are all required Authentication uses Meridian HMAC headers: - X-Meridian-Api-Key - X-Meridian-Timestamp - X-Meridian-Signature Use Idempotency-Key as a separate header for duplicate protection. The endpoint returns 202 Accepted once the encoded payload has been safely accepted for processing. Webhooks will be sent for each status change until a finality status. The transaction APIs may be used to list resulting transactions and retrieve the latest status on demand. ## OpenAPI ````yaml /products/payout-origination/api-reference/payout-origination.json post /v1/payout-origination/{format} openapi: 3.1.0 info: title: Meridian Payout Origination API version: 1.0.0 summary: Originate payout requests and track the resulting transactions description: > These endpoints accept a Base64-encoded payout message payload and allow you to list resulting transactions or retrieve a transaction by Meridian ID. Request authentication is performed using Meridian HMAC headers. The server validates the HMAC headers, stores the encoded payload, and queues the message for downstream processing. servers: - url: https://api.meridian.example.com security: [] tags: - name: Payouts description: Payout origination and transaction tracking paths: /v1/payout-origination/{format}: post: tags: - Payouts summary: Submit a payout request description: > Accepts a Base64-encoded payout request in the format specified by the `format` path parameter. Supported values: - `pacs008` for ISO 20022 `pacs.008.*` XML messages - `json` for a JSON payload where `entityId`, `beneficiaryId`, `amount`, `currency`, and `reference` are all required Authentication uses Meridian HMAC headers: - X-Meridian-Api-Key - X-Meridian-Timestamp - X-Meridian-Signature Use Idempotency-Key as a separate header for duplicate protection. The endpoint returns 202 Accepted once the encoded payload has been safely accepted for processing. Webhooks will be sent for each status change until a finality status. The transaction APIs may be used to list resulting transactions and retrieve the latest status on demand. operationId: submitMessage parameters: - $ref: '#/components/parameters/MessageFormat' - $ref: '#/components/parameters/IdempotencyKey' - $ref: '#/components/parameters/XMeridianProgramId' - $ref: '#/components/parameters/XMeridianApiKey' - $ref: '#/components/parameters/XMeridianTimestamp' - $ref: '#/components/parameters/XMeridianSignature' requestBody: required: true description: > Base64 string containing the full original message payload, encoded as a single opaque document. For `pacs008`, the decoded payload is an ISO 20022 XML document. For `json`, the decoded payload is a JSON object where `entityId`, `beneficiaryId`, `amount`, `currency`, and `reference` are all required. content: text/plain: schema: type: string minLength: 20 description: > Base64-encoded string containing the full original message payload. example: >- PERvY3VtZW50IHhtbG5zPSJ1cm46aXNvOnN0ZDppc286MjAwMjI6dGVjaDp4c2Q6cGFjcy4wMDguMDAxLjA4Ij48RklUb0ZJQ3N0bXJDZHRUcmY+PEdycEhkcj48TXNnSWQ+MjAyNjA0MDctMDAwMTIzPC9Nc2dJZD48L0dycEhkcj48L0ZJVG9GSUNzdG1yQ2R0VHJmPjwvRG9jdW1lbnQ+ examples: pacs008: summary: Base64-encoded pacs.008 XML message value: >- PERvY3VtZW50IHhtbG5zPSJ1cm46aXNvOnN0ZDppc286MjAwMjI6dGVjaDp4c2Q6cGFjcy4wMDguMDAxLjA4Ij48RklUb0ZJQ3N0bXJDZHRUcmY+PEdycEhkcj48TXNnSWQ+MjAyNjA0MDctMDAwMTIzPC9Nc2dJZD48L0dycEhkcj48L0ZJVG9GSUNzdG1yQ2R0VHJmPjwvRG9jdW1lbnQ+ json: summary: Base64-encoded JSON payout payload value: >- eyJlbnRpdHlJZCI6ImVudF8wMUpWWThZNE45WDJNNlM1UTdUMSIsImJlbmVmaWNpYXJ5SWQiOiJibmZfMDFKVlk4WTROOVgyTTZTNVE3VDIiLCJhbW91bnQiOiIxMjUwLjAwIiwiY3VycmVuY3kiOiJVU0QiLCJyZWZlcmVuY2UiOiJpbnZvaWNlLTEwMDA0NSJ9 responses: '202': description: Message accepted for asynchronous processing content: application/json: schema: $ref: '#/components/schemas/IngestionAccepted' examples: accepted: value: messageId: msg_01JVY8Y4N9X2M6S5Q7T1 transactionId: txn_01JVY8Y4N9X2M6S5Q7T1 status: RECEIVED receivedAt: '2026-04-07T20:11:42Z' '400': description: >- Malformed request, validation error, invalid Base64 payload, or invalid timestamp format content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: missingBody: value: validationErrors: - type: MissingRequestBody fieldRef: requestBody message: Missing RequestBody or missing non-null fields errorCode: INVALID_REQUEST message: Request body is required invalidTimestamp: value: validationErrors: - type: InvalidFormat fieldRef: X-Meridian-Timestamp message: Timestamp must be a valid RFC 3339 UTC datetime errorCode: INVALID_REQUEST message: Request validation failed invalidBase64: value: validationErrors: - type: InvalidFormat fieldRef: requestBody message: Expected a valid Base64-encoded payload errorCode: INVALID_BASE64_PAYLOAD message: Request body is not valid Base64 '401': description: HMAC authentication failed content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: badSignature: value: validationErrors: [] errorCode: AUTHENTICATION_FAILED message: Signature verification failed staleTimestamp: value: validationErrors: - type: InvalidValue fieldRef: X-Meridian-Timestamp message: Timestamp is outside the allowed clock skew window errorCode: AUTHENTICATION_FAILED message: Request authentication failed '403': description: >- Caller is authenticated but not authorized to submit this message type or sender content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: forbidden: value: validationErrors: [] errorCode: FORBIDDEN message: >- Caller is not authorized to submit messages for this sender '409': description: Duplicate idempotency key or duplicate business submission content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: duplicate: value: validationErrors: - type: InvalidValue fieldRef: Idempotency-Key message: >- A request with this idempotency key has already been processed errorCode: DUPLICATE_MESSAGE message: Duplicate message submission '413': description: Request payload exceeds allowed size content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: tooLarge: value: validationErrors: - type: UnprocessableValue fieldRef: requestBody message: Request body exceeds the maximum allowed size errorCode: PAYLOAD_TOO_LARGE message: Request payload is too large '415': description: Unsupported media type content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: unsupportedMediaType: value: validationErrors: - type: InvalidValue fieldRef: Content-Type message: Content-Type must be text/plain errorCode: UNSUPPORTED_MEDIA_TYPE message: Unsupported media type '422': description: >- Payload was accepted structurally but failed early semantic validation content: application/json: schema: $ref: '#/components/schemas/MeridianError' examples: unsupportedMessageType: value: validationErrors: - type: InvalidValue fieldRef: X-Message-Type message: >- The submitted message type is not supported by this endpoint errorCode: VALIDATION_FAILED message: Request validation failed security: - MeridianHmacAuth: [] components: parameters: MessageFormat: name: format in: path required: true description: >- Message format identifier. Use `pacs008` for ISO 20022 `pacs.008.*` XML messages or `json` for Base64-encoded JSON payout payloads. schema: type: string enum: - pacs008 - json example: json IdempotencyKey: name: Idempotency-Key in: header required: true description: Unique key to protect against accidental duplicate submissions schema: type: string minLength: 8 maxLength: 128 example: 6e6fa6e8-4e7c-4d1f-8d44-71f2a7e6f8b0 XMeridianProgramId: name: X-Meridian-Program-Id in: header required: true description: >- Identifies your Meridian program. Required on all requests but not included in the canonical signing string. schema: type: string minLength: 8 maxLength: 128 example: prog_01JVY8P4Q9F2M6S5Q7T1 XMeridianApiKey: name: X-Meridian-Api-Key in: header required: true description: Public client key identifier used to look up the HMAC secret schema: type: string minLength: 8 maxLength: 128 example: mk_live_partner_001 XMeridianTimestamp: name: X-Meridian-Timestamp in: header required: true description: > RFC 3339 UTC timestamp used in the HMAC signing string and replay protection. Requests outside the accepted clock skew window should be rejected. schema: type: string format: date-time example: '2026-04-07T20:11:40Z' XMeridianSignature: name: X-Meridian-Signature in: header required: true description: > HMAC-SHA256 signature of the canonical signing string. Recommended format: sha256={hex_digest} schema: type: string pattern: ^sha256=[A-Fa-f0-9]{64}$ example: sha256=3a0c1d8d3f5b9f76d44d0f5c65295f9e7d97e1f6782e4c9ac7b4a123456789ab schemas: IngestionAccepted: type: object required: - messageId - transactionId - status - receivedAt properties: messageId: type: string description: >- Received message id for the accepted message. Use this to correlate the original request. example: msg_01JVY8Y4N9X2M6S5Q7T1 transactionId: type: string description: >- Meridian-assigned identifier for the transaction created from the accepted message submission. Use this identifier to track the transaction status with the transaction APIs or webhooks. example: txn_01JVY8Y4N9X2M6S5Q7T1 status: type: string description: Initial processing state for the accepted submission. enum: - RECEIVED example: RECEIVED receivedAt: type: string format: date-time description: >- RFC 3339 timestamp showing when Meridian accepted the message for asynchronous processing. example: '2026-04-07T20:11:42Z' MeridianError: type: object required: - validationErrors - message properties: validationErrors: type: array description: > An array of validation errors that occurred during request processing. This may be empty if there are no field-level validation errors. items: $ref: '#/components/schemas/ValidationError' errorCode: type: - string - 'null' description: Optional machine-readable error code example: INVALID_REQUEST message: type: string description: Human-readable error message example: Request validation failed ValidationError: oneOf: - $ref: '#/components/schemas/ValidationErrorInvalidFormat' - $ref: '#/components/schemas/ValidationErrorInvalidValue' - $ref: '#/components/schemas/ValidationErrorMissingValue' - $ref: '#/components/schemas/ValidationErrorUnprocessableValue' - $ref: '#/components/schemas/ValidationErrorUnexpectedVerificationError' - $ref: '#/components/schemas/ValidationErrorMissingRequestBody' - $ref: '#/components/schemas/ValidationErrorMissingPathParameter' - $ref: '#/components/schemas/ValidationErrorMissingQueryParameter' - $ref: '#/components/schemas/ValidationErrorNotFound' discriminator: propertyName: type mapping: InvalidFormat: $ref: '#/components/schemas/ValidationErrorInvalidFormat' InvalidValue: $ref: '#/components/schemas/ValidationErrorInvalidValue' MissingValue: $ref: '#/components/schemas/ValidationErrorMissingValue' UnprocessableValue: $ref: '#/components/schemas/ValidationErrorUnprocessableValue' UnexpectedVerificationError: $ref: '#/components/schemas/ValidationErrorUnexpectedVerificationError' MissingRequestBody: $ref: '#/components/schemas/ValidationErrorMissingRequestBody' MissingPathParameter: $ref: '#/components/schemas/ValidationErrorMissingPathParameter' MissingQueryParameter: $ref: '#/components/schemas/ValidationErrorMissingQueryParameter' NotFound: $ref: '#/components/schemas/ValidationErrorNotFound' ValidationErrorInvalidFormat: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: InvalidFormat fieldRef: type: string message: type: string example: Invalid format ValidationErrorInvalidValue: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: InvalidValue fieldRef: type: string message: type: string example: Invalid value ValidationErrorMissingValue: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: MissingValue fieldRef: type: string message: type: string example: Missing value ValidationErrorUnprocessableValue: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: UnprocessableValue fieldRef: type: string message: type: string example: Unprocessable value ValidationErrorUnexpectedVerificationError: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: UnexpectedVerificationError fieldRef: type: string message: type: string example: Unexpected error during verifying the value ValidationErrorMissingRequestBody: type: object required: - type - fieldRef - message properties: type: type: string const: MissingRequestBody fieldRef: type: string const: requestBody message: type: string example: Missing RequestBody or missing non-null fields ValidationErrorMissingPathParameter: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: MissingPathParameter fieldRef: type: string message: type: string example: Missing path parameter someParam ValidationErrorMissingQueryParameter: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: MissingQueryParameter fieldRef: type: string message: type: string example: Missing query parameter someParam ValidationErrorNotFound: allOf: - $ref: '#/components/schemas/ValidationErrorBase' - type: object properties: type: type: string const: NotFound fieldRef: type: string message: type: string example: Not found ValidationErrorBase: type: object required: - type - fieldRef - message properties: type: type: string fieldRef: type: string description: The field or parameter that triggered the validation error message: type: string description: Human-readable explanation of the validation failure securitySchemes: MeridianHmacAuth: type: apiKey in: header name: X-Meridian-Signature description: |- Meridian HMAC header authentication. Required headers: - X-Meridian-Api-Key - X-Meridian-Program-Id - X-Meridian-Timestamp - X-Meridian-Signature ````