| Property name | Description | Value format |
|---|---|---|
| Valid email, max 100 characters | ||
| mobileNo | Mobile number | Full country code, only dialling digits, no symbols e.g. 48693427795 |
| businessId | TIW unique business id, provided by MaxCom | Exactly: '1' |
| customerName | Customer name | String, only English Alphabets allowed, max 100 chars |
| amount | Amount to be charged in TSh | Positive integer |
| txnId | Transaction id, unique, generated by TIW | Positive integer, Max 11 digits |
| hashCode | MD5 Hash of Shared Secret + amount + businessId + customerName + email + mobileNo + txnId | MD5 Hash |
Request is initialized by user from TIW application window, so there's no MaxCom response that can be parsed on TIW end, instead user is presented with expected interface of MaxCom application.
Customer (or TIW) may choose to cancel a Mobile Payment transaction. (This API is not applicable for Credit Card Payment)
To initiate cancellation, this API is invoked on MaxCom payment server (which in turn communicates the same to Mobile Money Gateway) and responds back with a Success or Failure. In case of failure, the same API may be re-invoked later (or handled manually).
| Property name | Description | Value format |
|---|---|---|
| txnId | Transaction Id (as provided by TIW in payment initialization request) | Positive integer |
| amount | Charged amount | Positive integer |
| hashCode | MD5 Hash of Shared Secret + amount + txnId | MD5 Hash |
| Property name | Description | Value format |
|---|---|---|
| txnId | Transaction Id (as provided by TIW in payment initialization request) | Positive integer |
| cancellationNo | Unique Cancellation No. | Positive integer,12 digits |
| cancellationDate | Cancellation Date and Time in YYYYMMDDHH24MISS format | |
| amount | Charged amount | Positive integer |
| status | Status | One of the following strings: "Success", "Failure" |
| responseCode | Internal response code of MaxCom, not meaningful to TIW, to be saved just for reference | 0-Success, 1 to 100 for different errors. |
| responseMessage | Message (human friendly description of status) | Max 200 characters |
| hashCode | MD5 Hash of Shared Secret + amount + cancellationDate + cancellationNo + responseCode + responseMessage + status + txnId | MD5 Hash |
Customer may choose to make payment via Credit Card or Mobile Money.
In case of Credit Card, this URL will be invoked after the Credit Card Payment Gateway either returns a Success or Failure response, and the same information is passed to TIW by redirecting browser to the resolve-payment-transaction URL.
In case of Mobile Money, payment is completed in 2 steps:
Step 1: Payment initialisation
Customer is presented with a Mobile Txn Ref and after pausing for 2 minutes, customer is redirected to resolve-payment-transaction URL. At this point, it is not known whether customer has completed the payment or not. Hence, a response code of 999 is returned with a Transaction Message of "Transaction Initiated Successfully" and "Success" status.
TIW Handshake: GET on resolve-payment-transaction
Step 2: Payment Completion
Upon completion of payment after a certain duration (after initialisation call, could it be before also in some cases(?)), same URL is invoked with a response code of 0.
TIW Handshake: POST (Same URL as a REST API) on resolve-payment-transaction from MaxCom Payment Gateway Server to TIW Server
| Property name | Description | Value format |
|---|---|---|
| txnId | Transaction Id (as provided by TIW in payment initialization request) | Positive integer |
| amount | Charged amount | Positive integer |
| status | Status | One of the following strings: "Success", "Failure", "Cancelled" |
| responseCode | Internal response code of MaxCom, not meaningful to TIW, to be saved just for reference | 0-Success, 1 to 100 for different errors. 999 in case of Mobile Money txn initiation |
| responseMessage | Message (human friendly description of status) | Max 200 characters |
| receiptNo | Receipt Number | Mobile Txn Ref for Step 1 and Receipt No. for Step 2. Max 20 characters |
| hashCode | MD5 Hash of Shared Secret + amount + receiptNo + responseCode + responseMessage + status + txnId | MD5 Hash |
Request is initialized by user from MaxCom application window, so instead of sending response to MaxCom service, TIW server responds back with TIW user application.
MaxCom may choose to cancel a Mobile Payment transaction in case payment is not received with defined time - Ex: After 2 days. (This API is not applicable for Credit Card Payment).
To initiate cancellation, this API is invoked by MaxCom payment server to TIW server and TIW server responds back with a Success or Failure. In case of failure, the same API may be re-invoked later (or handled manually).
| Property name | Description | Value format |
|---|---|---|
| txnId | Transaction Id (as provided by TIW in payment initialization request) | Positive integer |
| amount | Charged amount | Positive integer |
| cancellationNo | Unique Cancellation No. | Positive integer,12 digits |
| cancellationDate | Cancellation Date and Time in YYYYMMDDHH24MISS format | |
| hashCode | MD5 Hash of Shared Secret + amount + cancellationDate + cancellationNo + txnId | MD5 Hash |
| Property name | Description | Value format |
|---|---|---|
| txnId | Transaction Id (as provided by TIW in payment initialization request) | Positive integer |
| amount | Charged amount | Positive integer |
| status | Status | One of the following strings: "Success", "Failure", "Cancelled" |
| responseCode | Internal response code of TIW, not meaningful to MaxCom, to be saved just for reference | 0-Success, 1 to 100 for different errors. |
| responseMessage | Message (human friendly description of status) | Max 200 characters |
| hashCode | MD5 Hash of Shared Secret + amount + responseCode + responseMessage + status + txnId | MD5 Hash |