Payment Order Webhooks

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.

Payment Order Events

EventDescription
createdA payment order has been created. This happens when the Async Create Payment Order endpoint is used.
updatedAn attribute other than the payment order status has been modified. This happens when a user or API client edits a payment order.
failedA payment order failed to be created. This happens when the Async Create Payment Order endpoint is used.

You can simulate failed payment orders here.

You may redraft a failed payment order by using the Update Payment Order endpoint.
approvedA payment order has been approved.
deniedA payment order has been denied.
cancelledA payment order has been cancelled.
begin_processingA payment order has begun processing. Payment orders will no longer be editable after this point.
finish_processingA payment order has finished processing and been sent to the bank.
acknowledgedA Payment Order has been acknowledged by the bank. A Payment Order has passed initial validation & processing and may have been assigned unique identifiers by the originating bank. This does not mean the payment has been transmitted by the bank to the underlying network (e.g. NACHA or Fedwire). This does not guarantee that the payment will settle and may still fail due to compliance or other reasons.

Does not change the payment order's state.
confirmedA Payment Order has been transmitted by the bank to the underlying network and has been confirmed by the network. This is typically accompanied by the creation of PaymentReference objects representing unique reference numbers assigned to the payment by the network (e.g. ACH trace numbers or Fedwire IMAD/OMAD). This does not guarantee that the payment will settle and may still be failed or returned by the receiving bank (RDFI).

Does not change the payment order's state.
tentatively_reconciledA 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.
completedA payment order has been reconciled with a posted transaction.
returnedA payment order has been returned. You may redraft the payment order by using the Update Payment Order endpoint.
redraftedA payment order has been redrafted.
reversedA payment order reversal has been sent.
nsf_defermentThis 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_processingThis 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.
unreconciledA payment order has been unreconciled from a transaction.

🚧

Note that not all PaymentOrder events are associated with a change in status.

Payment Order Statuses

Payment orders have many states, which may also be sent as webhook events based on your configuration. You can find the full list of payment order states below.

StatusDescription
needs_approvalThe 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.
approvedThe payment order has been approved and will be sent to the bank.
processingThis 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.
sentThe 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.
completedThe 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.
returnedThe payment order has been returned. There is typically an associated Return object with more information.
reversedThe payment order has been reversed. There is typically an associated Reversal object with more information.
failedThis 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.
Note that the lifecycle diagram below only shows an arrow to the failed state down the asynchronous create path.
If a failure is associated with a vendor (e.g. Currencycloud), a vendor_failure_reason may be provided.
deniedThe payment order has been denied. This is a terminal state. This state is reached if a payment order in needs_approval was denied by an approver.
cancelledThe payment order was cancelled. This is a terminal state.

Special Cases

Check Payment Order Completed Status

In most cases, Check Payment Orders will be marked as completed when the bank reports the check as deposited by the recipient. This behavior allows you to retrieve outstanding checks by retrieving payment orders in the sent status.

Acknowledged and Confirmed Events

The acknowledged and confirmed events are not available at all banking partners and for all payment types (aka “rails”). The availability of these events is dependent on the data sources available at each banking partner that Modern Treasury is integrated with and your organization’s specific configuration. Please reach out to your customer success manager (CSM) during onboarding if you need these events.

Duplicate Events

A single PaymentOrder may receive multiple events of the same type in the event of a redraft. When a terminal payment (i.e. failed, returned, cancelled) is redrafted, it will be re-transmitted and may receive certain events again. In these cases, the id of the PaymentOrder will remain constant and your system should handle this appropriately.

Sample Events

Successful event

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

Event with errors

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

Error from vendor

{
  "event": "failed",
  "data": {
    "id": "4897da42-7abd-464e-ab57-d4bf13f49aa0",
    "vendor_failure_reason":"Following payer details are missing: payer_postcode"
  }
}

Completed Payment Order

{
  "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",
    "transaction_monitoring_enabled": false,
    "decision_id": null,
    "updated_at": "2019-12-12T22:27:25Z"
  }
}