Transactions TransactionTrigger

Transactions TransactionTrigger
Certified
Trigger execution on new Mercury transactions

Periodically polls the Mercury API for new transactions in a specific bank account, deduplicating records across polling intervals using a lookback window and the namespace KV store.

yaml
type: io.kestra.plugin.mercury.transactions.TransactionTrigger

Examples

Trigger flow execution on new Mercury transactions into memory

yaml
id: trigger_mercury_transactions
namespace: company.team

tasks:
  - id: log_transaction
    type: io.kestra.plugin.core.log.Log
    message: "{{ trigger.size }} new transaction(s), first from {{ trigger.transaction.counterpartyName }} on account {{ trigger.account.id }}"

triggers:
  - id: watch_transactions
    type: io.kestra.plugin.mercury.transactions.TransactionTrigger
    apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
    accountId: "d0e567d8-76a7-11e9-a22d-0b33e9de0755"

Trigger flow execution on new Mercury transactions streamed to storage

yaml
id: trigger_mercury_transactions_store
namespace: company.team

tasks:
  - id: log_stored
    type: io.kestra.plugin.core.log.Log
    message: "Stored transactions URI: {{ trigger.uri }}"

triggers:
  - id: watch_transactions_store
    type: io.kestra.plugin.mercury.transactions.TransactionTrigger
    apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
    accountId: "d0e567d8-76a7-11e9-a22d-0b33e9de0755"
    fetchType: STORE

Installation

Our standard Docker images already include this plugin. If you use a -slim image or another setup, install it with the following command:

kestractl plugins get io.kestra.plugin:plugin-mercury --compatible-for $KESTRA_VERSION

For kestractl, use your Kestra version with --compatible-for, or specify an exact plugin version.

For Kestra CLI, replace LATEST with a specific version or version range to pin the plugin version.

Properties

accountId *string

Account ID

The unique identifier (UUID) of the Mercury account whose transactions to monitor.

apiToken *string

Mercury API token

API token for authentication with the Mercury API.

allowConcurrent boolean

Defaultfalse

Specifies whether a trigger is allowed to start a new execution even if a previous run is still in progress.

baseUrl string

Defaulthttps://api.mercury.com/api/v1

Mercury API base URL

