Skip to content

Instantly share code, notes, and snippets.

@medikoo
Last active August 29, 2015 14:02
Show Gist options
  • Save medikoo/65e7c42e7c9ae86cca49 to your computer and use it in GitHub Desktop.
Save medikoo/65e7c42e7c9ae86cca49 to your computer and use it in GitHub Desktop.

TIW <-> MaxCom data exchange API

Shared Secret string used to validate requests, is hardcoded within codebase, and not exposed in this document on purpose.

API of MaxCom service

Initialization of payment transaction

Request data
Property nameDescriptionValue format
emailEmailValid email, max 100 characters
mobileNoMobile numberFull country code, only dialling digits, no symbols e.g. 48693427795
businessIdTIW unique business id, provided by MaxComExactly: 1
customerNameCustomer nameString, only A-Za-z0-9 and space, max 100 chars
amountAmount to be charged in TShPositive integer
txnIdTransaction id, unique, generated by TIWPositive integer, Max 11 digits
paymentMethodChosen payment method (either Credit Card or Mobile Money)One of the tokens: cc, mp
hashCodeMD5 Hash of Shared Secret + amount + businessId + customerName + email + mobileNo + paymentMethod + txnIdMD5 Hash
Response
In case of credit card method
Status: 201 Created
Location: [url to which user should be redirected]

Where Status is a HTTP Status, any other (not 201) HTTP status code should not be handled (failure should be assumed).

Location is HTTP header specifying to which page on MaxCom website we should redirect user.

In case of mobile payment method
Status: 201 Created

[Some text that should be displayed to user within TIW application]

Where Status is a HTTP Status, any other (not 201) HTTP status code should not be handled (failure should be assumed).

Cancellation of payment transaction

Request data
Property nameDescriptionValue format
txnIdTransaction idas at initialization
businessIdTIW unique business id, provided by MaxComas at initialization
hashCodeMD5 Hash of Shared Secret + businessId + txnId MD5 Hash
Response
Status: 200 OK

Where Status is a HTTP Status, any other (not 200) HTTP status code should not be handled (failure should be assumed).

API of TIW service

Resolution of payment

Request data
ret
Property nameDescriptionValue format
txnIdTransaction Idas at initialization
statusStatus (approved, cancelled or rejected)One of the following tokens: approved, cancelled, rejected
responseMessageHuman friendly description of a statusMax 200 characters
receiptNoReceipt NumberProvided only in case of approved status (otherwise an empty string), Max 20 characters
hashCodeMD5 Hash of Shared Secret + receiptNo + responseMessage + status + txnIdMD5 Hash
Response
Status: 200 OK

Where Status is a HTTP Status, any other (not 200) HTTP status code should not be handled (failure should be assumed).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment