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

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

​
Request flow

1

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

Sign the request

Authenticate the request with Meridian HMAC headers:
  • X-Meridian-Api-Key
  • X-Meridian-Timestamp
  • X-Meridian-Signature
3

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

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

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.

​
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:

​
Endpoint summary

​
Supported format values

​
Submit an encoded message

​
List transactions

​
Get a transaction by ID

​
Error handling

Build your client to handle these common response classes:

​
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