Recipients List
CertifiedList Mercury recipients
Recipients List
List Mercury recipients
Retrieve payment recipients from Mercury with automatic cursor-based pagination. Notice: recipient records contain sensitive banking information such as account and routing numbers, IBANs, and presigned attachment URLs. This information is returned in output records for workflow consumption but is never logged.
type: io.kestra.plugin.mercury.recipients.ListExamples
List all Mercury recipients into memory
id: list_mercury_recipients
namespace: company.team
tasks:
- id: list_recipients
type: io.kestra.plugin.mercury.recipients.List
apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
fetchType: FETCH
Stream all Mercury recipients to internal storage
id: store_mercury_recipients
namespace: company.team
tasks:
- id: store_recipients
type: io.kestra.plugin.mercury.recipients.List
apiToken: "{{ secret('MERCURY_API_TOKEN') }}"
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
apiToken *string
Mercury API token
API token for authentication with the Mercury API.
assets
Assets this task consumes as inputs or produces as outputs, for lineage tracking and the asset graph (Enterprise Edition). A flow declaring this property on a task is rejected in the open-source edition.
io.kestra.core.models.assets.AssetsDeclaration
IGNOREFAILWARNAsset failure behavior
Behavior applied to the task state when a declared asset fails to render, emit, or be persisted (e.g. a lock conflict): FAIL escalates it to FAILED, WARN (default) warns it if it would otherwise succeed, IGNORE leaves the state untouched.
Whether to auto-register assets referenced dynamically at runtime that are not statically declared in inputs or outputs.
The assets consumed as inputs.
io.kestra.core.models.assets.AssetIdentifier
1The assets produced as outputs.
io.kestra.plugin.ee.assets.Dataset
1150{}1150io.kestra.plugin.ee.assets.File
1150{}1150io.kestra.plugin.ee.assets.Table
1150{}1150io.kestra.plugin.ee.assets.VM
1150{}1150io.kestra.core.models.assets.External
1150{}1150io.kestra.core.models.assets.Custom
11501Custom asset type
{}1150baseUrl string
https://api.mercury.com/api/v1Mercury 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
FETCHSTOREFETCHFETCH_ONENONEFetch mode
Controls how results are returned: FETCH to return all rows in memory, FETCH_ONE for the first row, STORE to stream records as ION into internal storage, or NONE to skip collecting outputs.
limit integerstring
1000Results per page
Maximum number of recipients to return per page. Minimum 1, maximum 1000. Default is 1000.
order string
ASCDESCSort order
Sort order of the returned records. Allowed values: ASC or DESC. Defaults to ASC for accounts, cards, and recipients; defaults to DESC for statements.
pageCap integerstring
100Maximum pages to retrieve
Safety cap on the number of pages fetched during pagination. Minimum 1. Default is 100.
Outputs
row
The first recipient fetched
The first recipient retrieved. Only populated when fetchType is FETCH_ONE.
io.kestra.plugin.mercury.model.Recipient
Recipient address
Primary postal address of the recipient including recipient name.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Recipient attachments
List of uploaded tax documents and verification files associated with this recipient. Contains presigned download URLs valid for 12 hours; never log.
io.kestra.plugin.mercury.model.Recipient-Attachment
Attachment file name
Original name of the uploaded attachment file.
Tax form type
Type of tax form uploaded, if applicable. Possible values: w9, w8BEN, w8BENE, unknown.
date-timeUploaded at timestamp
Timestamp when the attachment was uploaded.
Download URL
Presigned URL to download the attachment. Valid for 12 hours. Contains sensitive download tokens; never log this value.
Check delivery information
Postal address where physical checks are delivered.
io.kestra.plugin.mercury.model.Recipient-CheckInfo
Check delivery address
The recipient postal address where physical checks are mailed.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Contact email
Primary contact email address for the recipient.
date-timeDate last paid
Timestamp when the most recent payment was dispatched to this recipient.
Default address
Default postal address of the recipient.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Default payment method
Default method used for payments to this recipient. Possible values: ach, check, domesticWire, internationalWire, realTimePayment.
Domestic wire routing information
Bank routing details for domestic Fedwire payments. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Electronic routing information
Bank routing details for ACH payments, including account and routing numbers. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Recipient emails
List of notification email addresses associated with the recipient.
Recipient ID
The unique identifier (UUID) for this payment recipient.
International wire routing information
Bank routing details for international SWIFT/wire transfers, including IBAN, SWIFT code, and country-specific data. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-InternationalWireRouting
Beneficiary bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Beneficiary bank details
Bank name, city, state, and country associated with the SWIFT code.
io.kestra.plugin.mercury.model.Recipient-BankDetails
Bank city and state
City and state or province of the financial institution.
Bank country code
Two-letter ISO 3166-1 alpha-2 country code of the financial institution.
Bank name
Name of the financial institution associated with the SWIFT code.
Correspondent bank information
Details of the intermediary or correspondent bank, if required for routing.
io.kestra.plugin.mercury.model.Recipient-CorrespondentBank
Correspondent bank name
Name of the intermediary or correspondent bank.
Correspondent routing number
Routing or transit number of the correspondent bank.
Correspondent SWIFT code
SWIFT/BIC code of the correspondent bank.
Country-specific banking details
Generic key-value map containing country-specific payment routing fields (e.g., IFSC for India, BSB for Australia, transit/bank code for Canada, legal ID for Brazil/Chile/Colombia).
Bank contact email address
Contact email for the recipient bank.
International bank account number
International Bank Account Number (IBAN) for the recipient.
Bank contact phone number
Contact telephone number for the recipient bank.
SWIFT or BIC code
Society for Worldwide Interbank Financial Telecommunication (SWIFT) or Business Identifier Code (BIC).
Invite ID
Identifier slug of the recipient onboarding invite, if created via recipient invitation.
Is business recipient
Whether this recipient is registered as a business entity rather than an individual.
Recipient name
Legal or commercial name of the recipient individual or organization.
Recipient nickname
Optional user-assigned nickname or alias for the recipient.
Real-time payment routing information
Bank routing details for The Clearing House Real-Time Payments (RTP). Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Recipient status
Lifecycle status of the recipient. Possible values: active, deleted.
rows array
The recipients fetched
List of retrieved recipients. Only populated when fetchType is FETCH.
io.kestra.plugin.mercury.model.Recipient
Recipient address
Primary postal address of the recipient including recipient name.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Recipient attachments
List of uploaded tax documents and verification files associated with this recipient. Contains presigned download URLs valid for 12 hours; never log.
io.kestra.plugin.mercury.model.Recipient-Attachment
Attachment file name
Original name of the uploaded attachment file.
Tax form type
Type of tax form uploaded, if applicable. Possible values: w9, w8BEN, w8BENE, unknown.
date-timeUploaded at timestamp
Timestamp when the attachment was uploaded.
Download URL
Presigned URL to download the attachment. Valid for 12 hours. Contains sensitive download tokens; never log this value.
Check delivery information
Postal address where physical checks are delivered.
io.kestra.plugin.mercury.model.Recipient-CheckInfo
Check delivery address
The recipient postal address where physical checks are mailed.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Contact email
Primary contact email address for the recipient.
date-timeDate last paid
Timestamp when the most recent payment was dispatched to this recipient.
Default address
Default postal address of the recipient.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Default payment method
Default method used for payments to this recipient. Possible values: ach, check, domesticWire, internationalWire, realTimePayment.
Domestic wire routing information
Bank routing details for domestic Fedwire payments. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Electronic routing information
Bank routing details for ACH payments, including account and routing numbers. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Recipient emails
List of notification email addresses associated with the recipient.
Recipient ID
The unique identifier (UUID) for this payment recipient.
International wire routing information
Bank routing details for international SWIFT/wire transfers, including IBAN, SWIFT code, and country-specific data. Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-InternationalWireRouting
Beneficiary bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Beneficiary bank details
Bank name, city, state, and country associated with the SWIFT code.
io.kestra.plugin.mercury.model.Recipient-BankDetails
Bank city and state
City and state or province of the financial institution.
Bank country code
Two-letter ISO 3166-1 alpha-2 country code of the financial institution.
Bank name
Name of the financial institution associated with the SWIFT code.
Correspondent bank information
Details of the intermediary or correspondent bank, if required for routing.
io.kestra.plugin.mercury.model.Recipient-CorrespondentBank
Correspondent bank name
Name of the intermediary or correspondent bank.
Correspondent routing number
Routing or transit number of the correspondent bank.
Correspondent SWIFT code
SWIFT/BIC code of the correspondent bank.
Country-specific banking details
Generic key-value map containing country-specific payment routing fields (e.g., IFSC for India, BSB for Australia, transit/bank code for Canada, legal ID for Brazil/Chile/Colombia).
Bank contact email address
Contact email for the recipient bank.
International bank account number
International Bank Account Number (IBAN) for the recipient.
Bank contact phone number
Contact telephone number for the recipient bank.
SWIFT or BIC code
Society for Worldwide Interbank Financial Telecommunication (SWIFT) or Business Identifier Code (BIC).
Invite ID
Identifier slug of the recipient onboarding invite, if created via recipient invitation.
Is business recipient
Whether this recipient is registered as a business entity rather than an individual.
Recipient name
Legal or commercial name of the recipient individual or organization.
Recipient nickname
Optional user-assigned nickname or alias for the recipient.
Real-time payment routing information
Bank routing details for The Clearing House Real-Time Payments (RTP). Sensitive banking details; never log.
io.kestra.plugin.mercury.model.Recipient-BankRouting
Account number
Bank account number for ACH, domestic wire or real-time payment (RTP) transfers.
Bank address
Postal address of the recipient financial institution.
io.kestra.plugin.mercury.model.Recipient-Address
Address line 1
Primary street address line.
Address line 2
Secondary street address line (apartment, suite, unit, etc.).
City
City of the address.
Country code
Two-letter ISO 3166-1 alpha-2 country code.
Address name
Name associated with this address, if present.
Postal code
Postal or ZIP code.
Region
State, province, or region code.
Bank name
Name of the recipient financial institution.
Electronic account type
Account classification, set for ACH routing only. Allowed values: businessChecking, businessSavings, personalChecking, personalSavings, businessGeneralLedger, personalGeneralLedger, businessLoan, personalLoan.
Routing number
Nine-digit ABA routing transit number.
Recipient status
Lifecycle status of the recipient. Possible values: active, deleted.
size integer
The total number of recipients returned
For FETCH this matches the size of rows, for FETCH_ONE 0 or 1, for STORE the count of stored records, and 0 for NONE.
uri string
uriURI of stored results
The URI of the file containing ION-formatted records in internal storage. Only populated when fetchType is STORE.
