---
title: "Create Payment Order"
method: POST
path: "/byob/payment_orders"
---

# Create Payment Order

`POST /byob/payment_orders`

Create a new Payment Order

## Request body

- object
  - `type` string, required — Select type from the list at [Payment Orders](https://docs.moderntreasury.com/platform/reference/payment-order-object)
  - `fallback_type` string — The payment type used to create the payment order if the original `type` is not valid for the receiving account. Currently, this only supports falling back from RTP to ACH (`type=rtp` and `fallback_type=ach`)
  - `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. Select subtype from the list at [Payment Orders](https://docs.moderntreasury.com/platform/reference/payment-order-object)
  - `amount` integer, required — Value in specified currency's smallest unit. e.g. $10 would be represented as `1000` (cents), and ¥10 would be represented as `10`. Network and bank limits may apply.
  - `direction` string, required — 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.
  - `originating_account_id` string, required — The ID of one of your organization's [internal accounts](https://docs.moderntreasury.com/platform/reference/internal-account-object)
  - `receiving_account_id` string — Either `receiving_account` or `receiving_account_id` must be present. When using `receiving_account_id`, you may pass the id of an external account or an internal account.
  - `receiving_account` object — Either `receiving_account` or `receiving_account_id` must be present. When using `receiving_account_id`, you may pass the id of an external account or an internal account. Note: This parameter is ignored when originating payments from a Modern Treasury Payments account; a `receiving_account_id` is required.
    - `account_type` string
    - `party_name` string
    - `party_type` string
    - `party_address` object
      - `line1` string
      - `line2` string
      - `locality` string
      - `region` string
      - `postal_code` string
      - `country` string
    - `account_details` object[]
      - `account_number` string, required
      - `account_number_type` string
    - `routing_details` object[]
      - `routing_number` string, required
      - `routing_number_type` string, required
      - `payment_type` string
    - `plaid_processor_token` string — If you've enabled the Modern Treasury + Plaid integration in your Plaid account, you can pass the processor token in this field.
  - `ledger_transaction` object — Specifies a [ledger transaction](https://docs.moderntreasury.com/platform/reference/ledger-transaction-object) object that will be created with the payment order. If the ledger transaction cannot be created, then the payment order creation will fail. The resulting ledger transaction will mirror the status of the payment order. See [Linking to other Modern Treasury objects](https://docs.moderntreasury.com/platform/docs/linking-to-other-modern-treasury-objects).
    - `description` string — An optional free-form description for internal use. Maximum of 1000 characters allowed.
    - `metadata` string, json — Metadata to be added to the ledger transaction. Must be a JSON object.
    - `effective_at` string, date-time — Format: ISO8601 to 6 decimal places. Defaults to time of insertion in the DB if not provided
    - `ledger_entries` object[]
      - `amount` integer, required — Supports any int value up to 10³⁶.
      - `direction` string, required — One of `credit` or `debit`.
      - `ledger_account_id` string, required
      - `lock_version` integer — Lock version of the ledger account. This can be passed when creating a ledger transaction to only succeed if no ledger transactions have posted since the given version. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#using-the-lock_version-field) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
      - `pending_balance_amount` object — Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s pending balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `posted_balance_amount` object — Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s posted balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `available_balance_amount` object — Use "gt" (>), "gte" (>=), "'lt" (<), "lte" (<=), or "eq" (=) to lock on the account’s available balance. If any of these conditions would be false after the transaction is created, the entire call will fail with error code 422. See [this guide](https://docs.moderntreasury.com/docs/handling-concurrency#locking-on-account-balance) for more details. This will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
        - `lt` integer
        - `lte` integer
        - `eq` integer
        - `gte` integer
        - `gt` integer
        - `not_eq` integer
      - `show_resulting_ledger_account_balances` boolean — If true, response will include the balance of the associated ledger account for the entry and will trigger synchronous processing, which imposes an additional rate limit on the API. See [Synchronous Ledger Entry Rate Limiting](https://docs.moderntreasury.com/docs/synchronous-ledger-entry-rate-limiting) for details.
      - `metadata` string, json
  - `ledger_transaction_id` string — Specifies the ID of a [ledger transaction](https://docs.moderntreasury.com/platform/reference/ledger-transaction-object) that will be linked to the payment order. If the payment order status and ledger transaction status do not match, the payment order creation will fail. The resulting ledger transaction will mirror the status of the payment order. See [Linking to other Modern Treasury objects](https://docs.moderntreasury.com/platform/docs/linking-to-other-modern-treasury-objects).
  - `currency` string — Must conform to ISO 4217. Defaults to the currency of the originating account. For currency conversions, this must be the target currency.
  - `process_after` string, date — If present, Modern Treasury will not [process](https://docs.moderntreasury.com/platform/reference/payment-orders) the payment until after this time. If `process_after` is past the [cutoff](https://docs.moderntreasury.com/platform/reference/ach-timings) 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 is [ISO8601 timestamp](https://docs.moderntreasury.com/platform/reference/timestamps). Please reach out to your Customer Success team to determine if your bank connections support this feature.
  - `effective_date` string, 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
  - `priority` string — Either `normal` or `high`. `high` priority is only available for `ach`, `eft`, and `check` payment types. For ACH and EFT 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.
  - `description` string — An optional description for internal use.
  - `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, this field will be passed through as the "Originator to Beneficiary Information", also known as OBI or Fedwire tag 6000. For `rtp` payments, this field will be included on the recipient's transaction.
  - `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 required and is the 3 digit [CPA Code](https://www.tdcommercialbanking.com/wbb/help/English/wbwEFTCPACodes.html) that will be attached to the payment.
  - `line_items` object[] — An array of line items that must sum up to the `amount` of the payment order. For more information see [Line Items](https://docs.moderntreasury.com/platform/reference/line-item-object)
    - `amount` integer
    - `metadata` string, json
    - `description` string
    - `accounting_category_id` string
  - `metadata` string, json — Additional data represented as key-value pairs. Both the key and value must be strings. See [Metadata](https://docs.moderntreasury.com/platform/reference/metadata).
  - `charge_bearer` string — The party that will pay the fees for the payment order. Read [Charge Bearer](https://docs.moderntreasury.com/payments/docs/charge-bearer) to learn more about possible values and how they get serialized
  - `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.
  - `nsf_protected` boolean — **Default:** `false`<br /> <br />A boolean to determine if NSF Protection is enabled for this payment order.<br /><br />**Note:** This setting must also be turned on in your organization settings page and enabled per payment order.
  - `originating_party_name` string — If present, this will replace your default company name on receiver's bank statement. Banks may institute maximum character lengths for different payment types. Characters above this limit may be truncated.
  - `ultimate_originating_account_id` string — The id of the account to which the origination of this payment should be attributed to. You may pass the id of a virtual account or an internal account.
  - `ultimate_originating_party_name` string — Name of the ultimate originator of the payment order.
  - `ultimate_originating_party_identifier` string — Identifier of the ultimate originator of the payment order.
  - `ultimate_originating_party_address` object — Address of the ultimate originator of the payment order.
    - `line1` string
    - `line2` string
    - `locality` string
    - `region` string
    - `postal_code` string
    - `country` string
  - `ultimate_receiving_party_name` string — Name of the ultimate funds recipient.
  - `ultimate_receiving_party_identifier` string — Identifier of the ultimate funds recipient.
  - `documents` object[] — An array of documents to be attached to the payment order. Note that if you attach documents, the request's content type must be `multipart/form-data`
    - `file` string, binary, required
    - `document_type` string
  - `send_remittance_advice` boolean — If `true`, an email will be sent to the counterparty when the payment order is sent to the bank. If `false`, the email will not be sent. If `null`, `send_remittance_advice` on the [Counterparty](https://docs.moderntreasury.com/platform/reference/counterparty-object) will be used to determine whether the email is sent..
  - `expires_at` string, date-time — RFP payments require an expires_at. This value must be past the effective_date.
  - `vendor_attributes` string, json — Additional vendor specific fields for this payment. Data must be represented as key-value pairs. Please contact our support team (help@moderntreasury.com) for a list of supported attributes.

## Response `200`

200

- object
  - `id` string
  - `type` string
  - `amount` integer
  - `direction` string
  - `originating_account_id` string
  - `receiving_account` object
    - `id` string
    - `account_type` string
    - `party_name` string
    - `party_type` string
    - `party_address` unknown
    - `account_details` object[]
      - `id` string
      - `account_number_safe` string
      - `account_number_type` unknown
    - `routing_details` object[]
      - `id` string
      - `payment_type` unknown
      - `routing_number` string
      - `routing_number_type` string
  - `receiving_account_id` string
  - `receiving_account_type` string
  - `accounting_category_id` string
  - `accounting_ledger_class_id` string
  - `currency` string
  - `ledger_transaction_id` unknown
  - `effective_date` string
  - `priority` string
  - `description` string
  - `statement_descriptor` string
  - `remittance_information` string
  - `metadata` object
  - `status` string
  - `counterparty_id` string
  - `transaction_ids` unknown[]
    - unknown
  - `current_return` unknown
  - `charge_bearer` unknown
  - `foreign_exchange_indicator` unknown
  - `foreign_exchange_contract` unknown
  - `send_remittance_advice` boolean
  - `nsf_protected` boolean
  - `transaction_monitoring_enabled` boolean
  - `originating_party_name` string
  - `ultimate_originating_party_name` string
  - `ultimate_originating_party_identifier` string
  - `ultimate_receiving_party_name` string
  - `ultimate_receiving_party_identifier` string
  - `live_mode` string
  - `created_at` string
  - `updated_at` string

---

[API](https://skmtc.net/modern-treasury/apis/modern-treasury-api.md) · [All operations](https://skmtc.net/modern-treasury/apis/modern-treasury-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modern-treasury/modern-treasury-api/versions/ed0431a2dcd0/schema)