Testing Scenarios

The Pagamio sandbox environment supports various testing scenarios using predefined test numbers, meter numbers, and biller accounts. Use these values when simulating purchases.

Bill Payment Test Scenario

DSTV Test Account

Test Account Number: 81715524
Product Code: BIL-DST-001

Sample Payload

{
  "productCode": "BIL-DST-001",
  "amount": 150.00,
  "accountNumber": "93888880",
  "paymentMethod": "cash",
  "additionalInfo": {}
}

Expected Response

{
    "transactionId": "e0e7ac02-41b8-4811-93bd-f63da3b89773",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-02T10:49:10.366078607",
    "successful": true,
    "receipt": {
        "amountDue": 97000,
        "accountHolder": "S CHANDAKA",
        "tenderType": "CASH",
        "amount": 7000,
        "serviceProviderFspNumber": "11514",
        "notes": "MultiChoice Call Centre 083 900 3788",
        "aggregator": "BLUE_LABEL",
        "accountNumber": "93888880",
        "vendorName": "Blu Bill Payment",
        "serviceProviderName": " DStv/Multichoice"
    }
}

Electricity Purchase Testing

Test Meter Numbers

000001020001
00001100000
00001000000 (FBE ONLY)
000000000100 (Water Meter Test)
00000100000
00000100100
00000110000
00000100110
00000110100
00200100000
0020110000
00201100000
00000210011
00000130000
00001100000

Standard Electricity Purchase

Example Payload

{
  "productCode": "ELE-FLS-001",
  "amount": 200.00,
  "paymentMethod": "cash",
  "meterNumber": "000001020001",
  "additionalInfo": {}
}

Example Response

{
    "transactionId": "7027adc3-ef49-4a65-8f74-2010d4d3c1a0",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-02T11:08:03.898840162",
    "successful": true,
    "receipt": {
        "amount": 20000,
        "meterNumber": "000001020001",
        "aggregator": "BLUE_LABEL",
        "name": "Mr. William HC Reeds",
        "utility": "City of Tshwane",
        "tokens": [
            {
                "token": "35265582586303340959",
                "tokenDescription": "Electricity Credit",
                "quantity": 61.14,
                "unit": "kWh",
                "free": false
            }
        ],
        "fixedCosts": [
            {
                "description": "STREET LIGHTS"
            }
        ],
        "receiptNumber": "87903/6493"
    }
}

Free Basic Electricity (FBE)

Example Payload

{
  "productCode": "ELE-FLS-002",
  "amount": 0.00,
  "paymentMethod": "cash",
  "meterNumber": "01012345671890",
  "additionalInfo": {}
}

Example Response

{
    "transactionId": "6e80d94b-722d-44e8-930c-24d713b84791",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-02T11:02:49.565443759",
    "successful": true,
    "receipt": {
        "amount": 0,
        "meterNumber": "01012345671890",
        "aggregator": "BLUE_LABEL",
        "name": "Mr. William HC Reeds",
        "utility": "City of Tshwane",
        "tokens": [
            {
                "token": "47413704770415973118",
                "tokenDescription": "FBE Token",
                "quantity": 100.0,
                "unit": "kWh",
                "free": true
            }
        ],
        "processor": "C A S H P O W E R",
        "operator": "CIGICELLVEND",
        "receiptNumber": "87903/6491",
        "utilityVatNumber": "4000142267"
    }
}

Water Purchase

Example Payload

{
    "productCode": "WTR-FLS-001",
    "amount": 250.00,
    "paymentMethod" : "cash",
    "meterNumber": "000000000100",
    "additionalInfo": {}
}

Example Response

{
    "transactionId": "a92f701d-a1ae-491c-b569-564f658b8dd2",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-03T05:47:21.185975854",
    "successful": true,
    "receipt": {
        "amount": 25000,
        "address": "900000041391 5,HERLEAR,HERLEAR",
        "meterNumber": "000000000100",
        "aggregator": "BLUE_LABEL",
        "name": "AF VAN WYK",
        "utility": "ontec",
        "tokens": [
            {
                "token": "93293453542827534253",
                "tokenDescription": "Water Token",
                "quantity": 125.0,
                "unit": "kl",
                "free": false
            }
        ],
        "receiptNumber": "533705474401"
    }
}

