Marx IPG Integration Guide

Welcome to the Marx Internet Payment Gateway (IPG) API Integration Guide. This comprehensive guide provides step-by-step instructions for merchants looking to seamlessly integrate the Marx IPG into their platforms, ensuring secure and efficient online payment processing.

Prerequisites

Your KYC details must be verified by our support team.
Once verified, you will receive your Merchant API Key.
Keep your API Key strictly confidential.

Sandbox URL https://payment.api.dev.marxpos.com/api/v4/ipg/

Production https://payment.v4.api.marx.lk/api/v4/ipg/

Authentication

It is required to send the merchant secret (emailed by Marx upon registration) in the header of every API call.

merchant-api-key: YOUR_SECRET_KEY

Step 1

Creating an order in Marx IPG

The Order Request API allows merchants to create order requests in Marx IPG on behalf of their customers. Upon successful request, Marx IPG provides a payment URL.

POST /orders

Supported Payment Methods

OTHER: VISA, MasterCard, UnionPay (LKR)
AMEX: American Express, Discover, Diners Club (LKR)
OTHER_USD: VISA, MasterCard, UnionPay (USD)
AMEX_USD: American Express, Discover, Diners Club (USD)
PAY_BY_BANK_ACCOUNT: Direct bank account payment

Request Parameters

Parameter	Type	Required	Description
merchantRID	String	Yes	Unique reference ID of the order (Cannot be duplicated).
amount	Decimal	Yes	Amount of the transaction.
validTimeLimit	Integer	Yes	Time limit of the transaction to proceed (in hours).
returnUrl	String	Yes	Url of the page to display payment result.
customerMail	String	Yes	Mail address of the customer.
customerMobile	String	No	Mobile no of the customer.
orderSummary	String	Yes	Description of the order.
customerReference	String	Yes	Unique reference to identify the transaction separately.
paymentMethod	String	Yes	The chosen payment method string.

Sample Request

{
  "merchantRID": "20231023003",
  "amount": 230.00,
  "validTimeLimit": 2,
  "returnUrl": "https://samplemerchant.com/payment-result.html",
  "customerMail": "[email protected]",
  "customerMobile": "94771234567",
  "orderSummary": "Order Description",
  "customerReference": "James Smith",
  "paymentMethod": "AMEX"
}

Sample Response

{
  "status": 0,
  "message": "SUCCESS",
  "data": {
    "payUrl": "https://ipg.dev.marxpos.com/?tr=5057",
    "trId": 5057,
    "merchantRID": "20231023003"
  },
  "timestamp": "2025-04-08T10:04:15Z"
}

Step 2

Redirect User & 3DS

2.1

Redirect to Payment URL

Extract the payUrl from the response in Step 1. Redirect the user's browser to this URL. The user is prompted to enter their card payment details.

2.2

3DS Authentication Page

The user will be directed to the bank's 3D Secure (3DS) authentication page (usually OTP verification).

Sandbox Note: In the dev environment, use the ACS emulator to simulate responses without real OTPs by selecting the desired outcome from the combo box.

2.3

Redirect The User To The Merchant Return Url

After completing 3DS authentication, the user is redirected back to your returnUrl specified in Step 1. This URL will include two important query parameters: trId and merchantRID.


                                https://merchant-return-url?trId=5057&merchantRID=20231023003

Step 3

Check Validity of Query Parameters

To facilitate the initiation of a payment request, merchants are required to perform a validation check on the trId and merchantRID query parameters received in the return URL.

These parameters should be cross-referenced with your previously saved database values. Once validation is successfully completed, you can proceed to trigger the Step 4 request.

Step 4

Initiate the Payment

Please Note: The payment amount will ONLY be deducted after this API call is successfully executed.

PUT /orders/{trId}

URL & Request Parameters

Parameter	Location	Required	Description
trId	URL Path	Yes	Value of the `trId` returned as a query parameter.
merchantRID	JSON Body	Yes	Merchant unique reference ID for the order.

Request Body

{
  "merchantRID": "20231023003"
}

Success Response

{
  "status": 0,
  "message": "SUCCESS",
  "data": {
    "summaryResult": "SUCCESS",
    "trId": 5057,
    "merchantRID": "20231023003",
    "gatewayResponse": {
       "order": {
          "status": "CAPTURED",
          "totalCapturedAmount": 230.00
       },
       "response": {
          "gatewayCode": "APPROVED"
       }
    }
  }
}

Step 5

Retrieve Order Summary

The Retrieve Order Summary API is designed to allow merchants to efficiently check the status and summary of their transactions using the unique trId.

GET /orders/{trId}/summary

Response Example

{
  "status": 0,
  "message": "SUCCESS",
  "data": {
    "summaryResult": "SUCCESS",
    "trId": 5057,
    "merchantRID": "20231023003",
    "order": {
      "amount": 230.00,
      "status": "SUCCESS",
      "paymentMethod": "AMEX",
      "customerMail": "[email protected]",
      "validTimeLimit": 2
    }
  }
}

Reference: Response Codes

1. Top-Level Status Codes

0	OPERATION SUCCESS
1	OPERATION FAILED

2. Summary Results

SUCCESS	The operation was successfully processed.
PENDING	The operation is currently in progress or pending.
FAILURE	The operation was declined or rejected.
UNKNOWN	The result of the operation is unknown.

3. Gateway Codes

ABORTED	Transaction aborted by payer.
ACQUIRED_SYSTEM_ERROR	Acquirer system error occurred processing the transaction.
APPROVED	Transaction Approved.
APPROVED_AUTO	Automatically approved by gateway (not submitted to acquirer).
APPROVED_PENDING_SETTLEMENT	Transaction Approved - pending batch settlement.
AUTHENTICATION_FAILED	Payer authentication failed.
AUTHENTICATION_IN_PROGRESS	Authentication possible but not completed, requires action.
BALANCE_AVAILABLE	A balance amount is available, payer can redeem points.
BALANCE_UNKNOWN	Balance might be available.
BLOCKED	Transaction blocked due to Risk or 3D Secure rules.
CANCELLED	Transaction cancelled by payer.
DECLINED	Requested operation not successful (declined by issuer).
DECLINED_AVS	Declined due to address verification.
DECLINED_AVS_CSC	Declined due to address verification and CSC.
DECLINED_CSC	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_RECEIVED	Deferred transaction received, awaiting processing.
DUPLICATE_BATCH	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 in progress.
NOT_ENROLLED_3D_SECURE	Card holder is not enrolled in 3D Secure.