Skip to main content
Find paykeys with an expiration date that needs attention or a block that may be recoverable. Use the results to identify affected customers and plan the required bank-connection follow-up.

​
Before you begin

For marketplace integrations, paykeys belong to the platform. These results cover platform-owned paykeys. The selected acting account identifies the local database context used throughout this workflow.

​
Run the workflow

1

Confirm the account and environment

Check runtime_context.environment, runtime_context.integration_type, and runtime_context.acting_account. For SaaS or marketplace, select the account if needed and check again:
2

Refresh paykeys

Confirm a sync_complete event and a final sync_summary with success: 1, warned: 0, and errored: 0. Review any sync_warning or sync_anomaly before using the list. Those findings can accompany exit code zero.
3

Find expiration and block issues

The report includes expired paykeys, paykeys with 14 or fewer whole days remaining, and other blocked paykeys marked eligible for unblocking. Change the positive --days value to use a different planning window.
4

Inspect each paykey's current details

Replace PAYKEY_ID with an id from the report. Check the current status, expiration date when present, customer association, and unblocking eligibility before choosing the follow-up.

​
Interpret the results

The result contains window_days, count, and a paykeys array. Each item’s reason explains why it was included: Items are ordered by those reasons, then by days_to_expiry. An expiration reason takes precedence when a paykey also has a recoverable block, so read status and unblock_eligible alongside reason. expires_at applies to certain paykeys. For an item included because of a block, interpret days_to_expiry only when it has a valid expires_at; a missing date can leave the numeric field at zero. Use the current paykey status to determine usability, including for paykeys outside this report’s expiration and block criteria.

​
Complete the investigation

Record the paykey ID, customer ID, reason, and follow-up date. For expiration, identify the required bank-connection update for that customer’s connection method. For a recoverable block, follow the prerequisites in the paykey management guide, including the customer’s required bank approval before unblocking. Refresh the records after the update to confirm the result.