# Payout test cases

> The mandatory tests for a payout integration, for bulk payouts from the Dashboard and for the Payouts API. You must pass these before going live.

Source: https://hub.ozow.com/integration-methods/testing/payout-test-cases/

Payout test cases are mandatory. You must complete all relevant tests below and receive sign-off
from Ozow's integration team before your payout integration can go live in production.

This page covers test cases for two integration paths:

- **Bulk payouts**: no-code payout submission via the Ozow Dashboard
- **API payouts**: programmatic payout integration via the Payouts API, covering both standard API
  tests and mock API simulation tests

Complete only the test cases relevant to your integration. If you are integrating both, you must
complete the test cases for each separately.

## How the process works

1. Complete all relevant test cases in the staging environment
2. Submit your test evidence via the link provided by your Ozow integration team contact
3. Ozow reviews your submission internally
4. If approved, Ozow collects your production configuration details and sets up your production environment
5. You receive confirmation that your integration is ready for go-live

> ℹ️ **Postman collection**: A Postman collection for the Payouts API is available in the [Payouts
> API reference](https://hub.ozow.com/api-reference/payouts-api.md). Download it to run these test cases directly in Postman.

## Important notes before testing

- All tests must be completed in the staging environment, no real funds are required and no real
  transactions take place in staging
- Your staging float will be set up with test funds by Ozow's integration team as part of the
  staging environment setup
- RTC payments are not available in staging: set `IsRtc` to `false` for all tests

---

## Bulk payout test cases

If you are integrating bulk payouts via the Dashboard, you must complete the following test in the
staging environment before bulk payouts can be enabled in production.

> ℹ️ **Note**: Bulk payout testing is separate from API payout testing. If you are integrating both,
> you must complete the relevant test cases for each.

### Bulk payout test 1: Successful bulk payout submission

Verify that you can successfully submit and complete a bulk payout via the Dashboard.

**Steps**

1. Log in to your staging Dashboard at [stagingdash.ozow.com](https://stagingdash.ozow.com)
2. Navigate to **Payouts** → **Bulk Payouts**
3. Download the CSV template and the Available Banks file
4. Complete the template with at least one valid payout
5. Upload the completed template
6. Approve the batch using an account with the bulk payout approver role
7. Confirm that at least one payout in the batch completes successfully

**Evidence required**

- Screenshot or URL of the completed batch on the Bulk Payouts page showing at least one successful
  payout

---

## Standard API test cases

Run these tests against the standard staging endpoint, `https://stagingpayoutsapi.ozow.com/v1/requestpayout`.

### Test 1: Request payout below minimum amount

Verify that your integration correctly handles a payout request below the minimum amount of R1.

**Steps**

1. Submit a payout request for an amount less than R1.00
2. Capture the JSON response from the API

**Evidence required**

- JSON response from the API

> ℹ️ **Note**: This validation does not show on the Ozow Dashboard. The JSON API response is the
> only evidence required for this test.

---

### Test 2: Request payout above maximum amount

Verify that your integration correctly handles a payout request above the maximum amount of R20.

**Steps**

1. Submit a payout request for an amount greater than R20.00
2. Capture the JSON response from the API

**Evidence required**

- JSON response from the API

> ℹ️ **Note**: This validation does not show on the Ozow Dashboard. The JSON API response is the
> only evidence required for this test.

---

### Test 3: Receive verification request and respond successfully

Verify that your verification webhook receives the request from Ozow and responds correctly.

**Steps**

1. Submit a valid payout request
2. Confirm that your verification webhook receives the verification request from Ozow
3. Respond to the verification request correctly with `IsVerified: true` and the decryption key
4. Confirm that a verification success timestamp appears on the payout details in the Dashboard

**Evidence required**

- URL of the payout from the Dashboard showing the verification success timestamp

---

### Test 4: Receive payout verification success message

Verify that your notification URL receives the verification success message from Ozow.

**Steps**

1. This test occurs automatically on successful completion of Test 3
2. Confirm that your notification URL receives a `verificationSuccess` message
3. Confirm this is visible under "Payout responses" on the payout details in the Dashboard

**Evidence required**

- URL of the payout from the Dashboard showing the `verificationSuccess` message sent to your
  notification URL

---

### Test 5: Receive payout complete message

Verify that your integration correctly handles a successfully completed payout.

**Steps**

1. Submit a valid payout request and complete the verification flow
2. Confirm that your notification URL receives a payout complete notification
3. Confirm the payout shows as successful on the Dashboard

**Evidence required**

- URL of the payout from the Dashboard showing a successful payout and notification to your
  notification URL

---

### Test 6: Receive payout cancelled message

Verify that your integration correctly handles a cancelled payout.

**Steps**

1. Submit a payout request that results in a cancellation
2. Confirm that your notification URL receives a payout cancelled notification
3. Confirm the cancellation is visible on the Dashboard

**Evidence required**

- URL of the payout from the Dashboard showing the cancellation

---

### Test 7: Receive low float balance message

Verify that your low float balance alert is working correctly.

**Steps**

1. Your low float balance alert is triggered when your float balance reaches R99.00 in staging
2. Confirm that the alert email is received by the user configured for float balance alerts

**Evidence required**

- Screenshot of the low float balance alert email received

---

### Test 8: CDV error, account number validation error

Verify that your integration correctly handles an account number validation error.

**Steps**

1. Submit a payout request using account number `1234567890` to trigger a CDV error
2. Confirm the error is visible on the Dashboard

**Evidence required**

- URL of the payout from the Dashboard showing the CDV error

---

### Test 9: Get payout status

Verify that you can successfully retrieve payout status via the API.

**Steps**

1. Submit a valid payout request and note the `payoutId`
2. Call the `getPayout` endpoint using the `payoutId`
3. Capture the JSON response from the API

**Evidence required**

- JSON response from the API

---

## Mock API test cases

Run these tests against the mock staging endpoint, `https://stagingpayoutsapi.ozow.com/mock/v1`, to
simulate specific failure scenarios.

> ℹ️ **Note**: Payout requests submitted to mock endpoints are not visible on the Dashboard. The
> JSON API response is the only evidence required for these tests.

For each of the three mock scenarios below, follow these steps:

**Step 1: Get current test configuration**

```http
GET https://stagingpayoutsapi.ozow.com/mock/v1/gettestconfiguration?siteCode={siteCode}
```

**Step 2: Set test configuration**

```http
POST https://stagingpayoutsapi.ozow.com/mock/v1/settestconfiguration
```

Set only the relevant field to `true` for the scenario you are testing. All other fields must be `false`.

**Step 3: Verify configuration**

Call `getTestConfiguration` again to confirm the configuration was set correctly before proceeding.

**Step 4, Submit mock payout request**

Submit a payout request to the mock endpoint to trigger the configured simulation response.

**Step 5, Get mock payout status**

Call `getMockPayout` to retrieve the result and capture the JSON response.

> ⚠️ **Important**: Repeat all five steps for each simulation scenario. Set exactly one field to
> `true` at a time. Reset the configuration between each test.

---

### Mock test 1: Account decryption failed

Set `IsAccountDecryptionFailed: true` in the test configuration and complete the five steps above.

**Evidence required**

- JSON response from the mock payout request
- JSON response from getMockPayout

---

### Mock test 2: Not verified response

Set `IsNotVerifiedResponse: true` in the test configuration and complete the five steps above.

**Evidence required**

- JSON response from the mock payout request
- JSON response from getMockPayout

---

### Mock test 3: Account decryption key missing

Set `IsAccountDecryptionKeyMissing: true` in the test configuration and complete the five steps above.

**Evidence required**

- JSON response from the mock payout request
- JSON response from getMockPayout