<?php
/**
 * Merchant ACH status interface. Defines the method that an ACH offsite payment
 * gateway must implement to report the current status of a stored payment account,
 * allowing the locally stored status to be reconciled with the remote gateway.
 *
 * @package blesta
 * @subpackage components.gateways
 * @copyright Copyright (c) 2026, Phillips Data, Inc.
 * @license http://www.blesta.com/license/ The Blesta License Agreement
 * @link http://www.blesta.com/ Blesta
 */
interface MerchantAchStatus
{
    /**
     * Retrieves the current status of an ACH account stored off site. This is used to keep the
     * payment account status stored locally in sync with the remote gateway, for instance when an
     * account was marked active locally but has since been found to require verification
     *
     * @param string $client_reference_id The reference ID for the client on the remote gateway
     * @param string $account_reference_id The reference ID for the stored account on the remote gateway
     * @return string|null The status of the payment account, 'active', 'inactive' or 'unverified',
     *  or null if the status could not be determined, in which case the locally stored status is kept
     */
    public function getAchAccountStatus($client_reference_id, $account_reference_id);
}
