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: 
{
  "messageId": "msg_01JVY8Y4N9X2M6S5Q7T1",
  "transactionId": "txn_01JVY8Y4N9X2M6S5Q7T1",
  "status": "RECEIVED",
  "receivedAt": "2026-04-07T20:11:42Z"
}

​
Endpoint summary

​
Supported format values

{format} valueSource payload
pacs008ISO 20022 pacs.008.* XML document
jsonJSON object with entityId, beneficiaryId, amount, currency, and reference

​
Submit an encoded message

ItemValue
MethodPOST
Path/v1/payout-origination/{format}
Content typetext/plain
Request bodyBase64 string containing the full message payload
Authentication headersX-Meridian-Api-Key, X-Meridian-Timestamp, X-Meridian-Signature
Idempotency headerIdempotency-Key
Success response202 Accepted

​
List transactions

ItemValue
MethodGET
Path/v1/transactions
Authentication headersX-Meridian-Api-Key, X-Meridian-Timestamp, X-Meridian-Signature
Optional query parameterspageIndex, pageSize, messageId
Success response200 OK
Response bodyJSON containing paginated transaction records with their latest processing status

​
Get a transaction by ID

ItemValue
MethodGET
Path/v1/transactions/{id}
Authentication headersX-Meridian-Api-Key, X-Meridian-Timestamp, X-Meridian-Signature
Success response200 OK
Response bodyJSON containing the transaction record and latest processing status

​
Error handling

Build your client to handle these common response classes:
StatusMeaning
400The request is malformed. Common causes include a missing body, invalid timestamp format, or an invalid Base64 payload.
401HMAC authentication failed. The signature may be invalid or the timestamp may be outside the allowed replay window.
403Your credentials are valid, but you are not authorized to submit this sender or message type.
404The supplied transaction id does not match a stored transaction when you use the detail endpoint.
409Meridian detected a duplicate submission, usually from a reused Idempotency-Key.
413The Base64 payload exceeds the allowed size.
415Content-Type is not text/plain.
422The 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