> ## 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.

# Overview

> Submit payout requests to Meridian for asynchronous validation and processing.

Use the Payout Origination API when you need to deliver a payout message to Meridian as a Base64-encoded payload.

You Base64-encode the original message payload, sign the request with Meridian HMAC headers, and submit it to the ingestion endpoint. Meridian accepts the encoded payload, stores it, and processes it asynchronously.

If you need help building the request body, see [Base64 payload encoding](/products/payout-origination/base64-payload-encoding).

## What this API does

The Payout Origination API is designed for one job: receiving a full message as an encoded payload and moving it into Meridian's processing pipeline.

Use this API when you need to:

* send a complete payment payload without splitting it across API fields
* preserve the exact message bytes while using a simple text transport format
* list resulting transactions and read their latest processing status
* protect against duplicate submissions with an idempotency key
* receive an acknowledgement immediately instead of waiting for full processing to finish

<Warning>
  Base64 encoding does not encrypt the message or provide confidentiality. Use
  HTTPS in transit and avoid logging or exposing the raw payload in client and
  server logs.
</Warning>

## Request flow

<Steps>
  <Step title="Base64-encode the message payload">
    Encode the complete source payload as a Base64 string.

    Send the encoded payload as the raw request body with `Content-Type: text/plain`.
  </Step>

  <Step title="Sign the request">
    Authenticate the request with Meridian HMAC headers:

    * `X-Meridian-Api-Key`
    * `X-Meridian-Timestamp`
    * `X-Meridian-Signature`
  </Step>

  <Step title="Add an idempotency key">
    Send `Idempotency-Key` as a separate request header.

    Use a unique `Idempotency-Key` for each business submission so retries do not create duplicates.
  </Step>

  <Step title="Submit the message">
    Send `POST /v1/payout-origination/{format}`, where `format` identifies the message type.

    Meridian validates the headers, checks that the body is valid Base64, stores the encoded payload, and queues the message for asynchronous processing.
  </Step>

  <Step title="Track processing status">
    A successful request returns `202 Accepted` with a Meridian `messageId`, a `transactionId`, an initial `RECEIVED` status, and a `receivedAt` timestamp.

    Meridian then continues downstream processing after the API request completes.
  </Step>
</Steps>

## What a successful response means

`202 Accepted` means Meridian has safely accepted the encoded payload for processing. It does not mean the message has already been validated or completed.

Store the returned `messageId` and `transactionId`. Use them for later status tracking, reconciliation, and transaction lookup.

Example accepted response:

```json theme={null}
{
  "messageId": "msg_01JVY8Y4N9X2M6S5Q7T1",
  "transactionId": "txn_01JVY8Y4N9X2M6S5Q7T1",
  "status": "RECEIVED",
  "receivedAt": "2026-04-07T20:11:42Z"
}
```

## Endpoint summary

### Supported format values

| `{format}` value | Source payload                                                                      |
| :--------------- | :---------------------------------------------------------------------------------- |
| `pacs008`        | ISO 20022 `pacs.008.*` XML document                                                 |
| `json`           | JSON object with `entityId`, `beneficiaryId`, `amount`, `currency`, and `reference` |

### Submit an encoded message

| Item                   | Value                                                                |
| :--------------------- | :------------------------------------------------------------------- |
| Method                 | `POST`                                                               |
| Path                   | `/v1/payout-origination/{format}`                                    |
| Content type           | `text/plain`                                                         |
| Request body           | Base64 string containing the full message payload                    |
| Authentication headers | `X-Meridian-Api-Key`, `X-Meridian-Timestamp`, `X-Meridian-Signature` |
| Idempotency header     | `Idempotency-Key`                                                    |
| Success response       | `202 Accepted`                                                       |

### List transactions

| Item                      | Value                                                                             |
| :------------------------ | :-------------------------------------------------------------------------------- |
| Method                    | `GET`                                                                             |
| Path                      | `/v1/transactions`                                                                |
| Authentication headers    | `X-Meridian-Api-Key`, `X-Meridian-Timestamp`, `X-Meridian-Signature`              |
| Optional query parameters | `pageIndex`, `pageSize`, `messageId`                                              |
| Success response          | `200 OK`                                                                          |
| Response body             | JSON containing paginated transaction records with their latest processing status |

### Get a transaction by ID

| Item                   | Value                                                                |
| :--------------------- | :------------------------------------------------------------------- |
| Method                 | `GET`                                                                |
| Path                   | `/v1/transactions/{id}`                                              |
| Authentication headers | `X-Meridian-Api-Key`, `X-Meridian-Timestamp`, `X-Meridian-Signature` |
| Success response       | `200 OK`                                                             |
| Response body          | JSON containing the transaction record and latest processing status  |

## Error handling

Build your client to handle these common response classes:

| Status | Meaning                                                                                                                 |
| :----- | :---------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request is malformed. Common causes include a missing body, invalid timestamp format, or an invalid Base64 payload. |
| `401`  | HMAC authentication failed. The signature may be invalid or the timestamp may be outside the allowed replay window.     |
| `403`  | Your credentials are valid, but you are not authorized to submit this sender or message type.                           |
| `404`  | The supplied transaction `id` does not match a stored transaction when you use the detail endpoint.                     |
| `409`  | Meridian detected a duplicate submission, usually from a reused `Idempotency-Key`.                                      |
| `413`  | The Base64 payload exceeds the allowed size.                                                                            |
| `415`  | `Content-Type` is not `text/plain`.                                                                                     |
| `422`  | The request was structurally valid but failed early semantic validation.                                                |

## Integration guidance

* Treat the request body as an opaque Base64 string. Do not transform the message content before submission.
* Use the path slug that matches the decoded payload you are sending.
* Generate a fresh idempotency key for each new message and reuse it only when retrying the same submission.
* Keep your system clock accurate. Timestamp skew can cause authentication failures.
* Store the Meridian `messageId`, returned `transactionId`, your own business reference, and the idempotency key together for audit and reconciliation.
* Hash and sign the exact Base64 string you send on the wire.
* Use `GET /v1/transactions` to reconcile batches of transactions.
* Use `GET /v1/transactions?messageId=...` when you want to find the transaction created from a specific submission.
* Use `GET /v1/transactions/{id}` when you already know the Meridian internal transaction ID.

## Next steps

* Review [Supported formats](/products/payout-origination/supported-formats) for the message types Meridian accepts.
* Review [Base64 payload encoding](/products/payout-origination/base64-payload-encoding) for practical guidance on building the request body.
* Review [Authentication](/products/payout-origination/authentication) for request signing details.
* Use the API reference for the exact request and response schema.