Step 2: Process Ozow Response
Ozow will send the following two posts back to the merchant:
• Redirect Response
• Notification Response
Redirect response
Depending on the payment completion status from Ozow, the response variables will be posted while redirecting the user to the applicable page. Please note that if the applicable URL was not sent in the post variables, or set for the merchant site in the merchant admin site, the user will not be redirected back to the merchant site, along with the post containing the response variables. The URL used will be determined as follows:
• Error URL - An error occurred during the payment process and payment was NOT successful
• Cancelled URL - The user opted to cancel during the payment process and payment was NOT successful
• Success URL - The payment was successful
Use the hash response variable to verify the validity of the response. This process is further described in the response hash check section below. It's recommended that you use the notification response to verify the outcome of the transaction.
Notification response
We will post the response variables to the designated notification URL. Please note that if the notification URL (NotifyUrl) was not sent in the post variables, or set for the merchant site in the merchant admin site, we will not be able to send the notification post containing the response variables. Use the hash response variable to verify the validity of the response. This process is further described in the response hash check section below.
Please note:
While we do our utmost to ensure that duplicate notifications are not sent to the notification URL, at times there may be instances where multiple notifications are sent for the same transaction. As such, it is of the utmost importance that your system is built in a manner that caters for this scenario, i.e. if you receive multiple notifications for the same transaction your client/payer is not credited multiple times for the payment.
Response variables
| Property | Type | Description |
|---|---|---|
1.SiteCode | String (50) | The site code sent to Ozow in the request post. |
2.TransactionId | String (50) | The transaction identifier generated by Ozow. |
3.TransactionReference | String (50) | The merchant's transaction reference sent in the request post's TransactionReference variable. |
4.Amount | Decimal (9,2) | The transaction amount. The amount is in the currency specified by the currency code posted. |
5.Status | String (50) | The transaction status. Possible values are: 1. Complete - The payment was successful. 2. Cancelled - The payment was cancelled. 3. Error - An error occurred while processing the payment. 4. Abandoned – The payment was abandoned. 5. PendingInvestigation – An inconclusive result was received by the bank and the payment needs to be verified manually. 6. Pending – The status cannot be determined as yet but will be reposted to the notification URL as soon as it has been determined. Merchants not using the notification URL will receive a PendingInvestigation status. |
6.Optional17. Optional28. Optional39. Optional410. Optional5 | String (50) | Optional fields sent in the request post. |
11.CurrencyCode | String (3) | The transaction currency code sent in the request post. |
12.IsTest | bool | Whether or not the original request was a test request. Possible values are true or false. |
13.StatusMessage | String (150) | Message regarding the status of the transaction. This field will not always have a value. This is a user friendly message that can be displayed to the user e.g. User cancelled transaction. |
14.Hash | String (100) | SHA512 hash used to ensure that certain fields in the message have not been altered after the hash was generated. Check the generate hash section below for more details on how to validate the response variables using the hash. |
15.SubStatus(See full list below) | String (50) | The transaction sub status for failed transactions. The value provides an indication as to why the payment failed. Some examples: • Unclassified – Failure scenario has not been mapped • InsufficientFunds - User did not have sufficient funds available to complete the payment While there are several sub-statuses, they have not been included here as they are strictly for reporting. |
16.MaskedAccountNumber | String (50) | The masked account number the payment was made from. If account number is 12 or more digits then the first and last four digits are unmasked e.g. 1234567898765 will be masked as 1234*****8765 If the account number is less than12 digits then the first and last 3 digits are left unmasked e.g. 123456789 will be masked as 123***789 This is not available by default and a request by the merchant must be submitted along with a justification for requiring this information. |
17.BankName | String (50) | The name of the bank the payment was made from. |
18.SmartIndicators | String (500) | Some Ozow merchants have requested this information as they use this in their own processes. The can be ignored unless you have a purpose and application for this information. The application of these indicators are for the merchant’s discretion and in isolation do not constitute any action to be taken by the merchant. The field will contain a pipe delimited list of the following values if they are applicable e.g. HIGH_VALUE | FIRST_OZOW : • HIGH_VALUE – If a soft limit is configured on the site and the amount paid is higher or equal to the configured limit • FIRST_OZOW – First time a user has paid using Ozow • FIRST_MERCHANT – First time a user has paid the merchant using Ozow • NEW_OZOW – User has paid using Ozow for the first time in the past seven days • NEW_MERCHANT - User has paid the merchant using Ozow for the first time in the past seven days |
SubStatus - List
The list refers to property 15. SubStatus The transaction sub status for failed transactions. The value provides an indication as to why the payment failed, each variant response is accounted for by number.
| SubStatus | Number |
|---|---|
| Unclassified | 0 |
| AutomationError | 1 |
| AutomationStepUnhandled | 2 |
| BankingLimitExceeded | 3 |
| LoginError | 4 |
| PushAppMessageDeclined | 5 |
| PushAppMessageError | 6 |
| AutomationInactivityTimeout | 7 |
| CustomerAccountError | 8 |
| BankNotResponding | 9 |
| CaptchaRequired | 10 |
| MerchantAccountError | 11 |
| OnlineBankingProfileError | 13 |
| InvalidPaymentReference | 14 |
| AutomationStartupFailure | 15 |
| BeneficiaryOrPaymentConfirmationFailure | 16 |
| DuplicatePayment | 17 |
| OnlineBankingTimeout | 19 |
| NoAvailableAccounts | 21 |
| OnlineBankingUnavailable | 22 |
| BankTechnicalError | 23 |
| SimSwapBlock | 24 |
| BankNotice | 25 |
| InsufficientFunds | 26 |
| NoInternetBanking | 28 |
| PaymentConfirmationError | 29 |
| AutomationLoopDetected | 31 |
| OnlineBankingVersionMigration | 35 |
| CreditCardNotAllowedMerchant | 36 |
| FraudulentActivity | 37 |
| BankPaymentError | 38 |
| OnlineBankingAction | 39 |
| OtpInvalidError | 40 |
| InsufficientAccess | 41 |
| PasswordChangeRequired | 42 |
| PublicBeneficiaryError | 43 |
| PaymentDetailsVerificationError | 44 |
| InvalidCustomerInput | 45 |
| AutomationPopulationError | 46 |
| ReceiptTimeout | 47 |
| NoLoginTimeout | 48 |
| UserCancelled | 49 |
| CancelToRetry | 50 |
| BrowserExitOrRedirect | 51 |
| AutomationNotStarted | 52 |
| LoginPageNotReached | 53 |
| NoBankSelected | 54 |
| AnomalousHighValueForUser | 55 |
Response hash check
Follow these steps to validate the response:
- Concatenate the response variables 1-13, in the order they appear in the response variables table.
- Append your private key to the concatenated string. Your private key can be found in the merchant details section of the merchant admin site.
- Convert the concatenated string to lowercase.
- Generate a SHA512 hash of the lowercase concatenated string.
- Compare generated hash to the hash value in the response variables.
Warning!
Some implementations of SHA512 drop the leading zeros. It is advisable to trim the leading zeros from the received and calculated hashes when comparing.
Only include variables listed in the response variables table above.
Updated over 1 year ago