Check Payout status using API (recommended)
Even though this step is optional, we highly recommend it to ensure that responses received reflect the correct transaction status. This will eliminate the chance that anyone is able to spoof the Ozow response to update a transaction status on the merchant site.
Each API call needs an http header value with the merchant's API key. The following API method can be used to check the transaction status:
- GetPayout
GetPayout
{baseUrl}/getpayout?payoutId={payoutId}
This method is called when you want to query a payout using the payoutId. This method can return multiple results. Ozow does not restrict the merchant from sending duplicate merchant references, even though we do advise that a unique reference is sent per transaction. The number of results returned are limited to 10.
Property | Type | Req. | Description |
---|---|---|---|
PayoutId | Guid | Yes | The unique payout identifier. |
Response
Payout - a successful call will return a payout object. The payout object is described further down.
{
"id": "00000000-0000-0000-0000-000000000000",
"amount": 0.01,
"merchantReference": "123",
"customerBankReference": "ABC123",
"siteCode": "[YOUR SITE CODE]",
"notifyUrl": "https://requestcatcher.com/",
"isRtc": false,
"bankingDetails": {
"bankGroupId": "13999FA-3A32-4E3D-82F0-A1DF7E9E4F7B",
"branchCode": "198765",
"accountNumber": "ff313a955ad9a8ddff32cb734d49fbcddd8eeb1e235009d59a801bc5af78270cfd"
},
"payoutStatus": {
"status": 5,
"subStatus": 0,
"errorMessage": "Complete"
}
}
Payout object
This is the object referred to in the response of the API calls above.
Property | Type | Description |
---|---|---|
Id | Guid | Ozow's unique reference for the payout. |
Amount | Decimal (9,2) | The payout amount. |
SiteCode | String (50) | Unique code assigned to each merchant site. [Please contact support for SiteCode - [email protected]] |
MerchantReference | String (20) | Merchant's payout reference. |
CustomerMerchantReference | String (20) | The reference that will be pre-populated in the "their reference" field in the customers online banking site. This will be the payout reference that appears on the merchant’s bank statement and can be used for recon purposes. |
NotifyUrl | String (150) | The URL that we should use to post all payout notifications. |
IsRTC | bool | Whether the payout should be processed as an RTC payout. |
BankingDetails | Object | Payout destination banking details. Refer to the BankingDetails table below. |
PayoutStatus | Object | Payout status. Refer to PayoutStatus table. |
BankDetailsObject
Property | Type | Req. | Description |
---|---|---|---|
BankGroupId | Guid | Yes | The unique bank identifier. |
AccountNumber | Strong (32) | Yes | The bank account number the payment should be made to. The account number should be encrypted by the encryption method detailed above. |
BranchCode | String (10) | Yes | The destination bank branch code. |
Payout Status
Property | Type | Description |
---|---|---|
Status | Int | The payout status. Possible values are: 1 - PayoutReceived - The payout has been received 2 - Verification - The payout is being verified 3 - SubmittedForProcessing - The payout is being processed 4 - PayoutProcessingError- There was an error with the payout 5 – PayoutComplete – The payout has been completed 6 – PayoutPendingInvestigation – The payout is being investigated 90 – PayoutReturned – The Payout could not be paid into recipient account 99 - Payout Cancelled - The payout was cancelled |
SubStatus | Int | The payout sub status. Possible values are: 100 - Payout_Unclassified - no sub status 101 - Payout_ValidationFailed – request validation failed and error description will be in the ErrorMessage field 201 – Verification_Pending - awaiting webook verification 202 - Verification_Failed - The verification webhook returned a failed 203 - Verification_Success - Successful payout verification via webhook 204 - Verification_Error - Unable to reach the verification webhook 205 - Verification_AccountNumberDecryptionFailed - decryption of the account number failed using the key received via webhook 206 - Verification_Success_Awaiting_Funds - Verification Success - Awaiting float top-up 207 - Verification_Success_Awaiting_Submission - Verification Success - Awaiting submission 301 - SubmittedForProcessing_PayoutAddedToBatch - the payout has been added to the payout batch 302 -SubmittedForProcessing_PayoutSubmittedToBank - the payout batch has been processed and submitted to the bank 303 - SubmittedForProcessing_PayoutSubmittedToPpi – payout submitted for processing 401 -PayoutProcessingError_PayoutRejected – the payout has been rejected by the bank 402 - PayoutProcessingError_PayoutCancelled - the payout has been cancelled 403 - PayoutProcessingError_Insufficient_Balance - insufficient balance 404 - PayoutProcessingError_PayoutInternalError 405 - PayoutProcessingError_InvalidAccountNumber – the payout has an invalid account number 601 - PayoutPendingInvestigation_AmountMismatch – the payout failed due to mismatch in amounts 9001 – PayoutReturned_Unpaid – Rejected By Destination Bank 9901 - Cancellation_AddedToBatch – cancellation request added to batch for processing 9902 - Cancellation_SubmittedToBank – cancellation request has been submitted to the bank 9903 - Cancellation_RejectedByBank – Cancellation request has been rejected by the bank 9904 - Payout Cancellation - CDV account number validation failed |
ErrorMessage | String (250) | Error message. |
TestConfigurationModel
To test the different outcomes a payout request may have, a merchant will be required to configure the various outcomes that a payout request may incur based on the setting configured. Below are the two API calls that provide the Get and Set methods for access to changing the TestConfigurationModel.
Get configuration.
{baseUrl}/gettestconfiguration?siteCode={siteCode}
When this method is called, the required parameter is the SiteCode of the merchant that returns the state of the configuration set by the merchant. This method can return a null object or return the current settings set for the merchant site. A null reference means the merchant has not yet set a test configuration setting.
Property | Type | Req. | Description |
---|---|---|---|
SiteCode | String (50) | Yes | Unique code assigned to each merchant site. [Please contact support for SiteCode - [email protected]] |
Response model: refer to table below
Set configuration
{baseUrl}/settestconfiguration
When this method is called, the merchant sets new settings or updates the current settings that will impact the result set to expect when a payout request is made. The purpose of this method is to mock the outcome of the payouts, marking the given fields as true in order to produce an expected outcome in the process of making a payout.
Constraint:
A valid method call only happens when one field is set to true. This prevents the expected outcome from only generating a response for one instance at a time. If all fields are marked as false for the test configuration model, the mock outcome will be the default payout request and a complete payout request journey will be undertaken.
Parameters
Property | Type | Description |
---|---|---|
SiteCode | String (50) | Unique code assigned to each merchant site. [Please contact support for SiteCode - [email protected]] |
IsAccountDecryptionFailed | bool | When set to true, all payout requests will return status code 99 and sub status 205 to mock decryption failure. |
IsNullResponse | bool | When set to true, all payout requests will return status code 2 and sub status 204 to mock a null response from the merchant callback. |
IsInvalidStatusCode | bool | When set to true, all payout requests will return status code 99 and sub status 202 to mock invalid status code. |
IsPayoutMismatch | bool | When set to true, all payout requests will return status code 2 and sub status 204 to mock a payout mismatch. |
IsNotVerifiedResponse | bool | When set to true, all payout requests will return status code 99 and sub status 202 to mock a response is not yet verified. |
IsAccountNumberDecryptionKeyMissing | bool | When set to true, all payout requests will return status code 99 and sub status 205 to mock account decryption key is missing. |
HasRetriedCountBeenExceeded | bool | When set to true, all payout requests will return status code 99 and sub status 204 to mock retry count has been exceeded. |
Important
Add the SiteCode and ApiKey as headers for each request.
Updated 2 months ago