Handling Failed Payments

Failed Payments

Payments can fail for a variety of reasons - we give you visibility into the reason for the failure using the failure_code on the payment object.

Two of the most common reasons for failure include

• insufficient_funds : This indicates a debit attempt failed due to a lack of available funds in the company's bank account. In this case, the company can add additional funds to their bank account and retry.
• account_closed : This indicates a payment failed due to the closure of a bank account. In this case, a new bank account must be created to retry the payment. Refer to Bank Account Verification for additional information.

Retrying Failed Payments

Both failed credit and debit payments can be retried. Note that fetching the Payment object and reading its can_retry field will guide whether a particular payment can be retried.

For debit payments, two options are available:

1. [Recommended] Retrying with a wire payment. Using the use_wire retry method will provide the relevant wiring details so the company can fulfill their debt obligation by sending Check a wire.
2. Retrying with a new or existing bank account. Specifying a new bank_account id will initiate a new debit on the desired bank account.

Warning: Retrying using a new bank account likely results in employees not getting paid on payday due to limitations of the ACH network! After a re-debit attempt is initiated, we must wait 3 banking days to clear the ACH return window (period of time in which the payment could still fail). Additionally, since the debit failed once, there is an additional risk of a subsequent failure. For this reason, we highly recommend using wires to recover from failed debit payments, as they land within a matter of hours rather than days.

For credit payments, retrying is only possible by specifying a new bank account. Retried credit payments can be expected to settle within 1-2 banking days.

Refunding Failed Credit Payments

In some situations, refunding credit payments may be preferable to retrying. Refunding a credit payment means that the company will be refunded for the amount of the employee's net pay with the expectation they will pay the employee off-platform, usually by a check. Refunding a payment will also result in the payment method of the corresponding payroll_item or contractor_payment switching to manual. The net pay funds will be returned to the company's bank account in 1-2 banking days. Given that funds would be returned to the company, we require that the company have funded its payroll in the first place - we won't refund a credit payment associated with an unfunded payroll.

Similar to the can_retry field, we recommend leveraging the Payment object's can_refund field to dictate whether a particular payment is eligible for refund.

Console

Console surfaces Payments as well as the ability to retry or refund payments.

The retry panel shows the available means of retrying - using a wire or a new bank account

After a subsequent wire attempt has been created to recover from the failure, the "View Wire Details" button becomes available

API

Payments and payment attempts can be viewed using the API via the Payment and Payment Attempt objects. You can read or list these objects.

{
    "id": "pyt_vIFHhvyGN47ej1upyIT8",
    "status": "paid",
    "amount": "4522.0400",
    "type": "company_cash_requirement",
    "parent_type": "payroll",
    "parent_id": "pay_ENA4k8LMHbgpV07GLGSv",
    "payment_attempts": [
        {
            "id": "pya_GaeJoEAzbqqc2D9GMfOF",
            "created_at": "2022-02-18T21:32:44.957364Z",
            "expected_completion_date": "2022-02-25",
            "status": "paid",
            "failure_code": null,
            "payment_method": "wire",
            "payment_instrument": null,
            "wire_details": {
                "account_number": "3302826020",
                "routing_number": "121140399",
                "bank_name": "JPMorgan Chase",
                "account_name": "JPM for benefit of CHECK TECHNOLOGIES",
                "account_address": "270 Park Avenue, New York, NY 10017",
                "amount": 4522.04
            }
        },
        {
            "id": "pya_Kgl6ERboridVSfv4XKdT",
            "created_at": "2022-02-18T20:14:40.713837Z",
            "expected_completion_date": "2022-02-23",
            "status": "failed",
            "failure_code": "insufficient_funds",
            "payment_method": "ach",
            "payment_instrument": "bnk_W7hjDGn6sU1d3U8dr9bq",
            "wire_details": null
        }
    ],
    "can_retry": false,
    "can_refund": false,
    "direction": "debit"
}

Additionally, payments can be retried or refunded using the API.