Skip to main content
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
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.
1

Build the final payload

Produce the exact payload Meridian should process.If you need the expected message shape for your format, review Supported formats.
2

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

Submit with the correct headers

Send the body with:
  • Content-Type: text/plain
  • Meridian HMAC authentication headers
  • a separate Idempotency-Key header

​
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: 
<Message>
  <Header>
    <Id>20260407-000123</Id>
  </Header>
</Message>
Base64-encode it: 
base64 -i message.xml
Example result: 
PE1lc3NhZ2U+CiAgPEhlYWRlcj4KICAgIDxJZD4yMDI2MDQwNy0wMDAxMjM8L0lkPgogIDwvSGVhZGVyPgo8L01lc3NhZ2U+
Send that Base64 string as the raw HTTP body. Example JSON to encode: 
{
  "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

MistakeResult
Sending plaintext XML with application/xmlMeridian rejects the request because the API expects text/plain with Base64 content
Sending plaintext JSON with application/jsonMeridian rejects the request because the API expects text/plain with Base64 content
Wrapping the Base64 string in JSONSignature and body handling become inconsistent with the documented request shape
Encoding a partial payloadMeridian receives an artifact that does not represent the original business message
Changing the body after signingHMAC 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.