Common error codes for Payouts- Merchant facing

Overview

This guide helps diagnose and resolve common issues regarding failed payments to customers. Please escalate your payout error code to [email protected] should you require assistance and troubleshooting. 

Common Failure Scenarios

? CRITICAL - Customer Not Paid

1. Insufficient Funds

Merchant Experience: "My payout failed with an insufficient funds error"

What's Happening: The merchant doesn't have enough money in their Peach account to cover all the payouts.

Result Codes You'll See:

• 2900.002.000 - "Load more funds and try again or try a lower amount"

• 2900.002.001 - "No balance available for your account. Load funds and try again"

• 
  

Support Team Can Resolve: ✅Yes

2. Invalid Customer Bank Details

Merchant Experience: "My payout failed - is there an issue with the bank account details?"

What's Happening: The customer provided incorrect bank account details (wrong account number, branch code, or bank).

Result Codes You'll See:

• 2001.003.109 / 2001.003.116 - "There is no account associated with the account number you entered"

• 2001.002.106 - "There is no account associated with the account number and the bank you entered"

• 
  

Support Team Can Resolve: ✅Yes

3. Customer's Bank Account Issues

Merchant Experience: "The bank details are correct but the payout still failed"

What's Happening: The customer's bank account exists but can't receive funds right now (account frozen, restrictions, etc.).

Result Codes You'll See:

• 2001.002.108 - "The recipient's account cannot receive funds right now. Please ask the recipient to check with their bank"

• 2001.002.115 - "The bank you tried to transfer to is not currently able to receive real-time fund transfers"

Support Team Can Resolve: ⚠️ PARTIALLY

4. Duplicate Payout Attempts

Merchant Experience: "I'm getting an error when trying to create a payout"

What's Happening: Merchant is trying to use the same payout ID that was already used.

Result Code You'll See:

• 2900.003.002 - "Payout IDs provided have already been used"

Support Team Can Resolve: ✅ YES

5. Invalid Input Data

Merchant Experience: "I can't submit my payout - getting validation errors"

What's Happening: The payout request has incorrectly formatted data.

Common Issues:

• Account holder name with special characters

• Branch code not exactly 6 digits  

• Reference with invalid characters

• Amount too small (under R10.00) or too large

• Invalid bank name

Result Code You'll See:

• 2900.003.001 - "Request field(s) missing or invalid"

Support Team Can Resolve: ✅ YES

6. Payout Amount Limits Exceeded

Merchant Experience: "I'm getting result code 2901.002.104 (or 2901.002.105) and it says to contact support" or "My large payout failed with a generic error message"

What's Happening: The payout amount exceeds the maximum allowed for the current time window, but the error message doesn't explain this clearly.

Result Codes You'll See:

• 2901.002.104 - Amount exceeds limits for current time window (merchant sees generic error message)

• 2901.002.105 - Amount exceeds limits for current time window (merchant sees generic error message)

Payout Limits:

• Business Days (Mon-Fri) 00:00-16:00: R5,000,000.00 maximum

• Business Days (Mon-Fri) 16:01-23:59: R250,000.00 maximum  

• Weekends (Sat-Sun) All Day: R250,000.00 maximum

• Public Holidays All Day: R250,000.00 maximum

Support Team Can Resolve: ✅ YES

7. API Request Errors

Merchant Experience: "I'm getting errors when trying to call your API" or "The API is rejecting my requests"

What's Happening: Various API validation or formatting errors in the merchant's integration.

Result Codes You'll See:

• 2900.003.000 - "Path parameter missing or invalid" (wrong payout request ID format)

• 2900.003.003 - "Invalid dates or date range" (date queries outside 3-month window)

• 2900.003.004 - "Include a valid request body and try again" (missing request body)

• 2900.003.005 - "Path parameter missing or invalid" (invalid query parameters)

• 2900.004.000 - "No Payout Request for the Payout Request ID you have provided" (payout request not found)

Support Team Can Resolve: ✅ YES

8. Authentication & Authorization Issues

