Marx IPG Integration Document
Version 2.0.0
Revision History
Author Date Description Version
Daini Nimaya 31/07/2020 Create order in Marx 1.0.0
Initiate the Payment
Daini Nimaya 06/08/2020 Redirect user to marx payment 1.0.1
url
Redirect user to the merchant
return url
Check the validity of the query
parameter
Daini Nimaya 25/08/2020 Change the domain in url 1.0.2
3Ds authentication page
Daini Nimaya 11/09/2020 Change the url of the API call. 2.0.0
Update the request parameters
Add response code
Add Summary results
Add Gateway Code
Abbreviations
API Application Programming Interface
IPG Internet Payment Gateway
URL Uniform Resource Locator
Step 01: Create order in Marx
The API is used to create an order request in Marx IPG side by the Merchant. Customer mail
is required if the mode is MAIL and customer mobile no. is required if the mode is SMS. And
if the mode is WEB customer mail and mobile no are not mandatory. It is required to send the
merchant secret (which is mailed by Marx when registering the merchant) in the header of the
API call.
URL : https://dev.app.marx.lk/api/v2/ipg/orders
Method: POST
Request Parameter Type Description Mandatory
merchantRID String Merchant unique reference id of the Yes
order(This can’t be duplicated)
amount Float Amount of the transaction Yes
validTimeLimit Int Time limit of the transaction to Yes
proceed (in hours)
returnUrl String Url of the page to display payment Yes
result
customerMail String Mail address of the customer Yes(in the case of
mode is MAIL)
customerMobile String Mobile no of the customer Yes(in the case of
mode is SMS)
mode String Mode to return the marx ipg Yes
payment url to the customer.
Possible values:WEB,SMS,MAIL
orderSummary String Description of the order Yes
customerReference String Unique reference to identify the Yes
transaction separately
Response Parameter Type Description
status Int Return the status code
message String Return the status message
data Object Return the Marx ipg payment page
url with tr id as a query parameter
Sample request:-
header:{
key: user_secret,
value: $2a$10$x1CAe9YuEz9G1X1ZQrTrLOJXFu2PSvrwLuBcWpgT2ecRAx5sxfOhW,
}
body:{
"merchantRID":"CT2020/09/09/MR0001",
"amount":300.00,
"validTimeLimit":5,
"returnUrl":"https://www.abc.com",
"customerMail":"[email protected]",
"customerMobile":"0763333333",
"mode":"WEB",
"orderSummary":"Order Description",
“customerReference”:”CT2020/09/09/CUST0001”
}
Sample response :-
{
"status": 0,
"message":"Order saved successfully" ,
"data": {
"payUrl": "https://dev.marxpay.com?tr=223"
}
}
Step 02: Redirect the user to the marx payment url
As per the create order response, in the data object there is a variable called payUrl.Merchant
redirect the user to that pay url. There,the user input the card payment details and click the
pay now button.
Step 03: 3Ds Authentication page
Next the user will guide to the bank’s 3Ds authentication page. User has to pass the
authentication process provided by the bank, most probably it will be an OTP verification. (In
the development environment you can get whatever output you like using the ACS emulator.
Just select the response from the combo box)
Step 04: Redirect the user to the merchant return
url
When 3Ds authentication is completed, the user will redirect to the return url which was sent
by the merchant in the first api call (create order in marx). Furthermore, the return url also
includes tr id and merchantRID as query parameters.
Sample redirect url: https://www.abc.com?tr=223&mur=1
Step 05: Check the validity of the query
parameters
Merchant has to check the validity of the tr id and merchantRID which were received as
query parameters by tallying with the values received previously and have to make the
‘Initiate the payment’ request.
Step 06: Initiate the Payment
The API is used to initiate the payment request from the Marx IPG side after verifying the
validity of the Merchant unique reference and Marx unique reference by the Merchant. It is
required to send the merchant secret (which is mailed by Marx when registering the
merchant) in the header of the API call.
URL : https://dev.app.marx.lk/api/v2/ipg/orders/{tr_id}
Method: PUT
Parameter Parameter Data Type Description Mandatory
Type
tr_id Query Long Value of the tr id which was Yes
Parameter return as a query parameter in
‘create order’ request
merchantRID Request String Merchant unique reference id of Yes
parameter the order
Response Parameter Type Description
status Int Return the status code
message String Return the status message
data Object Return an object containing all
details of the transaction.
Sample request :-
header:{
key: user_secret,
value: $2a$10$x1CAe9YuEz9G1X1ZQrTrLOJXFu2PSvrwLuBcWpgT2ecRAx5sxfOhW,
}
body:{
"merchantRID":"CT2020/09/09/MR0001"
}
Sample response :-
{
"status": 0,
"message": "Payment completed successfully",
"data": {
"summaryResult": "SUCCESS",
"gatewayResponse": {
"authorizationResponse": {
"commercialCard": "!01",
"commercialCardIndicator": "0",
"date": "0909",
"posData": "1025100006600",
"posEntryMode": "812",
"processingCode": "000000",
"responseCode": "00",
"returnAci": "Y",
"stan": "88825",
"time": "073729",
"cardSecurityCodeError": "M",
"financialNetworkCode": null,
"transactionIdentifier": null
},
"device": {
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML,
like Gecko) Chrome/85.0.4183.83 Safari/537.36",
"ipAddress": "112.134.151.166"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "0020009",
"order": {
"amount": 1250.5,
"chargeback": {
"amount": 0,
"currency": "LKR"
},
"creationTime": "2020-09-09T07:37:29.552Z",
"currency": "LKR",
"id": "cea0f7e3-d326-4b13-84ed-1eef783dc29b",
"merchantCategoryCode": "5999",
"status": "CAPTURED",
"totalAuthorizedAmount": 1250.5,
"totalCapturedAmount": 1250.5,
"totalRefundedAmount": 0
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"cardSecurityCode": {
"acquirerCode": "M",
"gatewayCode": "MATCH"
},
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "VISA",
"expiry": {
"month": "10",
"year": "22"
},
"fundingMethod": "CREDIT",
"nameOnCard": "H N Binura Salindra",
"number": "424242xxxxxx4242",
"scheme": "VISA",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfRecord": "2020-09-09T07:37:29.564Z",
"transaction": {
"id": "8c904eef-6fbc-43a3-8a35-178c91e85b3a",
"amount": 1250.5,
"authenticationStatus": null,
"authorizationCode": "021221",
"currency": "LKR",
"receipt": "025307088825",
"source": "INTERNET",
"terminal": "0005",
"type": "PAYMENT",
"acquirer": {
"batch": 20200909,
"date": "0909",
"id": "CARGILLSBANK_S2I",
"merchantId": "0020009",
"settlementDate": "2020-09-09",
"timeZone": "+0530",
"transactionId": null
},
"stan": null
},
"version": "54",
"3DSecure": {
"veResEnrolled": "Y",
"xid": "xPKZQJKyUR0vEAwRulkRcxvn2MM="
},
"3DSecureId": "59ae390b-1e55-4db9-ab04-d326b4be4d1a"
}
}
}
Note:- Please skip step 4, step 5 and step 6 if you created the order using marx merchant web
portal. Otherwise these steps are mandatory to complete the payment.
Response Code
Code Description
0 OPERATION SUCCESS
1 OPERATION FAILED
Possible Summary Results
Code Description
FAILURE The operation was declined or rejected by the
gateway, acquirer or issuer.
PENDING The operation is currently in progress or pending
processing.
SUCCESS The operation was successfully processed.
UNKNOWN The result of the operation is unknown.
Possible Gateway Code
Code Description
ABORTED Transaction aborted by payer.
ACQUIRED_SYSTEM_ERROR Acquirer system error occurred processing the
transaction.
APPROVED Transaction Approved.
APPROVED_AUTO The transaction was automatically approved by
the gateway. it was not submitted to the acquirer.
APPROVED_PENDING_SETTLEMENT Transaction Approved - pending batch
settlement.
AUTHENTICATION_FAILED Payer authentication failed.
AUTHENTICATION_IN_PROGRESS The operation determined that payer
authentication is possible for the given card, but
this has not been completed, and requires further
action by the merchant to proceed.
BALANCE_AVAILABLE A balance amount is available for the card, and
the payer can redeem points.
BALANCE_UNKNOWN A balance amount might be available for the
card. Points redemption should be offered to the
payer.
BLOCKED Transaction blocked due to Risk or 3D Secure
blocking rules.
CANCELLED Transaction cancelled by payer.
DECLINED The requested operation was not successful. For
example, a payment was declined by issuer or
payer authentication was not able to be
successfully completed.
DECLINED_AVS Transaction declined due to address verification.
DECLINED_AVS_CSC Transaction declined due to address verification
and card security code.
DECLINED_CSC Transaction declined due to card security code.
DECLINED_DO_NOT_CONTACT Transaction declined - do not contact issuer.
DECLINED_INVALID_PIN Transaction declined due to invalid PIN.
DECLINED_PAYMENT_PLAN Transaction declined due to payment plan.
DECLINED_PIN_REQUIRED Transaction declined due to PIN required.
DEFERRED_TRANSACTION_RECEIV Deferred transaction received and awaiting
ED processing.
DUPLICATE_BATCH Transaction declined due to duplicate batch.
EXCEEDED_RETRY_LIMIT Transaction retry limit exceeded.
EXPIRED_CARD Transaction declined due to expired card.
INSUFFICIENT_FUNDS Transaction declined due to insufficient funds.
INVALID_CSC Invalid card security code.
LOCK_FAILURE Order locked - another transaction is in progress
for this order.
NOT_ENROLLED_3D_SECURE Card holder is not enrolled in 3D Secure.
NOT_SUPPORTED Transaction type not supported.
NO_BALANCE A balance amount is not available for the card.
The payer cannot redeem points.
PARTIALLY_APPROVED The transaction was approved for a lesser amount
than requested. The approved amount is returned
in order.totalAuthorizedAmount.
PENDING Transaction is pending.
REFERRED Transaction declined - refer to issuer.
SUBMITTED The transaction has successfully been created in
the gateway. It is either awaiting submission to
the acquirer or has been submitted to the acquirer
but the gateway has not yet received a response
about the success or otherwise of the payment.
SYSTEM_ERROR Internal system error occurred processing the
transaction.
TIMED_OUT The gateway has timed out the request to the
acquirer because it did not receive a response.
Points redemption should not be offered to the
payer.
UNKNOWN The transaction has been submitted to the
acquirer but the gateway was not able to find out
about the success or otherwise of the payment. If
the gateway subsequently finds out about the
success of the payment it will update the response
code.
UNSPECIFIED_FAILURE Transaction could not be processed.