Base URL for the Mercury API. Override for the Mercury sandbox (https://api-sandbox.mercury.com/api/v1). Must use HTTPS, except for loopback hosts (localhost, 127.0.0.1, ::1) during local testing.

fetchType string

DefaultFETCH

Possible Values

STOREFETCHFETCH_ONENONE

Fetch mode

Controls the shape of the output only, every new transaction is fetched and marked as seen: FETCH to return all rows in memory, FETCH_ONE for the first row only, STORE to stream records as ION into internal storage, or NONE to skip collecting outputs. Default is FETCH.

interval string

DefaultPT5M

Formatduration

Polling interval

The interval between consecutive polls. Default is PT5M (5 minutes).

limit integerstring

Default1000

Results per page

Maximum number of transactions to return per page. Minimum 1, maximum 1000. Default is 1000.

lookback string

DefaultPT24H

Lookback window

Safety lookback duration for overlapping polls to catch delayed or out-of-order transactions. Minimum 1 minute. Default is PT24H (24 hours).

pageCap integerstring

Default100

Maximum pages to retrieve

Safety cap on the number of pages fetched during pagination. Minimum 1. Default is 100.

search string

Search term filter

Search term to filter transactions by description, note, recipient memo, or counterparty name.

status string

Possible Values

PENDINGSENTCANCELLEDFAILEDREVERSEDBLOCKED

Transaction status filter

Filter transactions by status: PENDING, SENT, CANCELLED, FAILED, REVERSED, or BLOCKED.

stopAfter array

SubTypestring

Possible Values

CREATEDSUBMITTEDRUNNINGPAUSEDRESTARTEDKILLINGSUCCESSWARNINGFAILEDKILLEDCANCELLEDQUEUEDRETRYINGRETRIEDSKIPPEDBREAKPOINTRESUBMITTED

List of execution states after which a trigger should be stopped (a.k.a. disabled).

when string

Defaulttrue

A condition that determines whether the trigger should run.

A Pebble expression evaluated at trigger time. The trigger fires only when the expression evaluates to a truthy value (true, a non-empty string, a non-zero number). Use this to gate trigger execution on dynamic runtime values such as execution labels, flow variables, or environment conditions.

Outputs

account

The monitored account

Reference to the monitored Mercury account.

Definitions

io.kestra.plugin.mercury.transactions.TransactionTrigger-AccountRef

idstring

Account ID

The unique identifier (UUID) of the monitored Mercury account.

row

The first new transaction

First new transaction detected in this poll. Only populated when fetchType is FETCH_ONE.

Definitions

io.kestra.plugin.mercury.model.Transaction

accountIdstring

Account ID

The external-facing account identifier for the Mercury account that owns this transaction.

amountnumber

Transaction amount

The amount of the transaction in USD. Can be negative for outgoing payments or fees, and positive for incoming deposits.

attachmentsarray

SubTypeobject

Attachments

File attachments associated with the transaction, such as receipts and invoices.

bankDescriptionstring

Bank description

Bank description text as reported on bank statements.

cardIdstring

Card ID

ID of the card behind this transaction, present on card payments and refunds (debit or credit); null otherwise.

categoryDataobject

Category data

Expense category details for transaction classification.

checkNumberstring

Check number

Check number present for check deposits and mailed checks; null otherwise.

compliantWithReceiptPolicyboolean

Compliant with receipt policy

Whether the transaction complies with the company's receipt policy.

counterpartyIdstring

Counterparty ID

The unique identifier for the counterparty.

counterpartyNamestring

Counterparty name

Name of the counterparty involved in the transaction.

counterpartyNicknamestring

Counterparty nickname

Nickname assigned to the counterparty, if any.

createdAtstring

Formatdate-time

Created at

Timestamp when the transaction record was created, in ISO 8601 UTC format.

creditAccountPeriodIdstring

Credit account period ID

ID of the credit account statement period, if applicable.

currencyExchangeInfoobject

Currency exchange info

Information on currency conversions for international transactions.

dashboardLinkstring

Dashboard link

The direct URL to view the transaction in the Mercury dashboard.

detailsobject

Transaction details

Transaction method details such as card info, electronic routing, or wire routing info.

estimatedDeliveryDatestring

Formatdate-time

Estimated delivery date

The estimated delivery timestamp for the transaction, in ISO 8601 UTC format.

externalMemostring

External memo

External memo attached to the payment.

failedAtstring

Formatdate-time

Failed at

Timestamp when the transaction failed, if applicable, in ISO 8601 UTC format.

feeIdstring

Fee ID

ID of the associated fee transaction, if any.

generalLedgerCodeNamestring

General ledger code name

Deprecated GL code name. Preserved for backwards compatibility.

glAllocationsarray

SubTypeobject

General ledger allocations

GL code allocations assigned via accounting software integrations.

hasGeneratedReceiptboolean

Has generated receipt

Whether a receipt was automatically generated.

idstring

Transaction ID

The unique identifier (UUID) for this transaction.

kindstring

Transaction kind

Kind of transaction, such as outgoingPayment, externalTransfer, internalTransfer, or creditCardTransaction.

merchantobject

Merchant details

Merchant information for card transactions, including MCC, merchant ID, and local currency data.

mercuryCategorystring

Mercury category

High-level merchant category assigned by Mercury.

notestring

User note

Internal user note attached to the transaction.

postedAtstring

Formatdate-time

Posted at

Timestamp when the transaction settled and posted to the ledger, in ISO 8601 UTC format.

reasonForFailurestring

Reason for failure

Description of why the transaction failed, if applicable.

relatedTransactionsarray

SubTypeobject

Related transactions

Related transactions such as refunds, fee reversals, or chargebacks.

requestIdstring

Request ID

ID returned from /account/: id/request-send-money if created via a payment request.

statusstring

Transaction status

Current status of the transaction. Possible values: pending, sent, cancelled, failed, reversed, blocked.

trackingNumberstring

Tracking number

Tracking number for wire, RTP, or ACH payments; null otherwise.

rows array

The new transactions

New transactions detected in this poll. Only populated when fetchType is FETCH.

Definitions

io.kestra.plugin.mercury.model.Transaction

accountIdstring

Account ID

The external-facing account identifier for the Mercury account that owns this transaction.

amountnumber

Transaction amount

The amount of the transaction in USD. Can be negative for outgoing payments or fees, and positive for incoming deposits.

attachmentsarray

SubTypeobject

Attachments

File attachments associated with the transaction, such as receipts and invoices.

bankDescriptionstring

Bank description

Bank description text as reported on bank statements.

cardIdstring

Card ID

ID of the card behind this transaction, present on card payments and refunds (debit or credit); null otherwise.

categoryDataobject

Category data

Expense category details for transaction classification.

checkNumberstring

Check number

Check number present for check deposits and mailed checks; null otherwise.

compliantWithReceiptPolicyboolean

Compliant with receipt policy

Whether the transaction complies with the company's receipt policy.

counterpartyIdstring

Counterparty ID

The unique identifier for the counterparty.

counterpartyNamestring

Counterparty name

Name of the counterparty involved in the transaction.

counterpartyNicknamestring

Counterparty nickname

Nickname assigned to the counterparty, if any.

createdAtstring

Formatdate-time

Created at

Timestamp when the transaction record was created, in ISO 8601 UTC format.

creditAccountPeriodIdstring

Credit account period ID

ID of the credit account statement period, if applicable.

currencyExchangeInfoobject

Currency exchange info

Information on currency conversions for international transactions.

dashboardLinkstring

Dashboard link

The direct URL to view the transaction in the Mercury dashboard.

detailsobject

Transaction details

Transaction method details such as card info, electronic routing, or wire routing info.

estimatedDeliveryDatestring

Formatdate-time

Estimated delivery date

The estimated delivery timestamp for the transaction, in ISO 8601 UTC format.

externalMemostring

External memo

External memo attached to the payment.

failedAtstring

Formatdate-time

Failed at

Timestamp when the transaction failed, if applicable, in ISO 8601 UTC format.

feeIdstring

Fee ID

ID of the associated fee transaction, if any.

generalLedgerCodeNamestring

General ledger code name

Deprecated GL code name. Preserved for backwards compatibility.

glAllocationsarray

SubTypeobject

General ledger allocations

GL code allocations assigned via accounting software integrations.

hasGeneratedReceiptboolean

Has generated receipt

Whether a receipt was automatically generated.

idstring

Transaction ID

The unique identifier (UUID) for this transaction.

kindstring

Transaction kind

Kind of transaction, such as outgoingPayment, externalTransfer, internalTransfer, or creditCardTransaction.

merchantobject

Merchant details

Merchant information for card transactions, including MCC, merchant ID, and local currency data.

mercuryCategorystring

Mercury category

High-level merchant category assigned by Mercury.

notestring

User note

Internal user note attached to the transaction.

postedAtstring

Formatdate-time

Posted at

Timestamp when the transaction settled and posted to the ledger, in ISO 8601 UTC format.

reasonForFailurestring

Reason for failure

Description of why the transaction failed, if applicable.

relatedTransactionsarray

SubTypeobject

Related transactions

Related transactions such as refunds, fee reversals, or chargebacks.

requestIdstring

Request ID

ID returned from /account/: id/request-send-money if created via a payment request.

statusstring

Transaction status

Current status of the transaction. Possible values: pending, sent, cancelled, failed, reversed, blocked.

trackingNumberstring

Tracking number

Tracking number for wire, RTP, or ACH payments; null otherwise.

size integer

Number of new transactions

The number of new transactions detected in this poll (0 for NONE). With FETCH_ONE only the first one is exposed in row, the others are still marked as seen.

transaction

The first new transaction (alias)

First new transaction detected in this poll, populated for FETCH and FETCH_ONE. Use rows to read all of them.

Definitions

io.kestra.plugin.mercury.model.Transaction

accountIdstring

Account ID

The external-facing account identifier for the Mercury account that owns this transaction.

amountnumber

Transaction amount

The amount of the transaction in USD. Can be negative for outgoing payments or fees, and positive for incoming deposits.

attachmentsarray

SubTypeobject

Attachments

File attachments associated with the transaction, such as receipts and invoices.

bankDescriptionstring

Bank description

Bank description text as reported on bank statements.

cardIdstring

Card ID

ID of the card behind this transaction, present on card payments and refunds (debit or credit); null otherwise.

categoryDataobject

Category data

Expense category details for transaction classification.

checkNumberstring

Check number

Check number present for check deposits and mailed checks; null otherwise.

compliantWithReceiptPolicyboolean

Compliant with receipt policy

Whether the transaction complies with the company's receipt policy.

counterpartyIdstring

Counterparty ID

The unique identifier for the counterparty.

counterpartyNamestring

Counterparty name

Name of the counterparty involved in the transaction.

counterpartyNicknamestring

Counterparty nickname

Nickname assigned to the counterparty, if any.

createdAtstring

Formatdate-time

Created at

Timestamp when the transaction record was created, in ISO 8601 UTC format.

creditAccountPeriodIdstring

Credit account period ID

ID of the credit account statement period, if applicable.

currencyExchangeInfoobject

Currency exchange info

Information on currency conversions for international transactions.

dashboardLinkstring

Dashboard link

The direct URL to view the transaction in the Mercury dashboard.

detailsobject

Transaction details

Transaction method details such as card info, electronic routing, or wire routing info.

estimatedDeliveryDatestring

Formatdate-time

Estimated delivery date

The estimated delivery timestamp for the transaction, in ISO 8601 UTC format.

externalMemostring

External memo

External memo attached to the payment.

failedAtstring

Formatdate-time

Failed at

Timestamp when the transaction failed, if applicable, in ISO 8601 UTC format.

feeIdstring

Fee ID

ID of the associated fee transaction, if any.

generalLedgerCodeNamestring

General ledger code name

Deprecated GL code name. Preserved for backwards compatibility.

glAllocationsarray

SubTypeobject

General ledger allocations

GL code allocations assigned via accounting software integrations.

hasGeneratedReceiptboolean

Has generated receipt

Whether a receipt was automatically generated.

idstring

Transaction ID

The unique identifier (UUID) for this transaction.

kindstring

Transaction kind

Kind of transaction, such as outgoingPayment, externalTransfer, internalTransfer, or creditCardTransaction.

merchantobject

Merchant details

Merchant information for card transactions, including MCC, merchant ID, and local currency data.

mercuryCategorystring

Mercury category

High-level merchant category assigned by Mercury.

notestring

User note

Internal user note attached to the transaction.

postedAtstring

Formatdate-time

Posted at

Timestamp when the transaction settled and posted to the ledger, in ISO 8601 UTC format.

reasonForFailurestring

Reason for failure

Description of why the transaction failed, if applicable.

relatedTransactionsarray

SubTypeobject

Related transactions

Related transactions such as refunds, fee reversals, or chargebacks.

requestIdstring

Request ID

ID returned from /account/: id/request-send-money if created via a payment request.

statusstring

Transaction status

Current status of the transaction. Possible values: pending, sent, cancelled, failed, reversed, blocked.

trackingNumberstring

Tracking number

Tracking number for wire, RTP, or ACH payments; null otherwise.

uri string

Formaturi

URI of stored results

The URI of the file containing ION-formatted records in internal storage. Only populated when fetchType is STORE.

Dataform

Tasks that run Dataform data transformations through the Dataform CLI.

Data

Huawei

Huawei plugin for Kestra

CloudDataInfrastructure

Transactions TransactionTriggerCertifiedTrigger execution on new Mercury transactions

Transactions TransactionTrigger

More Plugins in this Category

Dataform

Huawei

Transactions TransactionTrigger
Certified
Trigger execution on new Mercury transactions