Merchant Experience: "I can't access the API - getting unauthorized errors"

What's Happening: Problems with merchant authentication tokens or permissions.

Result Codes You'll See:

• 2900.005.000 - "Unauthorised" (invalid/expired token)

• 2900.005.001 - "Unauthorised: Please contact your business administrator" (no permission for this action)

Support Team Can Resolve: ⚠️ PARTIALLY

9. Webhook Notification Issues

Merchant Experience: "I'm not receiving payout status updates" or "My system isn't getting notifications about payout completions"

What's Happening: Our webhook delivery to the merchant's system is failing or not configured properly. This is an internal integration issue.

This requires an escalation to support2peachpayments.com for us to raise to the DEV Team

⚠️ ALWAYS ESCALATE TO SUPPORT TEAM in order for us to raise a query with the DEV Team.

10. System/Technical Errors

Result Codes That Always Need Dev Team:

• 2900.999.999 - "An error has occurred, please contact [email protected]"

• 2900.001.000 - Float service error

• 2900.001.001 - Payout service error  

• 2900.001.002 - Webhook request failed

• 2900.001.003 - Merchant service error

• 2900.001.004 - Merchant deposit reference not found

• 2900.001.005 - Merchant deposit reference not set

• 2900.002.002 - Failed to add to queue

• Any 2901.001.xxx codes (Tyme Bank technical errors)

• Any 2901.999.xxx codes (Tyme Bank unknown errors)

• 2001.001.107 - Technical banking error (escalate immediately)

11. Processing Stuck

Merchant Experience: "My payout has been 'processing' for a long time"

What's Happening: Payout stuck in processing state, likely due to integration issues with banking partner.

Support Team Cannot Resolve: ❌ ESCALATE IMMEDIATELY TO [email protected] in order for us to raise a query with or technical team.

Quick Reference

Payout Status Meanings

• pending = Waiting to be processed

• processing = Currently being processed by bank

• successful = Customer received money ✅

• failed = Payment failed - customer didn't get paid ❌

• reversed = Payment was reversed - money returned to Peach (Please contact Dev team)

When to Escalate Immediately

1. Any technical result codes (2900.999.999, 2900.001.xxx)

2. Payouts stuck in "processing" for >2 hours

3. Multiple merchants reporting similar issues with the same bank

4. Merchant balance/funding issues you can't verify

5. Any result code you're unsure about

Understanding Result Codes and Billing

Result Code Structure

Our result codes follow a specific pattern that determines whether merchants are charged for failed transactions:

Billable Errors (2000-2899)

• 2001.xxx.xxx: Bank validation and processing errors

• These are typically caused by incorrect customer bank details or issues with the customer's bank account

• Merchants are charged for these failures because they stem from merchant/customer-provided information

Unbillable Errors (2900-2999)  

• 2900.xxx.xxx: Internal Peach system errors

• 2901.xxx.xxx: Tyme Bank technical/integration errors

• Merchants are NOT charged for these failures because they're due to technical issues on our side or our banking partner's side

Why This Matters for Support

Understanding billing helps you:

1. Set expectations: Tell merchants whether they'll be charged for the failed transaction

2. Prioritize urgency: Unbillable errors (our fault) should be escalated faster

3. Explain costs: Merchants may ask why they're being charged for failed payouts

Examples by Section

• Invalid Bank Details (2001.xxx.xxx): ✅ Billable - Merchant provided wrong details

• Customer Bank Issues (2001.xxx.xxx): ✅ Billable - Customer's bank problem, not ours

• Insufficient Funds (2900.xxx.xxx): ❌ Unbillable - We should have caught this before processing

• System Errors (2900.xxx.xxx, 2901.xxx.xxx): ❌ Unbillable - Technical issues on our side

• Payout Limits (2901.xxx.xxx): ❌ Unbillable - Our system limitation, not merchant error

• API Validation (2900.xxx.xxx): ❌ Unbillable - Our API should handle these gracefully

• Authentication (2900.xxx.xxx): ❌ Unbillable - System access issues