Sign in

v1

latestOpenAPI 3.1.02026-07-241910582.8 KB

Create Payment Order

Create a new Payment Order

post/payment_orders

Request body

typestring required

Select type from the list at Payment Orders

fallback_typestring

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)

subtypestring

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

amountinteger 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.

directionstring 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_idstring required

The ID of one of your organization's internal accounts

receiving_account_idstring

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.

ledger_transaction_idstring

Specifies the ID of a ledger transaction 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.

currencystring

Must conform to ISO 4217. Defaults to the currency of the originating account. For currency conversions, this must be the target currency.

process_afterstring date-time

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 is ISO8601 timestamp. Please reach out to your Customer Success team to determine if your bank connections support this feature.

effective_datestring 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

prioritystring

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.

descriptionstring

An optional description for internal use.

statement_descriptorstring

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_informationstring

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.

purposestring

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 that will be attached to the payment.

metadatastring json

Additional data represented as key-value pairs. Both the key and value must be strings. See Metadata.

charge_bearerstring

The party that will pay the fees for the payment order. Read Charge Bearer to learn more about possible values and how they get serialized

foreign_exchange_indicatorstring

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_contractstring

If present, indicates a specific foreign exchange contract number that has been generated by your financial institution.

nsf_protectedboolean

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_namestring

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_idstring

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_namestring

Name of the ultimate originator of the payment order.

ultimate_originating_party_identifierstring

Identifier of the ultimate originator of the payment order.

ultimate_receiving_party_namestring

Name of the ultimate funds recipient.

ultimate_receiving_party_identifierstring

Identifier of the ultimate funds recipient.

send_remittance_adviceboolean

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 will be used to determine whether the email is sent..

expires_atstring date-time

RFP payments require an expires_at. This value must be past the effective_date.

vendor_attributesstring 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.

external_idstring

An optional user-defined 180 character unique identifier

Response

200

idstring
typestring
amountinteger
directionstring
originating_account_idstring
receiving_account_idstring
receiving_account_typestring
accounting_category_idstring
accounting_ledger_class_idstring
currencystring
{"stackTrail":"paths:/payment_orders:post:responses:200:content:application/json:schema:properties:ledger_transaction_id","oasType":"schema","type":"unknown"}
effective_datestring
prioritystring
descriptionstring
statement_descriptorstring
remittance_informationstring
metadataobject
statusstring
counterparty_idstring
{"stackTrail":"paths:/payment_orders:post:responses:200:content:application/json:schema:properties:current_return","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/payment_orders:post:responses:200:content:application/json:schema:properties:charge_bearer","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/payment_orders:post:responses:200:content:application/json:schema:properties:foreign_exchange_indicator","oasType":"schema","type":"unknown"}
{"stackTrail":"paths:/payment_orders:post:responses:200:content:application/json:schema:properties:foreign_exchange_contract","oasType":"schema","type":"unknown"}
send_remittance_adviceboolean
nsf_protectedboolean
transaction_monitoring_enabledboolean
originating_party_namestring
ultimate_originating_party_namestring
ultimate_originating_party_identifierstring
ultimate_receiving_party_namestring
ultimate_receiving_party_identifierstring
live_modestring
created_atstring
updated_atstring

Example response

{
  "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",
    "account_type": "checking",
    "party_name": "John Smith",
    "party_type": "business",
    "account_details": [
      {
        "id": "81a7cd32-39f5-4f0c-873f-4d9137ec9cd9",
        "account_number_safe": "1291"
      }
    ],
    "routing_details": [
      {
        "id": "5ceb251f-0235-48a2-81cb-0c668f5ee81b",
        "routing_number": "121141822",
        "routing_number_type": "aba"
      }
    ]
  },
  "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.",
  "status": "approved",
  "counterparty_id": "37ba4454-dd33-4aa0-8906-0e2e4103e45c",
  "send_remittance_advice": true,
  "originating_party_name": "Acme Company",
  "ultimate_originating_party_name": "Jane Doe",
  "ultimate_originating_party_identifier": "A1823N",
  "ultimate_receiving_party_name": "John Smith",
  "ultimate_receiving_party_identifier": "A8738N",
  "live_mode": "true",
  "created_at": "2019-11-09T00:11:07Z",
  "updated_at": "2019-11-09T00:11:07Z"
}