Egypt Bank Transfer Payout Testing
This guide explains how to test payouts to Egyptian bank accounts in the sandbox environment.
Overview
When testing payouts to Egyptian bank accounts in the sandbox environment, you can test your integration’s error handling, retry logic, and different payout states. The sandbox environment will process requests and return appropriate responses based on the transaction details you provide.
Account Number Format
Egyptian bank accounts can be provided in either:
- Standard account number format (e.g.,
100045022697) - IBAN (International Bank Account Number) format (e.g.,
EG550019000510000000000000010)
The API will validate the account number format. IBAN format is recommended for international compatibility.
Sandbox Testing Overview
The sandbox environment allows you to simulate different transaction outcomes by using specific suffixes in the account number. This enables you to test various transaction flows safely without impacting real balances.
How It Works:
- For bank account transactions, use test suffixes in the
accountNumberfield - Each suffix (101, 104-106) triggers a specific predefined transaction flow
- If your account number doesn’t end with 101, 104, 105, or 106, the system will automatically follow the default successful flow
Important: Sandbox responses are predefined and do not impact real balances.
Note: This integration only supports bank account transactions.
Account Transaction Flows
The following table shows how different account number suffixes trigger specific transaction flows in the sandbox:
Note: The default flow applies to any account number that doesn’t end with 101, 104, 105, or 106. This means successful transactions can use any valid account number without a special suffix.
Usage Examples
Minimum Required Fields
Here is an example of a payout request with the minimum required fields:
Note:
amountis specified in minor units (e.g.,5000= 50.00 EGP)currencyshould beEGPfor Egyptian PoundpaymentLocationandrecipient.countryuse 3-letter ISO country codes (e.g.,EGY)
Testing Successful Transfer (Default Flow)
Use any valid Egyptian account number (without a special suffix) to test a successful payout. The transaction will follow the default flow: Created → In Progress → Transferred.
Expected Result:
- Status code:
200 - Success:
true - Message:
"Submitted successfully" - Payout state:
{ type: "pending" } - Transaction flow: Created → In Progress → Transferred
Testing Failed Transaction (Suffix 101)
Use an account number ending in 101 to simulate a failed transaction:
Expected Result:
- Transaction flow: Created → Failed
Testing Third Party Rejection (Suffix 104)
Use an account number ending in 104 to simulate a third party rejection:
Expected Result:
- Transaction flow: Created → In Progress → Sent to Third Party → Third Party Rejected
Testing Third Party Transfer (Suffix 105)
Use an account number ending in 105 to simulate a successful third party transfer:
Expected Result:
- Transaction flow: Created → In Progress → Sent to Third Party → Transferred
Testing Bank Rejection (Suffix 106)
Use an account number ending in 106 to simulate a bank rejection:
Expected Result:
- Transaction flow: Created → In Progress → Bank Rejected
Testing Invalid Account Format
Use an invalid account number format to test validation:
Expected Result:
- Error code:
DOWNSTREAM_ERROR - Error message includes:
"Invalid Egyptian IBAN format. Please enter a valid IBAN." - The error response will include:
code: Numeric error code (e.g.,10)message: Error message (e.g.,"Invalid Input")field: Field name that caused the error (e.g.,"account_no")additional_info: Additional error details
Response Structure
Successful Response
When a payout is successfully submitted, you will receive:
Error Response
When a payout fails, you will receive an error with the following structure:
The error message contains a JSON string with detailed error information from the API, including:
code: Numeric error codemessage: Error message descriptionfield: Field name that caused the error (if applicable)additional_info: Additional error details
Required Fields
Request Fields
Required Top-Level Fields:
merchantId: Your merchant identifiermerchantReference: Unique reference for this payout (UUID recommended)amount: Amount in minor units (e.g.,5000= 50.00 EGP)currency: Currency code (useEGPfor Egyptian Pound)paymentMethodId: Set to"banktransfer"paymentLocation: 3-letter ISO country code (use"EGY"for Egypt)attributes: Can be an empty object{}or contain additional attributes
Required Recipient Fields:
recipient.type: Set to"bank_account"recipient.accountNumber: Bank account number (standard format or IBAN)recipient.bankCode: Egyptian bank code (e.g.,"CIB","BDC")recipient.accountHolderName: Name of the account holderrecipient.country: 3-letter ISO country code (use"EGY"for Egypt)
Required Sender Fields:
sender.fullName: Full name of the sendersender.phoneNumber: Contact number (e.g., “+27123456789”)sender.email: Email addresssender.country: Sender’s country name (e.g., “Egypt”)sender.countryCode: Sender’s country code (ISO Alpha-3, e.g., “EGY”)sender.senderAddress: Physical addresssender.dateOfBirth: Date of birth (format: “DD-MMM-YYYY”, e.g., “01-Jan-1990”)sender.identity: Identity type (e.g., “1”)sender.identityNumber: Identity document numbersender.identityExpiryDate: Identity expiry date (format: “DD-MMM-YYYY”, e.g., “01-Jan-2030”)sender.nationality: Nationality code (e.g., “ZA”)sender.jobDescription: Job descriptionsender.employerName: Employer name
Important Notes
-
Sandbox Environment Only: The sandbox environment uses the sandbox API. Production payouts will use real bank account numbers and process actual transactions.
-
Account Number Format: The API accepts both standard account numbers and IBAN format. Invalid formats will be rejected with a clear error message. IBAN format is recommended for international compatibility.
-
Payout Status: After submission, payouts will have a
pendingstate. The actual payout status will be updated via webhooks as the transaction is processed through the various lifecycle stages. -
Error Handling: Failed payout scenarios will return appropriate error messages and status codes from the API. Error responses include detailed information about what went wrong.
-
Bank Codes: Ensure you use valid Egyptian bank codes (e.g.,
CIB,BDC). Contact your account manager for a list of supported bank codes. -
Sandbox Behavior: The sandbox will process requests and return responses based on the API behavior. Different error scenarios may occur based on the transaction details, amounts, or other factors as determined by the sandbox environment.
-
Amount Format: Amounts are specified in minor units. For EGP,
5000represents 50.00 EGP (2 decimal places). -
Country Codes: Use 3-letter ISO country codes (e.g.,
EGYfor Egypt) forpaymentLocationandrecipient.country. -
Transaction Lifecycle: Use the account number suffixes (101, 104-106) to test different transaction flows. Monitor transactions through webhooks or by checking transaction status to see the complete lifecycle.
Testing Best Practices
-
Test Happy Path First: Start by testing successful transfers with valid account numbers (without special suffixes) to ensure your integration works correctly.
-
Test Error Scenarios: Use suffixes 101, 104, and 106 to test various failure scenarios and ensure your application handles them gracefully.
-
Monitor Webhook Events: Ensure your webhook handlers correctly process status updates for all transaction lifecycle stages (Created, In Progress, Sent to Third Party, Transferred, Failed, Bank Rejected, etc.).
-
Validate Required Fields: Ensure all required sender fields are provided to avoid validation errors.
-
Test Different Scenarios: Test with different amounts, currencies, and recipient details to understand how the sandbox responds to various scenarios.
-
Use Correct Currency: Always use
EGPfor Egyptian Pound payouts. -
Monitor Transaction Status: Use the transaction status endpoint to track transactions through their complete lifecycle, especially when testing third-party scenarios.
Next Steps
Once you’ve completed testing in the sandbox environment, contact your account manager to enable production payouts. Production transactions will use real bank account numbers and process actual funds transfers.
.svg){kind=logo}