Airtime/Data/SMS Testing

Test Mobile Numbers

Cell C — 840012300

MTN — 830012300

Telkom

850000000
850000009
850012345

Vodacom — 720012345

CellC Airtime Puchase Example Payload

{
  "productCode": "AIR-CLC-001",
  "amount": 201.00,
  "mobileNumber": "840012300",
  "paymentMethod": "cash",
  "additionalInfo": {}
}

Example Response

{
    "transactionId": "772709d7-857d-4d33-9c92-8721cdf4a965",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-02T11:15:51.623035713",
    "successful": true,
    "receipt": {
        "amount": 20100,
        "aggregator": "BLUE_LABEL"
    }
}

Vodacom Data Puchase Example Payload

{
    "productCode": "DAT-VOD-003",
    "amount": 219.00,
    "mobileNumber": "720012345",
    "paymentMethod" : "cash",
    "additionalInfo": {}
}

Example Response

{
    "transactionId": "444a0281-30fb-474a-ae9a-701c1d38beb4",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-03T05:53:04.26205571",
    "successful": true,
    "receipt": {
        "amount": 21900,
        "rechargeType": "PINLESS",
        "callCentre": "082111",
        "rechargeVendor": "AirtimeStub",
        "aggregator": "FLASH"
    }
}

Voucher Purchase Testing

Example Payload

{
  "productCode": "GAM-PBG-003",
  "amount": 224.00,
  "paymentMethod": "cash",
  "additionalInfo": {}
}

Example Response

{
    "transactionId": "4fd90d21-1d34-45c9-bae7-29f891aa54f2",
    "responseCode": "0",
    "responseMessage": "Purchase successful",
    "responseDateTime": "2025-12-02T11:19:07.985652347",
    "successful": true,
    "receipt": {
        "expiryDate": "2023-03-25",
        "amount": 22400,
        "redemptionInstructions": "1. Go to midasbuy.com/midasbuy/ot/redeem/pubgm \r\n\t2. Enter your Player ID and PIN\r\n\t3. The UC will be sent to your game account after the code is redeemed",
        "serialNumber": "6051221764667147835",
        "pin": "3K5L-DEN8-MBHG",
        "aggregator": "FLASH",
        "termsAndConditions": "Product is non-returnable or refundable.\r\n\tFor full T's & C's go to: http://www.pubgmobile.com/terms.html"
    }
}

Wallet Account Suspended

Triggers error 1300 - Wallet Suspended.

curl -X POST $BASE_URL/purchase \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "AIR-VOD-001",
    "amount": 50.00,
    "mobileNumber": "720012345",
    "paymentMethod": "cash",
    "channelId": "'$PAGAMIO_CHANNEL_ID'"
  }'

Expected Response:

{
    "responseCode": "1300",
    "responseMessage": "Wallet is SUSPENDED. Please contact support."
}

Insufficient Balance

Triggers error 1103 - Insufficient balance.

curl -X POST $BASE_URL/purchase \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "AIR-VOD-001",
    "amount": 999.00,
    "mobileNumber": "720012345",
    "paymentMethod": "cash",
    "channelId": "'$PAGAMIO_CHANNEL_ID'"
  }'

Expected Response:

{
    "responseCode": "1103",
    "responseMessage": "Insufficient balance. Available: 657.51 R, Required: 999.00 R"
}

Invalid Phone Number

Triggers error 1005 - Invalid phone number format.

curl -X POST $BASE_URL/purchase \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "AIR-VOD-001",
    "amount": 50.00,
    "mobileNumber": "+0720012345",
    "paymentMethod": "cash",
    "channelId": "'$PAGAMIO_CHANNEL_ID'"
  }'

Expected Response:

{
    "responseCode": "1005",
    "responseMessage": "Invalid phone number format"
}

Provider Timeout

Triggers a timeout after 30 seconds to test timeout handling.

curl -X POST $BASE_URL/purchase \
  -H "Authorization: Bearer $PAGAMIO_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "productCode": "AIR-VOD-001",
    "amount": 50.00,
    "mobileNumber": "720012345",
    "paymentMethod": "cash",
    "channelId": "'$PAGAMIO_CHANNEL_ID'"
  }'

Expected Response:

{
    "responseCode": "1204",
    "responseMessage": "Transaction Timeout"
}

