Payment Orders

As payment orders progress through their lifecycle, Modern Treasury will send webhooks to convey their latest statuses. The message body will include both an event and a data representation of the payment order. When there is an error, it will also be included. See the status codes section for additional details on how errors are presented.

These are the events you may receive:

Event	Description
created	A payment order has been created. This happens when the Async Create Payment Order endpoint is used.
failed	A payment order failed to be created. This happens when the Async Create Payment Order endpoint is used.
approved	A payment order has been approved.
denied	A payment order has been denied.
cancelled	A payment order has been cancelled.
begin_processing	A payment order has begun processing. Payment orders will no longer be editable after this point.
finish_processing	A payment order has finished processing and been sent to the bank.
tentatively_reconciled	A payment order has been tentatively reconciled to a pending transaction. This can be helpful to process if you are confident the transaction will post. See the guide for more information. Does not change the payment order's state.
completed	A payment order has been reconciled with a posted transaction.
returned	A payment order has been reversed. You may redraft the payment order by using the Update Payment Order endpoint.
nsf_deferment	This only applies for payment orders that are using NSF Protection. If the counterparty's balance is insufficient to cover the payment order, or if there is an error from Plaid while retrieving the balance, this event is sent. This means that the payment order was not sent to the bank and is still in the `approved` state.
nsf_plaid_error_but_processing	This only applies for payment orders that are using NSF Protection. This event can only be fired if your NSF Protection settings have opted you into initiating the payment orders even when the Plaid check has failed. When this event fires, it means that we were unable to pull the counterparty's balance from Plaid but still sent the payment order the bank.

These are the statuses a payment order may have:

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. The payment order will typically leave processing in under a second.
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	The payment order has been reconciled to a posted bank transaction. At this point, we know the payment occurred, and your account will have been debited or credited. 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.
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.
denied	The payment order has been denied. This is a terminal state.
cancelled	The payment order was cancelled. This is a terminal state.

Payment Order Lifecycle with Webhooks

{
  "event": "created",
  "data": {
    "id": "fd3c1f59-6d5b-466c-9126-7f8c82ad6e1c",
    "type": "ach",
    ...
  }
}

{
  "event": "failed",
  "data": {
    "id": "fd3c1f59-6d5b-466c-9126-7f8c82ad6e1c"
  },
  "error": {
    "code": "parameter_invalid",
    "message": "amount is invalid",
    "parameter": "amount"
  }
}

{
  "event": "completed",
  "data": {
    "accounting_category_id": null,
    "amount": 123100,
    "charge_bearer": null,
    "counterparty_id": "928db55e-6552-4aaf-96d7-10c693922b1f",
    "created_at": "2019-12-12T22:27:22Z",
    "currency": "USD",
    "description": null,
    "direction": "credit",
    "effective_date": "2019-12-13",
    "foreign_exchange_contract": null,
    "foreign_exchange_indicator": null,
    "id": "9f7e0efa-aeb7-4378-ae18-b4bb038e5495",
    "metadata": {},
    "object": "payment_order",
    "originating_account_id": "b9fc1ae0-d493-4f01-a7b3-b39104e802b5",
    "priority": "normal",
    "receiving_account": {
      "account_details": [
        { ... },
      ],
      "account_type": "checking",
      "created_at": "2019-11-21T22:51:04Z",
      "id": "71fae619-afa6-45e6-8630-ce4d0b3d6387",
      "intermediate_account_id": null,
      "object": "external_account",
      "party_address": null,
      "party_name": "John Smith",
      "party_type": null,
      "routing_details": [
        { ... },
      ],
      "updated_at": "2019-11-21T22:51:04Z",
      "verification_status": "unverified"
    },
    "receiving_account_id": "71fae619-afa6-45e6-8630-ce4d0b3d6387",
    "receiving_account_type": "external_account",
    "remittance_information": "December Rent",
    "statement_descriptor": "Rent",
    "status": "completed",
    "transaction_ids": [],
    "type": "ach",
    "updated_at": "2019-12-12T22:27:25Z"
  }
}