Invoice Payments

Overview of invoice payments

Payment Methods

Modern Treasury provides multiple methods of payments. Choosing one of these methods will connect the payment to the lifecycle of the invoice and automatically update the status of the invoice based on the status of the payment.

Unoriginated Payment

Unoriginated payments are when your bank accounts receive a debit or credit originated by a counterparty. Whenever an invoice recipient sends a payment manually using the information provided on the invoice, that is an unoriginated payment. This is the default payment method for invoices since an end recipient could always choose this option.

To reconcile an unoriginated payment with an invoice, MT leverages expected payments. By default, an invoice will create a corresponding expected payment object when the invoice is issued. The expected payment will be set with attributes designed to match a payment for the invoice amount from the counterparty. It is recommended that the recipient puts the invoice number e.g. 2023-00004 on the statement description in their payment to improve the likelihood of matching the payment with the invoice. More details about the statement description can be found here. Once the expected payment has been matched with the corresponding transaction line item, those items will be associated with the invoice.

The expected payment will be automatically archived if another payment method is selected. If the end recipient pays through the payment UI, the expected payment will be archived. Similarly, if a payment is manually issued from with in Modern Treasury for the invoice, the expected payment will be archived.

The expected payment can also be manually reconciled via the "Reconcile" page by searching for the invoice number or by selecting "Reconcile Invoice" in the dropdown menu on the invoice page.

Embedded Payment UI

Invoices can be sent with embedded payment flows, this is a component on the invoice where the end recipient can enter the details of the account from which they want to be debited. Once the recipient hits submit a payment order is created to ACH debit their account. The originating account must have ACH debit capabilities enabled to use this payment method.

To send an invoice with an embedded component, either:

  • Enable payment collection on the create invoice page


  • Create an invoice with payment_method set to ui.

The recipient will receive an invoice looking like the following:

Automatic Payment

Invoices can be sent with automatic payments enabled, in this case a payment order object is created at the time the invoice is issued. Today we support ACH Debits via this method and the debit will be initiated on the Payment Effective Date. The originating account must have ACH debit capabilities enabled to use this payment method.

To send an invoice with a automatic payment either:

  • Enable automatic payment on the invoice creation page


  • Create an invoice with payment_method set to automatic and fill in the appropriate values for the parameters payment_effective_date, receiving_account_id, and payment_type. More information can be found on the invoice API reference.

Fallback Payment Method

When an automatic payment fails, it transitions the invoice back to the unpaid status and creates an expected payment to handle an unoriginated payment that might be issued in place of the automatic payment. By setting the fallback payment method to ui via the API or selecting payment collection on the invoice form, the invoice will automatically create an embedded payment ui on the invoice when the automatic payment fails. The email notification for the invoice payment failure to the invoice recipient will also provide a "Pay Invoice" link to the invoice, providing the recipient with an option to pay via the embedded payment ui.

Manually Issuing Payment

After an invoice has transitioned from draft to the unpaid state, a payment can be manually issued via the UI or the API. The payment order issued must have matching originating_account_id, amount, currency to the invoice and must be in the direction of a debit.

Invoice Status

The invoice lifecycle will be directly connected to the payment object it is associated with. When the payment order or expected payment successfully completes, the invoice will be marked as paid. When a payment order is created, the invoice will be marked as payment_pending.

Invoices can be manually marked as paid through the UI or the API as long as the invoice is not in the payment_pending state.

When an invoice is transitioned to payment_pending through embedded payment UI or paid manually, any associated expected payment object will automatically be archived to avoid duplicated payments.

Required permissions

To use invoice payments, you will need the following permissions:

  1. Ability to manage the originating account associated with the invoice
  2. Ability to read the invoice counterparty

To create an invoice with automatic payment enabled, you will need the above permissions in addition to:

  1. Ability to read the receiving account
  2. Ability to create a new payment order

To create an invoice with an associated virtual account, you will need the above permissions in addition to:

  1. Ability to read the virtual account