Create a transaction intent

curl --request POST \
  --url https://sandbox-api.va.meridianpay.com/v1/transaction-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "debitInstrumentId": "acc_01JMERUSDRET001",
  "creditInstrumentId": "ba_01JMERPHSETTLE01",
  "fixedSide": "DEBIT",
  "amount": "250.00",
  "idempotencyKey": "create-key-9f2c1b3a",
  "memo": "Invoice INV-5530",
  "purpose": "VENDOR_CONTRACTOR_PAYOUTS"
}
'

{
  "id": "txnint_01JMERINTENT001",
  "type": "TRANSFER",
  "createdAt": "2026-04-30T15:00:00Z",
  "updatedAt": "2026-04-30T15:02:00Z",
  "status": "CREATED",
  "debitAmount": "7250.00",
  "debitCurrency": "USD",
  "debitInstrument": {
    "account": {
      "id": "acc_01JMEROAK7421",
      "displayName": "Oak Street Purchase Contract",
      "currency": "USD"
    },
    "instrumentType": "ACCOUNT"
  },
  "creditAmount": "7250.00",
  "creditCurrency": "USD",
  "creditInstrument": {
    "account": {
      "id": "acc_01JMEROAK7421",
      "displayName": "Oak Street Purchase Contract",
      "currency": "USD"
    },
    "instrumentType": "ACCOUNT"
  },
  "fees": [
    {
      "type": "PROCESSING",
      "label": "Processing fee",
      "amount": "1.00",
      "currency": "USD"
    }
  ],
  "exchangeRate": "1",
  "statusReason": "<string>",
  "relatedTransactionId": "<string>",
  "debitMemo": "INV-23014",
  "purpose": "PAYMENT_FOR_SERVICES",
  "creditRail": "ACH"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

POST

transaction-intents

curl --request POST \
  --url https://sandbox-api.va.meridianpay.com/v1/transaction-intents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "debitInstrumentId": "acc_01JMERUSDRET001",
  "creditInstrumentId": "ba_01JMERPHSETTLE01",
  "fixedSide": "DEBIT",
  "amount": "250.00",
  "idempotencyKey": "create-key-9f2c1b3a",
  "memo": "Invoice INV-5530",
  "purpose": "VENDOR_CONTRACTOR_PAYOUTS"
}
'

{
  "id": "txnint_01JMERINTENT001",
  "type": "TRANSFER",
  "createdAt": "2026-04-30T15:00:00Z",
  "updatedAt": "2026-04-30T15:02:00Z",
  "status": "CREATED",
  "debitAmount": "7250.00",
  "debitCurrency": "USD",
  "debitInstrument": {
    "account": {
      "id": "acc_01JMEROAK7421",
      "displayName": "Oak Street Purchase Contract",
      "currency": "USD"
    },
    "instrumentType": "ACCOUNT"
  },
  "creditAmount": "7250.00",
  "creditCurrency": "USD",
  "creditInstrument": {
    "account": {
      "id": "acc_01JMEROAK7421",
      "displayName": "Oak Street Purchase Contract",
      "currency": "USD"
    },
    "instrumentType": "ACCOUNT"
  },
  "fees": [
    {
      "type": "PROCESSING",
      "label": "Processing fee",
      "amount": "1.00",
      "currency": "USD"
    }
  ],
  "exchangeRate": "1",
  "statusReason": "<string>",
  "relatedTransactionId": "<string>",
  "debitMemo": "INV-23014",
  "purpose": "PAYMENT_FOR_SERVICES",
  "creditRail": "ACH"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "type": "InvalidFormat",
      "message": "<string>"
    }
  ],
  "errorCode": "UNAUTHORIZED"
}

Authorizations

Authorization

string

header

required

Bearer token authentication, for client-server calls.

Send the access token issued by POST /v1/auth/token as Authorization: Bearer {token}. The token carries its own program and user context, so the X-Meridian-* headers are not required. See Authentication.

Headers

X-Meridian-Api-Key

string

Server-to-server (HMAC) requests only. Partner API key issued by Meridian during provisioning.

X-Meridian-Timestamp

string

Server-to-server (HMAC) requests only. Current time in milliseconds since the Unix epoch. Must be within 60 seconds of the request.

X-Meridian-Program-Id

string

Server-to-server (HMAC) requests only. Identifies the program context for the request.

X-Meridian-User-Id

string

Server-to-server (HMAC) requests only. Identifies the Meridian user targeted by the request. Required for MULTI_USER integrations; omit for SINGLE_USER.

