Skip to main content

Stripe Payouts Streamlining Your Withdrawal Process


Handling Failure Payouts.

So you will receive a web hook payout.failed with meta data including reason of failure and codes.


Here's a list of the failure codes and their meanings:

  1. account_closed: The bank account associated with the payout has been closed.
  2. account_frozen: The bank account associated with the payout has been frozen.
  3. bank_account_restricted: The bank account has restrictions on the type or number of payouts allowed, often indicating that it is a savings or non-checking account.
  4. bank_ownership_changed: The destination bank account is no longer valid because its branch has changed ownership.
  5. could_not_process: The bank was unable to process the payout.
  6. debit_not_authorized: Debit transactions are not approved on the bank account. Stripe requires bank accounts to be set up for both credit and debit payouts.
  7. declined: The bank has declined the transfer. It is recommended to contact the bank for further clarification before retrying.
  8. insufficient_funds: The Stripe account has insufficient funds to cover the payout.
  9. invalid_account_number: The routing number appears correct, but the account number is invalid.
  10. incorrect_account_holder_name: The bank has notified Stripe that the bank account holder name on file is incorrect.
  11. incorrect_account_holder_address: The bank has notified Stripe that the bank account holder address on file is incorrect.
  12. incorrect_account_holder_tax_id: The bank has notified Stripe that the bank account holder tax ID on file is incorrect.
  13. invalid_currency: The bank was unable to process the payout due to currency incompatibility. This might occur when the bank account cannot accept payments in the specified currency.
  14. no_account: The bank account details on file are likely incorrect, and no bank account could be located with those details.
  15. unsupported_card: The bank no longer supports payouts to the specified card.

And the structure

  "id": "po_1NTSazHTGgsC5BiiIn54l5Nb",
  "object": "payout",
  "amount": 1100,
  "arrival_date": 1689206400,
  "automatic": true,
  "balance_transaction": "txn_3LZZ3PHTGgsC5Bii0HVQ6XOs",
  "created": 1689266545,
  "currency": "usd",
  "description": "STRIPE PAYOUT",
  "destination": "ba_1NTSazHTGgsC5BiiS52u0ep2",
  "failure_balance_transaction": null,
  "failure_code": null,
  "failure_message": null,
  "livemode": false,
  "metadata": {},
  "method": "standard",
  "original_payout": null,
  "reconciliation_status": "not_applicable",
  "reversed_by": null,
  "source_type": "card",
  "statement_descriptor": null,
  "status": "in_transit",
  "type": "bank_account"

So you will find the payout from your transactions table follow these steps

  1. Notify the User:
    • Inform the user promptly about the failed payout through email or in-app notifications.
    • Clearly explain the reason for the failure, referencing the specific failure code or providing a user-friendly explanation of the issue.
  2. Provide Instructions:
    • Instruct the user to review and correct the inputs or details associated with the failed payout.
    • Clearly communicate what needs to be corrected, such as bank account information, account holder name, or any other relevant details.
    • Offer guidance on how they can update the information within your app.
  3. Update User Interface:
    • Modify the user interface in your app to allow users to easily access and update the necessary information.
    • Provide clear instructions and intuitive design elements to guide users through the correction process.
    • Consider implementing validation checks to ensure that corrected inputs meet the required format and criteria.
  4. Assistance and Support:
    • Offer support channels, such as customer service or help desk, where users can reach out for assistance.
    • Provide prompt responses to user inquiries and be prepared to address any questions or concerns they may have regarding the failed payout.
  5. Retrying the Payout:
    • Once the user has corrected the necessary inputs, you can automatically schedule a retry of the payout at the next payout interval.
    • Initiate the payout using the updated and verified information.
  6. Monitoring and Communication:
    • Continuously monitor the status of retried payouts and keep the user informed of any updates or changes in the payout status.
    • Consider sending email notifications or in-app messages to inform the user about the retry attempt and subsequent status changes.