Code Examples

JavaScript/Node.js
Python

const testScenarios = [
  { name: "Success", number: "720012345", expectedCode: 0 },
  { name: "Insufficient Balance", number: "720012345", expectedCode: 1103 },
  { name: "Invalid Number", number: "+27990000003", expectedCode: 1005 },
  { name: "Timeout", number: "720012345", expectedCode: 1204 },
];

async function runTestScenarios() {
  for (const scenario of testScenarios) {
    try {
      const response = await axios.post(
        `${baseUrl}/purchase`,
        {
          productCode: "AIR-VOD-001",
          amount: 50.0,
          mobileNumber: scenario.number,
          paymentMethod: "cash",
          channelId: channelId,
        },
        {
          headers: { Authorization: `Bearer ${token}` },
        }
      );

      console.log(`✓ ${scenario.name}: Success`);
    } catch (error) {
      const code = error.response?.data?.error?.code;
      if (code === scenario.expectedCode) {
        console.log(`✓ ${scenario.name}: Got expected error ${code}`);
      } else {
        console.log(`✗ ${scenario.name}: Unexpected error ${code}`);
      }
    }
  }
}

test_scenarios = [
    {'name': 'Success', 'number': '+27990000001', 'expected_code': 0},
    {'name': 'Insufficient Balance', 'number': '+27990000002', 'expected_code': 1103},
    {'name': 'Invalid Number', 'number': '+27990000003', 'expected_code': 1005},
    {'name': 'Timeout', 'number': '+27990000004', 'expected_code': 1204}
]

def run_test_scenarios():
    for scenario in test_scenarios:
        try:
            response = requests.post(
                f"{base_url}/purchase",
                json={
                    'productCode': 'AIR-VOD-001',
                    'amount': 50.00,
                    'mobileNumber': scenario['number'],
                    'paymentMethod': 'cash',
                    'channelId': channel_id
                },
                headers={'Authorization': f"Bearer {token}"}
            )
            print(f"✓ {scenario['name']}: Success")
        except requests.exceptions.HTTPError as e:
            code = e.response.json().get('error', {}).get('code')
            if code == scenario['expected_code']:
                print(f"✓ {scenario['name']}: Got expected error {code}")
            else:
                print(f"✗ {scenario['name']}: Unexpected error {code}")

Best Practices

Test All Scenarios - Run through all test scenarios before going to production
Implement Error Handling - Ensure your application handles each error code appropriately
Test Timeout Logic - Use the timeout scenario to verify your retry and status check logic
Automated Testing - Integrate these scenarios into your automated test suite
Monitor Results - Log test results to track integration stability

Next Steps

After testing all scenarios:

Review the Sample Test Numbers page for complete list
Check Debugging Tips for troubleshooting guidance
Implement proper Error Handling in your application

Bill Payment Test Scenario​

DSTV Test Account​

Sample Payload​

Expected Response​

Electricity Purchase Testing​

Test Meter Numbers​

Standard Electricity Purchase​

Example Payload​

Example Response​

Free Basic Electricity (FBE)​

Example Payload​

Example Response​

Water Purchase​

Example Payload​

Example Response​

Airtime/Data/SMS Testing​

Test Mobile Numbers​

CellC Airtime Puchase Example Payload​

Example Response​

Vodacom Data Puchase Example Payload​

Example Response​

Voucher Purchase Testing​

Example Payload​

Example Response​

Wallet Account Suspended​

Insufficient Balance​

Invalid Phone Number​

Provider Timeout​

Code Examples​

Best Practices​

Next Steps​

Bill Payment Test Scenario

DSTV Test Account

Sample Payload

Expected Response

Electricity Purchase Testing

Test Meter Numbers

Standard Electricity Purchase

Example Payload

Example Response

Free Basic Electricity (FBE)

Example Payload

Example Response

Water Purchase

Example Payload

Example Response

Airtime/Data/SMS Testing

Test Mobile Numbers

CellC Airtime Puchase Example Payload

Example Response

Vodacom Data Puchase Example Payload

Example Response

Voucher Purchase Testing

Example Payload

Example Response

Wallet Account Suspended

Insufficient Balance

Invalid Phone Number

Provider Timeout

Code Examples

Best Practices

Next Steps