> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mnai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# JSON format

> Understand the Base64-encoded JSON payload Meridian accepts when you submit `POST /v1/payout-origination/json`.

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

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

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

```json theme={null}
{
  "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 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`

## Related pages

* [Supported formats](/products/payout-origination/supported-formats)
* [Base64 payload encoding](/products/payout-origination/base64-payload-encoding)
* [Authentication](/products/payout-origination/authentication)