• Forcing transactions to pay out
• Forcing collections to succeed
• Testing based on input
  • XOF mobile collections
    • Success scenario
    • Error scenario
• Automated Testing with Simulated Data
• Why Use Simulated Testing?
• Account validation
• Payouts
  • Ghana
    • GHS::Bank
    • GHS::Mobile
  • Nigeria
    • NGN::Bank
  • Uganda
    • UGX::Mobile
  • CEMAC Region (XAF)
    • XAF::Mobile
      • Cameroon
      • Gabon
  • WAEMU Region (XOF)
    • XOF::Mobile

Our sandbox environment is a trimmed down version of our production API that allows you test out new features. It is also the environment where you’ll need to demonstrate you can use our system well enough before we approve your API and give access to our production system.

To facilitate testing our sandbox environment has a few features that can help in developing your integration. These features are not available on our production environment.

Forcing transactions to pay out

You can use the POST /transactions/[TRANSFERZERO_TRANSACTION_ID]/payout endpoint with an empty body to force a funded, but not yet paid transaction to succeed. You can use this endpoint to test out if you are receiving successful transaction webhooks properly.

Forcing collections to succeed

You can use the POST /transactions/[TRANSFERZERO_TRANSACTION_ID]/payin endpoint with a PayinMethodRequest body to force a successful payin, for example to test out if you are receiving successful transaction webhooks properly. See the examples below using our SDKs

POST /v1/transactions/e77f89fa-8371-496c-ae73-e56697fc08d8/payin
{
 "payin_method":  {
  "type": 'GHS::Mobile'
 },
}

PayinMethodRequest request = new PayinMethodRequest(
  type: "GHS::Mobile",
TransactionsApi api = new TransactionsApi(configuration);
try {
  TransactionResponse response = api.PayinTransaction("e77f89fa-8371-496c-ae73-e56697fc08d8",request);
} catch (ApiException e) {
  if (e.IsValidationError)
    TransactionResponse response = e.ParseObject<TransactionResponse>();
    // Process validation error
  }
  throw e;
}
);

Dim request as PayinMethodRequest = New PayinMethodRequest(
  type:="GHS::Mobile",
Dim api as TransactionsApi = New TransactionsApi(configuration)
Try
  Dim response as TransactionResponse = api.PayinTransaction("e77f89fa-8371-496c-ae73-e56697fc08d8",request)
Catch e As ApiException
  If e.IsValidationError Then
    Dim response as TransactionResponse = e.ParseObject(Of TransactionResponse)()
    ' Process validation error
  End If
  Throw e
End Try
)

PayinMethodRequest request = new PayinMethodRequest();
request.setType("GHS::Mobile");
TransactionsApi api = new TransactionsApi(apiClient);
try {
  TransactionResponse response = api.payinTransaction("e77f89fa-8371-496c-ae73-e56697fc08d8",request);
} catch (ApiException e) {
  if (e.isValidationError()) {
    TransactionResponse response = e.getResponseObject(TransactionResponse.class);
    // Process validation error
  }
  throw e;
};

const request = new TransferZeroSdk.PayinMethodRequest();
request.type = "GHS::Mobile";
const api = new TransferZeroSdk.TransactionsApi(apiClient);
try {
  const response = await api.payinTransaction("e77f89fa-8371-496c-ae73-e56697fc08d8",request);
} catch (e) {
  if (e.isValidationError) {
    const response = e.getResponseObject();
    // Process validation error
  }
  throw e;
}

$request = new PayinMethodRequest();
$request->setType("GHS::Mobile");
$api = new TransactionsApi();
try {
  $response = api->payinTransaction("e77f89fa-8371-496c-ae73-e56697fc08d8",$request);
} catch (ApiException $e) {
  if ($e->isValidationError()) {
    $response = $e->getResponseObject();
    // Process validation error
  }
  throw $e;
}

request = TransferZero::PayinMethodRequest.new
request.type = "GHS::Mobile"
api = TransferZero::TransactionsApi.new
begin
  response = api.payin_transaction("e77f89fa-8371-496c-ae73-e56697fc08d8",request)
rescue TransferZero::ApiError => e
  if e.validation_error
    response = e.response_object("TransactionResponse")
    # Process validation error
  end
  raise e
end

Testing based on input

You can test success/error scenarios based on payload attributes such as:

• mobile_number
• amount

XOF mobile collections

Success scenario

When testing collections for XOF::Mobile, you can use a mobile number ending with 0 to have a collection succeed. The payload for this scenario would be:

{
  "id": "1625c534-6db4-4f3a-adf2-62a8bec89080",
  "type": "XOF::Mobile",
  "ux_flow": "ussd_voucher",
  "state": "initial",
  "in_details": {
    "otp": "1234",
    "phone_number": "+221771234700", // E.164 international format
    "mobile_provider": "orange",
    "country": "SN"
  },
  "out_details": {
    "style": "info"
  },
  "instructions": {}
}

Once the collection request is processed, you’d receive a payin_method.paid_in webhook:

