Payment Actions are only available on select connections. Please reach out to [email protected] or your customer success manager to confirm availability for your connection.
A payment_action is an object that represents additional actions or instructions that should be sent to the bank regarding a specific payment (e.g. a payment_order) that is distinct from the payment initiation instruction.
| Attribute | Description |
|---|---|
| id string | Unique identifier for the payment order |
| live_mode boolean | This field will be true if this object was created with a production API key or false if created with a test API key. |
| actionable_id string | The id of the payment to action on. Optional, but if present, the actionable_type must also be present. |
| actionable_type string | The type of the payment being actioned on. One of payment_order, expected_payment. Optional, but if present, the actionable_id must also be present. |
| type string | The type of action decision for this specific payment action. The possible actions are determined based on the of the actionable. |
| status string | The status of the payment action. One of pending, processable, processing, sent, acknowledged, failed, cancelled. For bank connections where Modern Treasury does not receive acknowledgement or failure signals, sent may be a terminal state. See Terminal states. |
| details object | The action specific attributes of the payment action. |
Payment Action Types for each Payment Types
currently we only support positive pay actions forcheck type payments
| Payment Type | Possible Action Types | Description |
|---|---|---|
check | stop | Send a payment action notification to stop the corresponding check payment. |
issue | Send a payment action notification to issue the corresponding check payment (also known as Positive Pay). This is a notification to the bank that the corresponding check has been printed outside of the bank and should be honored. |
Payment Action State Machine
The diagram below describes the changes and dependencies of the payment action state machine.
When the Payment Action is associated to an actionable of type payment_order, the payment action state is dependent on the state of the Payment Order. For other actionable types, such as expected_payment, the payment action state is not dependent on the state of the EP.
The following abbreviations are used to make rendering the diagram easier:pa is payment_action and po is payment_order. actionable refers to a type of payment that payment actions can be run on, specifically a payment_order.
Terminal states
acknowledged, failed, and cancelled are terminal states. A Payment Action moves from sent to acknowledged or failed only when Modern Treasury receives an acknowledgement or failure signal from the bank. For bank connections where Modern Treasury does not receive acknowledgement or failure signals, sent may be a terminal state: the Payment Action stays in sent and never moves to acknowledged or failed. This is expected behavior and does not mean the action wasn't delivered to the bank.
Actionable State Matrix
Payment Action → Payment Order Status Mapping
The following describes the states of a payment action alongside the possible states for the corresponding actionable
| Payment Action Status | Payment Order Status |
|---|---|
pending | pending,needs_approval,approvedprocessing |
processable | sent |
processing | sent |
sent | sent,stopped 1 |
acknowledged | stoppedcompleted |
failed | sent,completed |
cancelled | failed,cancelled |
stopped as soon as the stop Payment Action is sent, without waiting for a bank acknowledgement file. In these cases, the Payment Action can remain in sent (never reaching acknowledged) while the Payment Order is already stopped. This is expected behavior: the Payment Order's terminal state does not depend on receiving an acknowledgement because there is no acknowledgement file to wait for.