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

ItemRequirement
Path slugjson
Document formatJSON object
Submission modelBase64-encode the full JSON payload and send it as the request body
Content typetext/plain
Required fieldsentityId, beneficiaryId, amount, currency, reference
Required valuesAll five fields must be present and each field must have a non-empty value
TransformationsDo 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.
FieldTypeDescription
entityIdstringMeridian entity identifier for the payout originator
beneficiaryIdstringMeridian beneficiary identifier that should receive the payout
amountstring or numberPayout amount before Base64 encoding
currencystringThree-letter payout currency code
referencestringYour 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:
  1. Build the final JSON object with entityId, beneficiaryId, amount, currency, and reference.
  2. Validate that all five fields are present and that all five values are populated in your own system.
  3. Base64-encode the full JSON document.
  4. 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 fieldJSON sourceNotes
externalIdreferenceMeridian exposes your reference as the business-facing external identifier
amounts.debit.amountamountUses the submitted payout amount
amounts.debit.currencycurrencyUses the submitted currency
amounts.credit.amountamountCurrently mirrors the same payout amount
amounts.credit.currencycurrencyCurrently mirrors the same payout currency
creditInstrument.beneficiaryAccount.idbeneficiaryIdUses the beneficiary identifier in the payload
source.typeInternal value external_submissionCurrent 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