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

# Base64 payload encoding

> Learn how to prepare the Base64-encoded payload you send to the Payout Origination API.

Use this guide when you need to turn a complete message payload into the `text/plain` request body the Payout Origination API accepts.

The API does not accept raw plaintext XML or JSON. You must Base64-encode the full source payload and send the encoded payload as the raw request body.

## What you encode

Encode the complete payload you want Meridian to process.

That means:

* finish building the payload first
* validate the payload content before encoding
* encode the full payload as one artifact
* send the encoded result as-is

Do not:

* wrap the source payload in another envelope before encoding
* split the message into separate fields
* encode only part of the payload
* modify the encoded payload after it is produced

<Warning>
  Base64 encoding is not encryption. It preserves the source payload as plain
  reversible data. Rely on HTTPS, access controls, and careful logging
  practices to protect message contents.
</Warning>

## Recommended flow

<Steps>
  <Step title="Build the final payload">
    Produce the exact payload Meridian should process.

    If you need the expected message shape for your format, review [Supported formats](/products/payout-origination/supported-formats).
  </Step>

  <Step title="Encode the payload as Base64">
    Base64-encode the full payload and produce a single ASCII string.

    Send the encoded payload directly as the HTTP request body.
  </Step>

  <Step title="Submit with the correct headers">
    Send the body with:

    * `Content-Type: text/plain`
    * Meridian HMAC authentication headers
    * a separate `Idempotency-Key` header
  </Step>
</Steps>

## Encoding guidance

Apply Base64 to the exact bytes of the source payload you want Meridian to process.

That means:

* use a stable character encoding such as UTF-8 for the source payload
* Base64-encode the entire payload in one step
* hash and sign the exact Base64 string that you send
* avoid inserting extra whitespace, line wrapping, or formatting changes after encoding

## Example payloads

Example XML to encode:

```xml theme={null}
<Message>
  <Header>
    <Id>20260407-000123</Id>
  </Header>
</Message>
```

Base64-encode it:

```bash theme={null}
base64 -i message.xml
```

Example result:

```text theme={null}
PE1lc3NhZ2U+CiAgPEhlYWRlcj4KICAgIDxJZD4yMDI2MDQwNy0wMDAxMjM8L0lkPgogIDwvSGVhZGVyPgo8L01lc3NhZ2U+
```

Send that Base64 string as the raw HTTP body.

Example JSON to encode:

```json theme={null}
{
  "entityId": "ent_01JVY8Y4N9X2M6S5Q7T1",
  "beneficiaryId": "bnf_01JVY8Y4N9X2M6S5Q7T2",
  "amount": "1250.00",
  "currency": "USD",
  "reference": "invoice-100045"
}
```

## Handling guidance

* Keep the source payload in a stable encoding such as UTF-8 before Base64-encoding it.
* Treat the Base64 output as an opaque string.
* Send the encoded payload as the raw request body, not as a JSON property.
* Log identifiers such as `messageId` and your own business reference instead of logging raw payment contents.
* Reuse the same Base64 payload only when retrying the same logical submission with the same idempotency intent.

## Common mistakes

| Mistake                                        | Result                                                                                |
| :--------------------------------------------- | :------------------------------------------------------------------------------------ |
| Sending plaintext XML with `application/xml`   | Meridian rejects the request because the API expects `text/plain` with Base64 content |
| Sending plaintext JSON with `application/json` | Meridian rejects the request because the API expects `text/plain` with Base64 content |
| Wrapping the Base64 string in JSON             | Signature and body handling become inconsistent with the documented request shape     |
| Encoding a partial payload                     | Meridian receives an artifact that does not represent the original business message   |
| Changing the body after signing                | HMAC verification fails                                                               |

## Relationship to retrieval

After Meridian accepts the request, you can query the latest processing state with `GET /v1/transactions`, `GET /v1/transactions?messageId=...`, or `GET /v1/transactions/{id}`.

These GET endpoints return transaction records and status information. They do not return the stored Base64 payload, and they do not replace your responsibility to manage the original source payload safely in your own systems where required.

## Related pages

* [Overview](/products/payout-origination/overview)
* [Supported formats](/products/payout-origination/supported-formats)
* [Authentication](/products/payout-origination/authentication)