Getting started
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.
To initiate the integration process, your KYC details must first be verified by our support team.
Once verified, you will receive your Merchant API key along with other integration methods and documentation.
Please ensure that this information is kept strictly confidential.
For any assistance regarding your merchant account, visit our website at marx.lk or contact us at support@marx.lk. Our support team is here to guide you through every step of the integration process.
1. Creating an order in Marx IPG
INTRODUCTION
This is the first API call for creating an order request.
The Order Request API allows merchants to create order requests in Marx IPG (Internet Payment Gateway) on behalf of their customers. Upon successful request, Marx IPG provides a payment URL, which customers can use to make payments.
Payment Methods
- OTHER: Merchants can use this option to collect payments made via VISA, MasterCard, or UnionPay credit or debit cards. Transaction currency is LKR.
- AMEX: This method is used when merchants want to collect payments made with American Express, Discover, or Diners Club credit or debit cards. Transaction currency is LKR.
- OTHER_USD: Merchants can use this option to collect payments made via VISA, MasterCard, or UnionPay credit or debit cards. Transaction currency is USD.
- AMEX_USD: This method is used when merchants want to collect payments made with American Express, Discover, or Diners Club credit or debit cards. Transaction currency is USD.
- PAY_BY_BANK_ACCOUNT: This method is used when merchants want to collect payments made with bank account.
Create An Order In Marx IPG Sample Request :
{
header:{
key: merchant-api-key,
value: $2a$10$x1CAe9YuEz9G1X1ZQrTrLOJXFu2PSvrwLuBcWpgT2ecRAx5sxfOhW,
}
body:{
"merchantRID": "20231023003",
"amount": 230.00,
"validTimeLimit": 2,
"returnUrl": "https://samplemerchant.com/payment-result.html",
"customerMail": "jamessmith@example.com",
"customerMobile": "94771234567",
"orderSummary": "Order Description",
"customerReference": "James Smith",
"paymentMethod": "AMEX"
}
}
Create An Order In Marx IPG 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"
}
API Details
| Sandbox URL | https://payment.api.dev.marxpos.com/api/v4/ipg/orders |
| Production URL | https://payment.v4.api.marx.lk/api/v4/ipg/orders |
| HTTP Method | POST |
| Request Format | JSON |
| Success Response Code | 200 OK |
REQUEST HEADERS
| Parameter | Description | Mandatory |
|---|---|---|
| merchant-api-key | It is required to send the merchant secret (which is mailed by Marx when registering the merchant) in the header of the API call. | Yes |
Request Parameters
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| merchantRID | String | Merchant unique reference id of the order (This can’t be duplicated). | Yes |
| amount | Decimal | Merchant unique reference id of the order (This can’t be duplicated). | Yes |
| validTimeLimit | Integer | Time limit of the transaction to proceed (in hours). | Yes |
| returnUrl | String | Url of the page to display payment result. | Yes |
| customerMail | String | Mail address of the customer. | Yes |
| customerMobile | String | Mobile no of the customer. | No |
| orderSummary | String | Description of the order. | Yes |
| customerReference | String | Unique reference to identify the transaction separately. | Yes |
| paymentMethod | String | Merchants must specify the payment method. Possible values: OTHER, AMEX, OTHER_USD, AMEX_USD, PAY_BY_BANK_ACCOUNT |
Yes |
Response Parameters
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| status | Integer | Return the status code | yes |
| message | String | Return the status message | yes |
| data | Object | Return an object containing all details of the transaction. | yes |
2.1. Redirect The User To The Marx Payment Url
INTRODUCTION
Upon successful order creation within the marx IPG ecosystem, the response will contain a crucial element known as the 'payUrl' variable, nested within the data object. Merchants are required to redirect the end user to this specified pay URL. Once redirected, the user is prompted to enter their card payment details and subsequently initiate the payment process by clicking the 'Pay Now' button.
2.2. 3Ds Authentication page
INTRODUCTION
Next, the user will be directed to the bank's 3D Secure (3DS) authentication page.
The user must successfully complete the authentication process as provided by the credit/debit card issuing bank, which typically
involves OTP (One-Time Password) verification to verify the card user.
Please Note : In the sandbox development environment,
you can simulate various responses using the ACS (Access Control Server) emulator.
Simply select the desired response from the combo box to replicate different authentication scenarios.
2.3. Redirect The User To The Merchant Return Url
INTRODUCTION
After successfully completing the 3D Secure (3DS) authentication, the user will be automatically redirected to the return URL specified by the merchant in the initial API call, which is typically the '1. Create An Order in Marx IPG' request. The return URL also includes two important query parameters: 'trId' and 'merchantRID'. These parameters provide crucial information for tracking and processing the transaction.
Sample Redirect URL:
https://merchant-return-url?trId=5057&merchantRID=20231023003
- trId (Transaction ID provided by Marx):This parameter contains a unique identifier associated with the transaction, allowing you to retrieve and reference specific transaction details.
- merchantRID (Merchant Request ID):This parameter represents the unique identifier provided by the merchant, enabling you to associate the transaction with the corresponding merchant request.
3. Check The Validity Of The Query Parameters
INTRODUCTION
To facilitate the initiation of a payment request within the API, merchants are required to perform a validation check on the 'trId' and 'merchantRID' query parameters. These parameters should be cross-referenced with previously received values. Once the validation is successfully completed, the merchant can proceed to trigger the '4. Initiate the Payment' request. This step ensures the security and accuracy of the payment initiation process.
4. Initiate the Payment
INTRODUCTION
The Payment Request Initiation API facilitates the initiation of payment requests through the marx IPG. This API allows merchants to seamlessly request payments from their customers, with the payment amount deducted upon successful transactions. To ensure a smooth transaction process, it is essential for merchants to do the step '3. Check The Validity Of The Query Parameters'
Please Note: That the payment amount will only be deducted for payments successfully verified with 3DS (3D Secure) process only.
Initiate The Payment Sample Request :
{
header:{
key: merchant-api-key,
value: $2a$10$x1CAe9YuEz9G1X1ZQrTrLOJXFu2PSvrwLuBcWpgT2ecRAx5sxfOhW,
}
body:{
"merchantRID":"20231023003"
}
}
Initiate The Payment Sample Response :
{
"status": 0,
"message": "SUCCESS",
"data": {
"summaryResult": "SUCCESS",
"trId": 5057,
"merchantRID": "20231023003",
"gatewayResponse": {
"authorizationResponse": {
"commercialCard": null,
"commercialCardIndicator": null,
"date": null,
"posData": "1025100006600",
"posEntryMode": "812",
"processingCode": "003000",
"responseCode": "00",
"returnAci": null,
"stan": "218470",
"time": null,
"cardSecurityCodeError": "M",
"financialNetworkCode": null,
"transactionIdentifier": "123456789012345"
},
"device": {
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36",
"ipAddress": "112.134.116.166"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TEST9170076111",
"order": {
"amount": 230.00,
"chargeback": {
"amount": 0,
"currency": "LKR"
},
"creationTime": "2023-10-23T17:06:38.601Z",
"currency": "LKR",
"id": "6a716db1-ee47-4ef5-8e50-e502d0f6d276",
"merchantCategoryCode": "7399",
"status": "CAPTURED",
"totalAuthorizedAmount": 230.00,
"totalCapturedAmount": 230.00,
"totalRefundedAmount": 0.00
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"cardSecurityCode": {
"acquirerCode": "M",
"gatewayCode": "MATCH"
},
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"nameOnCard": "James Smith",
"number": "345678xxxxx4564",
"scheme": "AMEX",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfRecord": "2023-10-23T17:09:47.425Z",
"transaction": {
"id": "c681771c-b872-4155-8591-21c7a593a6da",
"amount": 230.00,
"authenticationStatus": "AUTHENTICATION_NOT_SUPPORTED",
"authorizationCode": "218470",
"currency": "LKR",
"receipt": "329617218470",
"source": "INTERNET",
"terminal": "MLK4",
"type": "PAYMENT",
"acquirer": {
"batch": 20231023,
"date": "1023",
"id": "NTB_S2I",
"merchantId": "9170076111",
"settlementDate": "2023-10-23",
"timeZone": "+0530",
"transactionId": "123456789012345"
},
"stan": "218470"
},
"version": "62",
"3DSecure": null,
"3DSecureId": null
}
}
}
API Details
| Sandbox URL | https://payment.api.dev.marxpos.com/api/v4/ipg/orders/{trId} |
| Production URL | https://payment.v4.api.marx.lk/api/v4/ipg/orders/{trId} |
| HTTP Method | PUT |
| Request Format | JSON |
| Success Response Code | 200 OK |
REQUEST HEADERS
| Parameter | Description | Mandatory |
|---|---|---|
| merchant-api-key | It is required to send the merchant secret (which is mailed by Marx when registering the merchant) in the header of the API call. | Yes |
URL PARAMETERS
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| {trId} | Integer | Value of the trId which was return as a response parameter in '1. Create An Order In
Marx IPG' request. (This parameter contains a unique identifier associated with the transaction, allowing you to retrieve and reference specific transaction details.) |
Yes |
Request Parameters
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| merchantRID | String | Merchant unique reference ID for the order, which was initially used by the merchant during the order creation process in Marx ('1. Create An Order In Marx IPG') | Yes |
Response Parameters
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| status | Integer | Return the status code | yes |
| message | String | Return the status message | yes |
| data | Object | Return an object containing all details of the transaction. | yes |
5. Retrieve Order Summary
INTRODUCTION
The Retrieve Order Summary API is designed to allow merchants to efficiently check the status and summary of their orders. Merchants can use this API to retrieve essential information about their transactions. To process this API, merchants need to provide the unique transaction ID ('trId') generated by marx IPG during the order creation process ('1. Create An Order In Marx IPG').
Retrieve Order Summary Sample Request :
{
header:{
key: merchant-api-key,
value: $2a$10$x1CAe9YuEz9G1X1ZQrTrLOJXFu2PSvrwLuBcWpgT2ecRAx5sxfOhW,
}
}
Retrieve Order Summary Sample Response :
{
"status": 0,
"message": "SUCCESS",
"data": {
"summaryResult": "SUCCESS",
"trId": 5057,
"merchantRID": "20231023003",
"order": {
"trId": 5057,
"merchantRID": "20231023003",
"amount": 230.00,
"status": "SUCCESS",
"mode": "WEB",
"paymentMethod": "AMEX",
"returnUrl": "https://samplemerchant.com/payment-result.html",
"orderSummary": "Order Description",
"customerMail": "jamessmith@example.com",
"customerMobile": "94771234567",
"customerReference": "James Smith",
"createdDateTime": "2023-10-23T17:03:13.000+0000",
"validTimeLimit": 2,
"expiryDateTime": "2023-10-23 19:04:13",
"merchantId": 109,
"ipgAPIVersion": "V3"
},
"gatewayResponse": {
"authorizationResponse": {
"commercialCard": null,
"commercialCardIndicator": null,
"date": null,
"posData": "1025100006600",
"posEntryMode": "812",
"processingCode": "003000",
"responseCode": "00",
"returnAci": null,
"stan": "218470",
"time": null,
"cardSecurityCodeError": "M",
"financialNetworkCode": null,
"transactionIdentifier": "123456789012345"
},
"device": {
"browser": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/118.0.0.0 Safari/537.36",
"ipAddress": "112.134.116.166"
},
"gatewayEntryPoint": "WEB_SERVICES_API",
"merchant": "TEST9170076111",
"order": {
"amount": 230.0,
"chargeback": {
"amount": 0,
"currency": "LKR"
},
"creationTime": "2023-10-23T17:06:38.601Z",
"currency": "LKR",
"id": "6a716db1-ee47-4ef5-8e50-e502d0f6d276",
"merchantCategoryCode": "7399",
"status": "CAPTURED",
"totalAuthorizedAmount": 230.0,
"totalCapturedAmount": 230.0,
"totalRefundedAmount": 0.0
},
"response": {
"acquirerCode": "00",
"acquirerMessage": "Approved",
"cardSecurityCode": {
"acquirerCode": "M",
"gatewayCode": "MATCH"
},
"gatewayCode": "APPROVED"
},
"result": "SUCCESS",
"sourceOfFunds": {
"provided": {
"card": {
"brand": "AMEX",
"expiry": {
"month": "1",
"year": "39"
},
"fundingMethod": "CREDIT",
"nameOnCard": "James Smith",
"number": "345678xxxxx4564",
"scheme": "AMEX",
"storedOnFile": "NOT_STORED"
}
},
"type": "CARD"
},
"timeOfRecord": "2023-10-23T17:09:47.425Z",
"transaction": {
"id": "c681771c-b872-4155-8591-21c7a593a6da",
"amount": 230.0,
"authenticationStatus": "AUTHENTICATION_NOT_SUPPORTED",
"authorizationCode": "218470",
"currency": "LKR",
"receipt": "329617218470",
"source": "INTERNET",
"terminal": "MLK4",
"type": "PAYMENT",
"acquirer": {
"batch": 20231023,
"date": "1023",
"id": "NTB_S2I",
"merchantId": "9170076111",
"settlementDate": "2023-10-23",
"timeZone": "+0530",
"transactionId": "123456789012345"
},
"stan": "218470"
},
"version": "62",
"3DSecure": null,
"3DSecureId": null
}
}
}
API Details
| Sandbox URL | https://payment.api.dev.marxpos.com/api/v4/ipg/orders/{trId}/summary |
| Production URL | https://payment.v4.api.marx.lk/api/v4/ipg/orders/{trId}/summary |
| HTTP Method | GET |
| Request Format | JSON |
| Success Response Code | 200 OK |
REQUEST HEADERS
| Parameter | Description | Mandatory |
|---|---|---|
| merchant-api-key | It is required to send the merchant secret (which is mailed by Marx when registering the merchant) in the header of the API call. | Yes |
URL PARAMETERS
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| {trId} | Integer | Value of the trId which was return as a response parameter in '1. Create An Order In
Marx IPG' request. (This parameter contains a unique identifier associated with the transaction, allowing you to retrieve and reference specific transaction details.) |
Yes |
Response Parameters
| Parameter | Type | Description | Mandatory |
|---|---|---|---|
| status | Integer | Return the status code | yes |
| message | String | Return the status message | yes |
| data | Object | Return an object containing all details of the transaction. | yes |
Response Codes
The marx IPG Integration API uses the following response codes and results:
Status 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_RECEIVED | Deferred transaction received and awaiting 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. |