Body

application/json

Debit and credit instruments, the fixed side, the amount to price, and optionally the rail to pay the credit instrument over

Debit and credit payment instruments plus the amount to price a transaction intent. The intent is a preview only — no funds move until it is committed.

debitInstrumentId

string

required

Identifier of the payment instrument to debit (the funding side), e.g. the id of a balance account returned by GET /v1/accounts. Must differ from creditInstrumentId.

Example:

"acc_01JMERUSDRET001"

creditInstrumentId

string

required

Identifier of the payment instrument to credit (the receiving side): a beneficiary bank account id, or a beneficiary blockchain wallet id for a stablecoin payout. Must differ from debitInstrumentId. When either instrument is a stablecoin, both must be in the same currency.

Example:

"ba_01JMERPHSETTLE01"

fixedSide

enum<string>

required

Which side of the transaction amount is fixed on. DEBIT fixes the amount debited from the funding instrument; CREDIT fixes the amount credited to the receiving instrument. The other side is derived from the exchange rate.

Available options:

DEBIT,

CREDIT

Example:

"DEBIT"

amount

string

required

Amount to price on the fixedSide, as a decimal string in that side's currency. Must be at least 1 in that currency. A value carrying more precision than the currency holds is rounded to that currency's precision - two decimal places for a fiat currency, six for a stablecoin - rather than rejected, using banker's rounding, so 250.005 USD is priced as 250.00. The other side is then derived from the rounded value.

Example:

"250.00"

idempotencyKey

string

required

Caller-supplied idempotency key (max 255 chars). Repeating a create with the same key returns the same intent instead of creating a new one. The same key must be supplied again to commit this intent.

Example:

"create-key-9f2c1b3a"

memo

string | null

Optional free-text memo carried onto the resulting transaction (max 1024 chars).

Example:

"Invoice INV-5530"

purpose

enum<string> | null

Optional payment purpose, used for compliance/reporting on cross-border payouts.

Available options:

PAYMENT_FOR_SERVICES,

PAYMENT_FOR_SOFTWARE,

PAYMENT_FOR_IMPORTED_GOODS,

TRAVEL_SERVICES,

VENDOR_CONTRACTOR_PAYOUTS,

TRANSFER_TO_OWN_ACCOUNT,

INVESTMENT_IN_SHARES,

PURCHASE_OF_PROPERTY,

REPAYMENT_OF_LOANS,

SALARY,

PAYMENT_OF_PROPERTY_RENTAL,

INFORMATION_SERVICE_CHARGES,

ADVERTISING_AND_PUBLIC_RELATIONS_EXPENSES,

ROYALTY_TRADEMARK_PATENT_AND_COPYRIGHT_FEES,

BROKER_FRONTEND_GUARANTEE_AND_CUSTODIAN_FEES,

ADVISOR_TECHNICAL_AND_ACADEMIC_FEES,

REPRESENTATIVE_OFFICE_EXPENSES,

TAX_PAYMENT,

TRANSPORTATION_FEES_FOR_GOODS,

CONSTRUCTION_COSTS,

INSURANCE_PREMIUM,

GENERAL_GOODS_TRADES_OFFLINE,

INSURANCE_CLAIMS_PAYMENT,

FAMILY_MAINTENANCE,

EDUCATION_RELATED_EXPENSES,

MEDICAL_TREATMENT,

DONATIONS,

MUTUAL_FUND_INVESTMENT,

CURRENCY_EXCHANGE,

USER_WITHDRAWAL,

ADVANCE_PAYMENTS_FOR_GOODS,

VENDOR_CONTRACTOR_PAYOUTS_SOFTWARE_DEVELOPMENT,

MERCHANT_SETTLEMENT,

REPATRIATION_FUND_SETTLEMENT,

PERSONAL_REMITTANCE,

RETURN_OF_FUNDS,

null

Example:

"VENDOR_CONTRACTOR_PAYOUTS"

creditRail

enum<string> | null

Optional rail to pay the credit instrument over, e.g. ACH or WIRE for a US bank account, SWIFT for an international one, or the wallet's chain for a stablecoin payout. Must be one of the rails the credit instrument can be paid over. Omit to let payout routing choose the rail.

Available options:

WIRE,

ACH,

RTP,

SEPA,

SEPA_INSTANT,

SWIFT,

EXTERNAL_WALLET,

ETHEREUM,

BASE,

