JSON format

Use this page when you want to originate a payout from a Base64-encoded JSON payload instead of an ISO 20022 XML document.

Use json as the {format} path parameter when submitting this message type: POST /v1/payout-origination/json

Meridian accepts a single JSON object as the source payload for this format. Build the JSON document first, then Base64-encode that exact JSON string and send it as the raw text/plain request body.

Meridian intake requirements

Item	Requirement
Path slug	`json`
Document format	JSON object
Submission model	Base64-encode the full JSON payload and send it as the request body
Content type	`text/plain`
Required fields	`entityId`, `beneficiaryId`, `amount`, `currency`, `reference`
Required values	All five fields must be present and each field must have a non-empty value
Transformations	Do not wrap the payload in another JSON envelope after encoding

Required payload shape

The decoded JSON payload must contain all of these fields. All values are required.

Field	Type	Description
`entityId`	string	Meridian entity identifier for the payout originator
`beneficiaryId`	string	Meridian beneficiary identifier that should receive the payout
`amount`	string or number	Payout amount before Base64 encoding
`currency`	string	Three-letter payout currency code
`reference`	string	Your business reference for the payout

Example JSON payload

{
  "entityId": "ent_01JVY8Y4N9X2M6S5Q7T1",
  "beneficiaryId": "bnf_01JVY8Y4N9X2M6S5Q7T2",
  "amount": "1250.00",
  "currency": "USD",
  "reference": "invoice-100045"
}

Practical expectations

When you prepare a JSON payout origination payload:

include all five required fields with values
use the exact entityId and beneficiaryId values Meridian assigned
preserve the JSON bytes you intend to submit before encoding
Base64-encode the complete JSON object in one step
send the encoded output as the raw request body

Do not:

send plaintext JSON with application/json
split the payload fields into query parameters or headers
Base64-encode one field at a time
wrap the Base64 string in another JSON property

Before you submit

Before calling POST /v1/payout-origination/json:

Build the final JSON object with entityId, beneficiaryId, amount, currency, and reference.
Validate that all five fields are present and that all five values are populated in your own system.
Base64-encode the full JSON document.
Send the encoded payload with HMAC authentication headers and a separate Idempotency-Key header.

Transaction model mapping

Use this section to understand how Meridian maps the decoded JSON payload into the transaction model returned by GET /v1/transactions and GET /v1/transactions/{id}.

Transaction field	JSON source	Notes
`externalId`	`reference`	Meridian exposes your reference as the business-facing external identifier
`amounts.debit.amount`	`amount`	Uses the submitted payout amount
`amounts.debit.currency`	`currency`	Uses the submitted currency
`amounts.credit.amount`	`amount`	Currently mirrors the same payout amount
`amounts.credit.currency`	`currency`	Currently mirrors the same payout currency
`creditInstrument.beneficiaryAccount.id`	`beneficiaryId`	Uses the beneficiary identifier in the payload
`source.type`	Internal value `external_submission`	Current documented behavior for JSON-ingested transactions

Meridian assigns these transaction fields directly; they are not sourced from the JSON payload:

id
messageId
status
statusReason
createdAt
updatedAt
relatedTransactionId

Getting Started

Message Preparation

API Reference

Webhooks

Meridian intake requirements

Required payload shape

Example JSON payload

Practical expectations

Before you submit

Transaction model mapping

​Meridian intake requirements

​Required payload shape

​Example JSON payload

​Practical expectations

​Before you submit

​Transaction model mapping

​Related pages

Meridian intake requirements

Required payload shape

Example JSON payload

Practical expectations

Before you submit

Transaction model mapping

Related pages