Payout test cases

PayoutPayout Money sent from a merchant to a bank account. Unlike a refund, a payout is not tied to a payment anyone made you, so you can pay anyone with a bank account. Payouts draw on your float rather than on your incoming payments, and they are not self-service: they need approval from Ozow and testing in staging first. 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

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 floatFloat The balance held with Ozow that payouts and refunds are paid out of. Both draw on it, and neither will process while it is empty. Payins do not need one, so if you only take payments you never meet it. will be set up with test funds by Ozow's integration team as part of the staging environment setup
• RTCReal-Time Clearing Payments that clear immediately rather than waiting for a batch. A batch run settles at set times through the day; a Real-Time Clearing payment moves the funds between the two bank accounts as it is made, so the recipient can rely on them straight away.PayInc 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.

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
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

---

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

---

Test 3: Receive verification request and respond successfully#

Verify that your verification webhookWebhook A URL of yours that Ozow calls when something happens, rather than you polling to find out. The call carries no credential of yours and arrives at a public URL, so authenticate it before acting on it: a hash field on the Payments API, a Svix signature on One API. 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.

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

Step 1: Get current test configuration

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

Step 2: Set test configuration

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.

---

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