⚠️
The Payment Order API is shared across all Modern Treasury integrations. This page documents the full set of fields and payment types available when directly integrating your own bank accounts. PSP customers should reference this page instead.

A payment_order is an instruction to move money to or from your bank account via payment types such as ACH, wire, RTP, and check. When a new payment order is created on Modern Treasury, we communicate with your bank to move the amount of money you specified.

This page covers Payment Orders for organizations using their own bank connection (BYO Bank). For PSP-specific Payment Orders documentation, see Payment Orders.

Related Guides:

Attribute	Description
id string	Unique identifier for the payment order
type string	One of `ach`, `eft`, `wire`, `check`, `sen`, `book`, `rtp`, `sepa`, `bacs`, `au_becs`, `interac`, `signet`, `provexchange`, `cross_border`.
subtype string	An additional layer of classification for the type of payment order you are doing. This field is only used for `ach` and `cross_border` payment orders currently. For `ach` payment orders, the `subtype` represents the SEC code. We currently support `CCD`, `PPD`, `IAT`, `CTX`, `WEB`, `CIE`, and `TEL`.
amount int64	Value in specified currency's smallest unit. e.g. $10 (US Dollar) would be represented as `1000`, while ¥10 (Japanese Yen) would be represented as `10`. For RTP, the maximum amount allowed by the network is $10,000,000.
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 wire, rtp, and check payments will always be `credit`.
status string	The current status of the payment order. See the webhooks section for more on the different statuses.
reconciliation_status string	The current reconciliation status. One of `unreconciled`, `tenatively_reconciled`, or `reconciled`.
priority string	Either `normal` or `high`. For ACH and EFT payments, `high` represents a same-day ACH or EFT transfer, respectively. For check payments, `high` can mean an overnight check rather than standard mail.
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`.
ledger_transaction_id string	The ID of the ledger transaction linked to the payment order. See Linking to other Modern Treasury objects.
accounting_category_id string	The ID of one of your accounting categories. Note that these will only be accessible if your accounting system has been connected.
accounting_ledger_class_id string	The ID of one of your accounting ledger classes. Note that these will only be accessible if your accounting system has been connected.
currency string	Must conform to ISO 4217. Defaults to the currency of the originating 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 date	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. For `eft` the maximum length is 15 characters.
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.
purpose string	For `wire`, this is usually the purpose which is transmitted via the "InstrForDbtrAgt" field in the ISO20022 file. If you are using Currencycloud, this is the `payment.purpose_code` field. For `eft`, this field is the 3 digit CPA Code that will be attached to the payment.
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.
charge_bearer string	The party that will pay the fees for the payment order. Only applies to `wire` payment orders. Can be one of `shared`, `sender`, or `receiver`, which correspond respectively with the SWIFT 71A values `SHA`, `OUR`, `BEN`.
foreign_exchange_indicator string	Indicates the type of FX transfer to initiate, can be either `variable_to_fixed`, `fixed_to_variable`, or `null` if the payment order currency matches the originating account currency.
foreign_exchange_contract string	If present, indicates a specific foreign exchange contract number that has been generated by your financial institution.
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.
transaction_monitoring_enabled boolean	A boolean that indicates whether Transaction Monitoring is enabled for this Payment Order. Note that you must have purchased Compliance to use this feature.
compliance_rule_metadata object	Pass in additional data for use in Compliance rules. Data must be represented as key-value pairs, where the key and value are strings. See Metadata.
decision_id string	If Transaction Monitoring is enabled and this payment order is tied to a specific Decision, the id will appear, otherwise `null`.
ultimate_originating_account_id string	The account ID to which the origination of this payment should be attributed to. Can be a virtual account or internal account. The originating account must be the parent account of the ultimate originating account.
ultimate_originating_account_type string	The ultimate originating account type. Can be one of `virtual_account` or `internal_account`.
ultimate_originating_party_identifier string	Identifier of the ultimate originator of the payment order.
ultimate_originating_party_name string	Name of the ultimate originator of the payment order.
ultimate_receiving_party_identifier string	Identifier of the ultimate funds recipient.
ultimate_receiving_party_name string	Name of the ultimate funds recipient.
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.
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.
reference_numbers array	An array of Payment Reference objects.
vendor_failure_reason string	This field will be populated if a vendor (e.g. Currencycloud) failure occurs. Logic shouldn't be built on its value as it is free-form.
send_remittance_advice boolean	Send an email to the counterparty when the payment order is sent to the bank. If `null`, `send_remittance_advice` on the Counterparty is used.
expires_at datetime	The datetime that a RFP type payment expires, `null` for non RFP payments

{
  "id": "c5f4009c-bdd6-4cc1-84b2-17974ac9e77a",
  "type": "ach",
  "amount": 20000,
  "direction": "credit",
  "originating_account_id": "0f8e3719-3dfd-4613-9bbf-c0333781b59f",
  "receiving_account_id": "5acec2ef-987b-4260-aa97-b719eeb0a8d5",
  "receiving_account_type": "external_account",
  "accounting_category_id": "45ac4565-2302-41c9-962a-1a9d7e85db99",
  "accounting_ledger_class_id": "d59c3d5c-bcf9-4efb-8a0a-46a5f4394028",
  "currency": "USD",
  "effective_date": "2018-11-08",
  "priority": "normal",
  "description": "Repellendus deleniti atque quod.",
  "statement_descriptor": "Rerum del.",
  "remittance_information": "Accusamus tempore molestiae laboriosam.",
  "metadata": {},
  "status": "approved",
  "reconciliation_status": "unreconciled",
  "counterparty_id": "37ba4454-dd33-4aa0-8906-0e2e4103e45c",
  "send_remittance_advice": true,
  "transaction_ids": [],
  "current_return": null,
  "current_hold": null,
  "charge_bearer": null,
  "foreign_exchange_indicator": null,
  "foreign_exchange_contract": null,
  "subtype": null,
  "purpose": null,
  "nsf_protected": false,
  "originating_party_name": "Acme Company",
  "ultimate_originating_account_id": "388d37b2-3b15-48a8-8765-609241476a27",
  "ultimate_originating_account_type": "virtual_account",
  "ultimate_originating_party_name": "Jane Doe",
  "ultimate_originating_party_identifier": "A1823N",
  "ultimate_receiving_party_name": "Jane Doe",
  "ultimate_receiving_party_identifier": "A1823N",
  "transaction_monitoring_enabled": false,
  "decision_id": null,
  "live_mode": true,
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z",
  "compliance_rule_metadata": {}
}

Payment Order Statuses

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

Legend:

flowchart LR
    state_1(["State 1"]) -->|webhook_event| state_2(["State 2"])

    classDef active fill:#1EA373,stroke:#1EA373,color:#FFFFFF

    class state_1,state_2 active

flowchart TD
    create["Create Payment Order in App or API"]

    needs_approval(["Needs Approval ²"])
    denied(["Denied"])
    cancelled(["Cancelled"])
    approved(["Approved"])
    processing(["Processing"])
    sent(["Sent"])
    stopped(["Stopped ⁴"])
    failed(["Failed ³"])
    completed(["Completed ⁵"])
    returned(["Returned ⁶"])
    reversed(["Reversed"])

    create -->|created ¹| needs_approval
    needs_approval -->|denied| denied
    needs_approval -->|cancelled| cancelled
    needs_approval -->|approved| approved
    approved -->|cancelled| cancelled
    approved -->|begin_processing| processing
    processing -->|finish_processing| sent
    sent -->|stopped| stopped
    sent -->|completed| completed
    sent -->|returned| returned
    sent -->|reversed| reversed
    sent -->|failed| failed
    completed -->|returned| returned
    completed -->|reversed| reversed
    create -->|failed ¹| failed
    failed -->|redrafted| needs_approval
    returned -->|redrafted| needs_approval

    reversed ~~~ returned

    classDef entry fill:#2B71D4,stroke:#2B71D4,color:#FFFFFF
    classDef active fill:#1EA373,stroke:#1EA373,color:#FFFFFF
    classDef terminal fill:#CD3640,stroke:#CD3640,color:#FFFFFF

    class create entry
    class needs_approval,approved,processing,sent,completed,reversed active
    class denied,cancelled,failed,stopped,returned terminal

The created and failed events are only emitted during creation when using the asynchronous API. Synchronous calls will return an HTTP code (201, 4xx) on success or failure.
If there are no Approval Rules triggered, a Payment Order will go straight from Needs Approval to Approved.
Once Sent, a payment may move to Failed from any state if the originating bank sends us a failure notification. When processing webhooks or polling for payment statuses, make sure you account for these edge cases.
Stopped is only relevant for checks managed via Payment Actions.
Completed does not imply reconciliation. Use the Reconciliation Status attribute to determine reconciliation state.
A Return implies that the originated payment reached the RDFI. However, when a Return is received on a Sent Payment Order it transitions directly to Returned.

Status	Description
`needs_approval`	The payment order needs at least one internal approval before it can be sent to the bank. If the `effective_date` has passed but it isn’t approved yet, it will be sent at the earliest time after approval.
`approved`	The payment order has been internally approved and will be sent to the bank.
`denied`	The payment order has been denied by an approver during internal approval.
`cancelled`	The payment order was cancelled before being processed.
`processing`	Modern Treasury is preparing the payment order to be sent for approval and execution. Once processing begins, the payment order cannot be edited or cancelled 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 order.
`held`	The payment order has been placed on hold. Holds can be added manually for Bring Your Own Bank Payment Orders and either manually resolved or automatically resolved by further state changes on the payment order.
`stopped`	Check-specific: the positive pay file associated with the payment order has been revoked or cancelled.
`completed`	The payment order has been executed, and the transaction has been posted to the originating ledger at the bank, indicating that funds have been accepted or released. Note: some payment order types are not final (e.g., ACH can still return later).
`returned`	The payment order was returned after completing. There is an associated `Return` object with more information.
`reversed`	The payment order has been reversed. There is an associated `Reversal` object with more information.
`failed`	The payment was unable to be executed. More information as to the reason may be provided on `failure_reason`.