A payment_order is an instruction to move money to or from your account via payment types such as ACH, wire, RTP, stablecoin, and check. The payment order includes statuses that update you over the lifecycle of the payment.

Related Guides:

Attribute	Description
id string	Unique identifier for the payment order
external_id string	An optional user-defined 180 character unique identifier
type string	One of `ach`(US ACH) `book`(Book) `check` (Check) `rtp` (Real Time Payment and FedNow) `stablecoin` (onchain transfer in USDG, USDC, PYUSD, USDT, etc) `wire` (Domestic Wires)
subtype string	An additional layer of classification for the type of payment order you are doing. This field is only used for `ach` and `stablecoin` payment orders currently. For `ach` payment orders, the `subtype` represents the SEC code. We currently support `CCD`, `PPD`, `CTX`, `WEB`, and `TEL`. For `stablecoin`, pass in the intended blockchain network. See here for a list supported networks.
amount int64	Value in specified currency's smallest unit. e.g. $10 (US Dollar) would be represented as `1000`. For stablecoins (USDC, USDG, USDT, PYUSD), the smallest unit is 6 decimal places — e.g. $10 USDC would be represented as `10000000`. For RTP, the maximum amount allowed by the network is $10,000,000.
currency string	Must conform to ISO 4217. Defaults to the currency of the originating account.
direction string	One of `credit`, `debit` Describes the direction money is flowing in the transaction. A `credit` moves money from your account to someone else's. A `debit` pulls money from someone else's account to your own. Note that rtp and check payments will always be `credit`.
status string	The current status of the payment order. See the status section for details.
reconciliation_status string	The current reconciliation status. One of `unreconciled`, `tenatively_reconciled`, or `reconciled`.
priority string	Either `normal` or `high`. `high` priority is only available for `ach` and `check` payment types. For ACH payments, `high` represents a same-day transfer. For check payments, `high` can mean an overnight check rather than standard mail. For all other payment types, `high` priority payments are treated the same as `normal` priority payments.
originating_account_id string	The ID of one of your organization's internal accounts
receiving_account_id string	The receiving account ID. Can be an external account or internal account
receiving_account_type string	The receiving account type. Can be one of `external_account` or `internal_account`.
description string	An optional description for internal use.
effective_date date	Date transactions are to be posted to the participants' account. Defaults to the current business day or the next business day if the current day is a bank holiday or weekend. Format: yyyy-mm-dd
process_after string	If present, Modern Treasury will not process the payment until after this time. If `process_after` is past the cutoff for `effective_date`, `process_after` will take precedence and `effective_date` will automatically update to reflect the earliest possible sending date after `process_after`. Format: ISO8601 timestamp
statement_descriptor string	An optional descriptor which will appear in the receiver's statement. For `check` payments this field will be used as the memo line. For `ach` the maximum length is 10 characters. Note that for ACH payments, the name on your bank account will be included automatically by the bank, so you can use the characters for other useful information.
remittance_information string	For `ach`, this field will be passed through on an addenda record. For `wire` payments the field will be passed through as the "Originator to Beneficiary Information", also known as OBI or Fedwire tag 6000. Character limits vary by bank and rail. Typical limits are 80 characters for `ach` payments, and 140 characters for `wire` payments.
purpose string	For `wire`, this is usually the purpose which is transmitted via the "InstrForDbtrAgt" field in the ISO20022 file.
metadata object	Additional data represented as key-value pairs. Both the key and value must be strings. See Metadata.
counterparty_id string	If the payment order is tied to a specific Counterparty , their id will appear, otherwise `null`.
transaction_ids array	The IDs of all the transactions associated to this payment order. Usually, you will only have a single transaction ID. However, if a payment order initially results in a Return, but gets redrafted and is later successfully completed, it can have many transactions.
current_return object	If the payment order's status is `returned`, this will include the return object's data.
current_hold object	If the payment order's status is `held`, this will include the Hold object's data.
originating_party_name string	If present, this will replace your default company name on receiver's bank statement. This field can only be used for ACH payments currently. For ACH, only the first 16 characters of this string will be used. Any additional characters will be truncated.
nsf_protected boolean Default:* `false`	A boolean to determine if NSF Protection is enabled for this payment order. NSF Protection is a feature that only works for external accounts that are created with Plaid processor tokens. Also note that you must turn on the setting for this feature in your organization settings page.
live_mode boolean	This field will be true if this object was created with a production API key or false if created with a test API key.
reference_numbers array	An array of Payment Reference objects.
ledger_transaction_id string	The ID of the ledger transaction linked to the payment order. See Linking to other Modern Treasury objects .

{
  "id": "c5f4009c-bdd6-4cc1-84b2-17974ac9e77a",
  "external_id": null,
  "type": "ach",
  "subtype": null,
  "amount": 20000,
  "currency": "USD",
  "direction": "credit",
  "status": "approved",
  "reconciliation_status": "unreconciled",
  "priority": "normal",
  "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
  "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5",
  "receiving_account_type": "external_account",
  "description": "Invoice #12345 payment",
  "effective_date": "2018-11-08",
  "process_after": null,
  "statement_descriptor": "Rerum del.",
  "remittance_information": "Accusamus tempore molestiae laboriosam.",
  "purpose": null,
  "metadata": {
    "invoice_id": "INV-12345",
    "customer_ref": "CUST-789"
  },
  "counterparty_id": "37ba4454-dd33-4aa0-8906-0e2e4103e45c",
  "transaction_ids": [],
  "current_return": null,
  "current_hold": null,
  "nsf_protected": false,
  "originating_party_name": "Acme Company",
  "live_mode": true,
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z"
}

Payment Order Statuses

The statusfield represents the current state of a payment order. Webhook events can be configured to listen for changes in state.

Status	Description
`needs_approval`	The payment order needs at least one approval before it can be sent to the bank. Note that if the `effective_date` on the payment order has been passed but the payment order isn't approved yet, it will be sent to the bank at the earliest time after it is approved.
`approved`	The payment order has been approved and will be sent to the bank.
`processing`	This is a very short state where Modern Treasury is preparing the payment order to be sent to the bank. Once it begins processing, it cannot be edited anymore.
`sent`	The payment order has been sent to the bank. It may remain in this state for up to a few days, depending on the type of payment.
`completed`	A payment order has been completed. The bank has accepted and executed the payment instruction, and the transaction has been posted to the customer’s ledger, indicating that funds have been accepted or released. Note however, that some payment types are not final. For an ACH, you may still get a return later.
`returned`	The payment order has been returned. There is typically an associated `Return` object with more information.
`reversed`	The payment order has been reversed. There is typically an associated `Reversal` object with more information.
`failed`	This status is rare but may happen if there is an error at the bank. It can also happen when using the asynchronous create API endpoint, if the parameters are invalid. Note that the lifecycle diagram below only shows an arrow to the failed state down the asynchronous create path.
`denied`	The payment order has been denied. This is a terminal state. This state is reached if a payment order in `needs_approval` was denied by an approver.
`cancelled`	The payment order was cancelled. This is a terminal state.
`held`	The payment order has been placed on hold for compliance reasons.