{
  "webhook": "ddef6199-6171-43ba-bbb5-29fb06c9df9f",
  "event": "payin_method.paid_in",
  "object": {
    "id": "1625c534-6db4-4f3a-adf2-62a8bec89080",
    "type": "XOF::Mobile",
    "ux_flow": "ussd_voucher",
    "state": "success",
    "state_reason_details": {
      "code": "0",
      "category": "paid",
      "messages": [
        "Success",
        "Success",
        "Success"
      ],
      "description": "The transaction was successfully completed."
    },
    "in_details": {
      "otp": "1234",
      "ux_flow": "ussd_voucher",
      "phone_number": "+221771234700", // E.164 international format
      "mobile_provider": "orange",
      "country": "SN"
    },
    "out_details": {
      "style": "info"
    },
    "instructions": {
    },
    "transaction_id": "0d59466a-dc2f-4aca-bad1-d4a98da37697",
    "transaction_external_id": "510c4e28-fe33-4c06-bd79-49d52d5b3094"
  }
}

Error scenario

When testing collections for XOF::Mobile, you can use a mobile number ending with 9 to have a collection fail. The payload for this scenario would be:

{
  "id": "1625c534-6db4-4f3a-adf2-62a8bec89080",
  "type": "XOF::Mobile",
  "ux_flow": "ussd_voucher",
  "state": "initial",
  "in_details": {
    "otp": "1234",
    "phone_number": "+221771234709", // E.164 international format
    "mobile_provider": "orange",
    "country": "SN"
  },
  "out_details": {
    "style": "info"
  },
  "instructions": {}
}

Once the collection request is processed, you’d receive a payin_method.error webhook:

{
  "webhook": "ddef6199-6171-43ba-bbb5-29fb06c9df9f",
  "event": "payin_method.error",
  "object": {
    "id": "10bcee73-2c39-4c0d-9e00-7540c4d34a91",
    "type": "XOF::Mobile",
    "ux_flow": "ussd_voucher",
    "state": "error",
    "state_reason_details": {
      "code": "412",
      "category": "invalid_user_data_error",
      "messages": [
        "User Error",
        "Invalid user details",
        "Invalid mobile number"
      ],
      "description": "Mobile details are invalid. Please update the mobile details. You can also cancel this transaction."
    },
    "in_details": {
      "otp": "1234",
      "ux_flow": "ussd_voucher",
      "phone_number": "+221771234709", // E.164 international format
      "mobile_provider": "orange",
      "country": "SN"
    },
    "out_details": {
      "style": "info"
    },
    "instructions": {
    },
    "transaction_id": "b83f38d6-fc4c-49de-b512-f45ac914bbea",
    "transaction_external_id": "9b5f3c64-9b6b-41b8-9658-168999961b70"
  }
}

Automated Testing with Simulated Data

Welcome to the AZA automated testing playground!

This guide will show you how to safely test your integration with our API using simulated transactions, without real data or money involved, in our Sandbox environment.

Why Use Simulated Testing?

Simulated testing lets you:

• Validate integration flows (e.g. account validation and transaction creation/payout).

• Simulate different transactions and recipients states (paid, pending, temporary errors, recipient errors and sender errors).

• Catch errors early, before they hit production.

All tests happen in our Sandbox environment, using deterministic test data, making responses consistent and predictable.

Account validation

We currently support simulated account validation tests in our Sandbox environment for the following countries/corridors:

• Ghana (GHS::Bank and GHS::Mobile)
• Nigeria (NGN::Bank)
• Uganda (UGX::Mobile)

The account validation test is a simulation of the account validation flow, which is used to verify the validity of a recipient’s account before sending money. The test will return a success or failure response based on the provided bank_account or phone_number (depending on the corridor) last (or last 2) digit(s).

• For GHS::Bank and GHS::Mobile a bank_account or phone_number ending in a digit between 0 and 8 will return a successful response, whereas setting 9 as last digit will return a failure response (for the full request details please refer to the Ghana Account Validation Documentation).

• For NGN::Bank a bank_account ending in a digit between 0 and 9 will return a successful response, whereas setting 39 as the last 2 digits will return a failure response (for the full request details please refer to the Nigeria Account Validation Documentation).

• For UGX::Mobile with airtel set as mobile provider a phone_number ending in a digit between 0 and 9 will return a successful response, whereas setting 29 as the last 2 digits will return a failure response.

• For UGX::Mobile with mtn set as mobile provider a phone_number ending in a digit between 0 and 9 will return a successful response, whereas setting 19 as the last 2 digits will return a failure response.

For the full request details please refer to the Uganda Account Validation Documentation.

Please refer to the Account Validation Responses section for more detailed informations about the possible responses you can expect to be returned for each scenario (kindly note that the system failure/connectivity issue scenario - Account validation failed error response - is not currently available to be tested in Sandbox).

Payouts

We currently support simulated payouts tests in our Sandbox environment for the following countries/corridors:

• Ghana (GHS::Bank and GHS::Mobile)
• Nigeria (NGN::Bank)
• Uganda (UGX::Mobile)
• CEMAC Region (XAF) (XAF::Mobile)
• WAEMU Region (XOF) (XOF::Mobile)

Kindly reference the table below when testing our simulated payout feature, showing the expected setup and corresponding responses for different countries and corridors (category, code and description will be returned in the state_reason_details object - please refer to the Receiving error messages section for more informations):

Ghana

GHS::Bank

GHS::Mobile

Nigeria

NGN::Bank

Uganda

UGX::Mobile

• With airtel set as mobile provider:

• With mtn set as mobile provider:

CEMAC Region (XAF)

XAF::Mobile

Cameroon

Gabon

WAEMU Region (XOF)

XOF::Mobile