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"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

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"
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

{
  "message": "<string>",
  "validationErrors": [
    {
      "fieldRef": "<string>",
      "message": "<string>"
    }
  ]
}

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, and the amount to price

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), e.g. a beneficiary bank account id. Must differ from debitInstrumentId.

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 positive decimal string in that side's currency.

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"

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
External Wallet Instrument
Virtual Account 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
External Wallet Instrument
Virtual Account 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

⌘I

Getting Started

Authentication

Enrollment

Transactions

API Reference

Webhooks

Create a transaction intent

Authorizations

Headers

Body

Response