Funds coverage

Funds coverage lets you configure one financial product—such as a savings account, loan, or credit card—to act as a fallback funding source for another product when there is insufficient balance or a payment failure. A common use case is overdraft protection, where funds are automatically pulled from a designated source to prevent transaction declines.

You can define multiple coverage sources, control their priority, and enable or disable them as needed. The service is designed to support additional product types over time without changing how coverage is executed.

💡

Note

Funds coverage is available only for overdraft protection and uses the savings balance as the funding source to cover the overdraft.

How funds coverage works

When a covered account does not have enough available balance to complete a transaction, coverage is applied automatically using your configured sources.

With fund coverage, you can:

• Register which products are allowed to act as fallback sources
• Assign a priority order to each coverage source
• Enable or disable individual sources
• Allow fallback attempts across multiple sources until the shortfall is covered or no options remain

When a shortfall occurs, you select the highest‑priority active source and a funds movement is executed to credit the covered account so the transaction can proceed.

Configuring coverage sources

You can configure coverage relationships using the funds coverage API.

Endpoints

Manage coverage configurations using the following endpoints. Refer to each endpoint for detailed field descriptions.

Example configuration

{
  "protectionSources": [
    {
      "covered": "overdraft",
      "sources": [
        {
          "type": "savings_account",
          "id": "123456",
          "processing_code": 7000,
          "hierarchy": 1,
          "active": true
        },
        {
          "type": "loan",
          "id": "LN789",
          "processing_code": 789100,
          "hierarchy": 2,
          "active": true
        }
      ]
    }
  ]
}

In this example, you configure two coverage sources for an overdraft: a savings account and a loan, with the savings account set as the primary source. If the savings account does not have sufficient funds to cover the overdraft, coverage automatically falls back to the loan.

Business rules

When you configure coverage sources, the following rules are enforced.

• Coverage sources must exist, belong to the customer, and meet eligibility criteria.
• Each source must have a unique hierarchy value; gaps are allowed if intentional.
• A product cannot act as a coverage source for itself.
• You can control availability using the active flag.
• You must include all required fields in your request.
• Errors are returned for invalid IDs, unauthorized relationships, duplicate hierarchy values, or circular references.

Operational flow

Processing code setup

Before coverage can be executed, you must configure a processing code that defines how funds move between products. Use the Create balance configuration endpoint to create a processing code.

Depending on your setup:

• If the coverage source and covered account belong to the same account holder, the processing code typically debits the savings account balance and credits the available balance. For example, using a savings account as coverage source for overdraft protection.
• If the accounts belong to different customers within the same organization, you must specify both the impacted account and the counterpart account.

Note that you are responsible for creating processing codes and balance configurations. Refer to these examples.

Use the same account as overdraft protection source

{
  "id": "d567a7ef-447c-467a-90ee-79584f055436",
  "account_id": 13409,
  "configs": [
    {
      "scenarios": [
        {
          "condition": {
            "type": "default",
            "amount_to_check_balance": "amount",
            "order": 1
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "consider": [
              "AvailableSavingsAccountLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "never"
          }
        }
      ],
      "filters": {
        "currency_code": "",
        "account_type": "",
        "mcc": null,
        "processing_codes": [
          "{processing_code_value}"
        ],
        "min_installments": 0,
        "max_installments": 0
      },
      "is_active": true
    }
  ]
}

In this example, account ID 13409 is both the impacted account and the overdraft protection source. If a shortfall or overdraft occurs on account 13409, the Pismo platform uses the available savings balance in that same account to cover it. For more information about impacted and counterpart accounts, refer to Create balance configuration and Balance configuration use cases.

Use different accounts as overdraft protection source

{
  "id": "d567a7ef-447c-467a-90ee-79584f055436",
  "account_id": 13409,
  "configs": [
    {
      "scenarios": [
        {
          "condition": {
            "type": "default",
            "amount_to_check_balance": "amount",
            "order": 1
          },
          "result": {
            "impact": [
              "AvailableCreditLimit"
            ],
            "consider": [
              "AvailableSavingsAccountLimit"
            ],
            "amount": "contract_amount",
            "amount_consider": "principal_amount",
            "reset_limit": "never",
            "impact_account": {
              "account_id": 123456
            },
            "counterpart_account": {
              "account_id": 789456,
              "processing_code": "000000000"
            }
          }
        }
      ],
      "filters": {
        "currency_code": "",
        "account_type": "",
        "mcc": null,
        "processing_codes": [
          "000000000"
        ],
        "min_installments": 0,
        "max_installments": 0
      },
      "is_active": true
    }
  ]
}

When the impacted and counterpart accounts belong to different account holders, you must specify both account IDs in the API call. In this example, account 123456 is the impacted account, and account 789456 is the counterpart account. If an overdraft occurs, the Pismo platform uses the counterpart account as the protection source to cover the impacted account.

Coverage execution during an event

During an overdraft or balance shortfall, the Pismo platform performs the following actions.

• Verifies that coverage is enabled for the account
• Queries the ledger to calculate the exact shortfall amount
• Uses funds coverage to retrieve eligible sources in priority order
• Triggers a funds movement using the configured processing code
• Credits the covered account’s available balance so the transaction can complete

💡

Notes

• If the first source does not fully cover the shortfall, the next active source in the hierarchy is automatically attempted.
• All fund movements follow standard posting rules, ensuring ledger consistency and audibility.

Common error responses

These are the common errors and why they occur.