Sandbox Testing Guide

This guide details how to use Balad's sandbox environment to simulate transaction flows, validate your API integration, and test various outcomes, including detailed failure reasons.

💡

Sandbox responses are predefined and do not impact real balances.

Walkthrough — Simulating a Cash Transaction with Compliance Suspension

This example walks through suffix 103, which simulates a compliance hold that ultimately resolves successfully.

Create the Transaction

Navigate to the Create Transaction endpoint.
Set receiver_contact_no to a value ending in 103
Send the request.

{
"transaction_type": 1,
"remitter_reference_no": "{{refNo}}",
"sender_first_name": "SHOHAIB KHAN",
"sender_last_name": "MOHAMMAD",
"sender_address": "KUWAIT ROAD KUWAIT",
"sender_dateofbirth": "10-May-1980",
"sender_identity": 2,
"sender_identity_no": "PK12255100",
"sender_identity_expiry_date": "23-Jul-2027",
"sender_nationality": "EG",
"sender_country_code": "KW",
"sender_contact_no": "96539053100",
"receiver_first_name": "Mohammad Faisal Rashid",
"receiver_last_name": "Mustafa",
"receiver_address": "EGYPT",
"receiver_identity_type": 2,
"receiver_nationality": "EG",
"receiver_contact_no": "01222222103",   // suffix 103 triggers this flow
"sending_currency_code": "EGP",
"amount": "5800",
"account_no": "01234323456",
"receiver_bank_code": "BDC",
"source_of_remittance": "001",
"purpose": "002"
}

Monitor Initial Status

The transaction moves to Bank Processing, then into Bank Compliance Suspended (status 16).

Simulate Approval via Dashboard

Open the Balad Dashboard and locate the transaction.
Use the simulation controls to trigger the compliance approval and continue processing.

Confirm Final State

After approval, the transaction follows this lifecycle:

Created → Bank Processing → Bank Compliance Suspended → Ready for Pickup → Transferred

Verify the final status using the Get Transaction Status endpoint or by monitoring your Webhook Payload.

Account & Wallet Transaction Flows

Apply the suffix to the account_no field. Any transaction not using a listed suffix follows the Default flow automatically.

Suffix	Transaction Flow	Failure Category	Failure Code	Failure Message
Default	Created → Bank Processing → Transferred	—	—	—
101	Created → Failed	`TECH_FAIL`	`TECH_FAL_001`	Technical issue, transaction processing failed
102	Created → Bank Processing → Bank Compliance Suspended → Bank Compliance Rejected	`COMPLIANCE_RESTRICTION`	`CMP_001`	Rejected due to AML / sanctions screening
103	Created → Bank Processing → Bank Compliance Suspended → Transferred	—	—	—
104	Created → Bank Processing → Transferred To ACH → Third Party Rejected	`BEN_BANK_RESTRICTION`	`BEN_BNK_001`	Beneficiary bank is temporarily unavailable
105	Created → Bank Processing → Transferred To ACH → Transferred	—	—	—
106	Created → Bank Processing → Bank Rejected	`INVALID_ACCOUNT`	`ACC_004`	Invalid account format / wrong account length
107	Created → Bank Processing → Bank Rejected	`MISC`	`MSC_001`	Generic bank rejection / unspecified error

Cash Transaction Flows

Apply the suffix to the receiver_contact_no field. Any transaction not using a listed suffix follows the Default flow automatically.

Suffix	Transaction Flow	Failure Category	Failure Code	Failure Message
Default	Created → Bank Processing → Ready for Pickup → Transferred	—	—	—
101	Created → Failed	`TECH_FAIL`	`TECH_FAL_001`	Technical issue, transaction processing failed
102	Created → Bank Processing → Bank Compliance Suspended → Bank Compliance Rejected	`COMPLIANCE_RESTRICTION`	`CMP_001`	Rejected due to AML / sanctions screening
103	Created → Bank Processing → Bank Compliance Suspended → Ready For Pickup → Transferred	—	—	—
104	Created → Bank Processing → Ready for Pickup → Returned	`RETURNED`	`RTN_001`	Transaction expired and is automatically returned
105	Created → Bank Processing → Ready for Pickup → Canceled	`CANCELLED`	`CNL_001`	Transaction cancelled

Compliance Review Simulation

To trigger Balad's AML compliance review, set sender_first_name or receiver_first_name to Ahmed Hassan in your request payload.

The transaction will enter Balad Compliance Suspended status and remain pending until reviewed. The support team can approve or reject it manually via the Balad Dashboard.

The two payloads below show both trigger positions. The fields marked with a comment are the ones that activate the compliance check.

Ahmed Hassan as Sender

Ahmed Hassan as Receiver

{
  "transaction_type": 1,
  "remitter_reference_no": "{{refNo}}",
  "sender_first_name": "Ahmed Hassan",        // triggers compliance review
  "sender_last_name": "",
  "sender_address": "KUWAIT ROAD KUWAIT",
  "sender_dateofbirth": "10-May-1980",
  "sender_identity": 2,
  "sender_identity_no": "PK12255100",
  "sender_identity_expiry_date": "23-Jul-2027",
  "sender_nationality": "EG",
  "sender_country_code": "KW",
  "sender_contact_no": "96539053100",
  "receiver_first_name": "Mohammad Faisal Rashid",
  "receiver_last_name": "Mustafa",
  "receiver_address": "EGYPT",
  "receiver_identity_type": 2,
  "receiver_nationality": "EG",
  "receiver_contact_no": "01141119177",
  "sending_currency_code": "EGP",
  "amount": "5800",
  "account_no": "01234323456",
  "receiver_bank_code": "BDC",
  "source_of_remittance": "001",
  "purpose": "002"
}

Account Number Validation

By default, Sandbox accepts any account number format without validation, making it easy to get started.

To simulate an invalid account number response, use the CIB bank code:

Set receiver_bank_code to CIB

Use an account_no with an invalid length (e.g., 3 digits)

The API will return a validation error

Example Error Response:

{
    "data": null,
    "errors": [
        {
            "code": 10,
            "message": "Invalid Input",
            "field": "account_no",
            "additional_info": "The beneficiary account number is invalid"
        }
    ]
}

Sandbox Testing Guide

Walkthrough — Simulating a Cash Transaction with Compliance Suspension#

Account & Wallet Transaction Flows#

Cash Transaction Flows#

Compliance Review Simulation#

Account Number Validation#

Walkthrough — Simulating a Cash Transaction with Compliance Suspension

Account & Wallet Transaction Flows

Cash Transaction Flows

Compliance Review Simulation

Account Number Validation