POLYGON,

null

Example:

"ACH"

Response

The created transaction intent preview

A transaction-shaped preview of a movement of funds. No funds move until the intent is committed.

string

required

Unique identifier of the transaction intent

Example:

"txnint_01JMERINTENT001"

type

enum<string>

required

Type of transaction the intent would create

Available options:

TRANSFER,

DEPOSIT,

WITHDRAWAL,

REFUND,

PARTIAL_REFUND

Example:

"TRANSFER"

createdAt

string<date-time>

required

Timestamp when the transaction intent was created

Example:

"2026-04-30T15:00:00Z"

updatedAt

string<date-time>

required

Timestamp when the transaction intent was last updated

Example:

"2026-04-30T15:02:00Z"

status

enum<string>

required

Current status of the transaction intent

Available options:

CREATED,

EXPIRED,

CANCELED,

COMMITTED,

FAILED

Example:

"CREATED"

debitAmount

string

required

Amount to be debited as a decimal string

Example:

"7250.00"

debitCurrency

string

required

ISO 4217 currency code on the debit side

Example:

"USD"

debitInstrument

Account Instrument · object

required

Meridian (balance) account instrument

Account Instrument
Bank Account Instrument
Virtual Account Instrument
External Wallet Instrument

Show child attributes

creditAmount

string

required

Amount to be credited as a decimal string

Example:

"7250.00"

creditCurrency

string

required

ISO 4217 currency code on the credit side

Example:

"USD"

creditInstrument

Account Instrument · object

required

Meridian (balance) account instrument

Account Instrument
Bank Account Instrument
Virtual Account Instrument
External Wallet Instrument

Show child attributes

fees

Transaction Fee · object[]

required

Fees that would be applied to the transaction

Show child attributes

exchangeRate

string

required

Exchange rate that would be applied

Example:

"1"

statusReason

string | null

Reason for the current status

ID of the transaction created when the intent was committed

debitMemo

string | null

Debit-side memo or reference text supplied when the intent was created

Example:

"INV-23014"

purpose

enum<string> | null

Payment purpose

Available options:

PAYMENT_FOR_SERVICES,

PAYMENT_FOR_SOFTWARE,

PAYMENT_FOR_IMPORTED_GOODS,

TRAVEL_SERVICES,

VENDOR_CONTRACTOR_PAYOUTS,

TRANSFER_TO_OWN_ACCOUNT,

INVESTMENT_IN_SHARES,

PURCHASE_OF_PROPERTY,

REPAYMENT_OF_LOANS,

SALARY,

PAYMENT_OF_PROPERTY_RENTAL,

INFORMATION_SERVICE_CHARGES,

ADVERTISING_AND_PUBLIC_RELATIONS_EXPENSES,

ROYALTY_TRADEMARK_PATENT_AND_COPYRIGHT_FEES,

BROKER_FRONTEND_GUARANTEE_AND_CUSTODIAN_FEES,

ADVISOR_TECHNICAL_AND_ACADEMIC_FEES,

REPRESENTATIVE_OFFICE_EXPENSES,

TAX_PAYMENT,

TRANSPORTATION_FEES_FOR_GOODS,

CONSTRUCTION_COSTS,

INSURANCE_PREMIUM,

GENERAL_GOODS_TRADES_OFFLINE,

INSURANCE_CLAIMS_PAYMENT,

FAMILY_MAINTENANCE,

EDUCATION_RELATED_EXPENSES,

MEDICAL_TREATMENT,

DONATIONS,

MUTUAL_FUND_INVESTMENT,

CURRENCY_EXCHANGE,

USER_WITHDRAWAL,

ADVANCE_PAYMENTS_FOR_GOODS,

VENDOR_CONTRACTOR_PAYOUTS_SOFTWARE_DEVELOPMENT,

MERCHANT_SETTLEMENT,

REPATRIATION_FUND_SETTLEMENT,

PERSONAL_REMITTANCE,

RETURN_OF_FUNDS,

null

creditRail

enum<string> | null

Rail the credit instrument will be paid over, when one was pinned on the intent

Available options:

WIRE,

ACH,

RTP,

SEPA,

SEPA_INSTANT,

SWIFT,

EXTERNAL_WALLET,

ETHEREUM,

BASE,

POLYGON,

null

Example:

"ACH"

Getting Started

Authentication

Enrollment

Transactions

API Reference

Webhooks

Create a transaction intent

Authorizations

Headers

Body

Response