1. Overview

The TRAXX Payment Gateway supports card payments, alternative payment methods, hosted checkout, refunds, transaction queries, and recurring payment setup using parameter-based transaction types.

Audience

This document is intended for developers integrating merchant systems with the TRAXX Payment Gateway.

Supported Payment Methods

• Visa
• Mastercard
• Alternative payment methods such as Paynow QR and selected wallets (Apple Pay, Google Pay), where enabled

2. Integration Methods

Please note that successful payments using payment methods such as PayNow and wallets cannot be tested in the sandbox environment. However, you may click the Cancel button to test the redirect flow.

3. Quick Start

Direct Post flow

POST https://sandbox.traxx.sg/api/payment

Hosted Payment Page flow

POST https://sandbox.traxx.sg/hostedpageserver/api/v1/transactions

4. Transaction Types

Availability of each transaction type depends on acquirer support and merchant configuration.

5. Payment Request

Note: All parameter values must be submitted as string data types, unless stated otherwise.

5.1 Common Parameters

5.2 Direct Post

POST (CARD) https://sandbox.traxx.sg/api/payment
POST (QR) https://sandbox.traxx.sg/api/qr

5.3 Hosted Payment Page

POST https://sandbox.traxx.sg/hostedpageserver/api/v1/transactions

For Hosted Payment Page integration, the merchant must not send card number, CVV, or expiry details. The customer enters those details on the TRAXX hosted checkout page after redirect.

6. Payment Response

The payment response contains the transaction result and any next-step instructions.

{
  "transType": "sales",
  "orderNo": "1776751685203",
  "merNo": "2888",
  "terNo": "88816",
  "currencyCode": "SGD",
  "amount": "21.00",
  "tradeNo": "9aa0ada8a798f6de",
  "hashcode": "56a7b4e97d8e0bddcc8cf571bb6b77df47b184591e98b59fb4bd61bffca0b1ae",
  "respCode": "01",
  "respMsg": "pending_async",
  "acquirer": "FS-SGD",
  "settleCurrency": "SGD",
  "settleAmount": "21.00",
  "skipTo3DURL": "https://test.com/gateway/processing;sessionid=574DAA...1Ojg4NDM",
  "merNotifyURL": "https://notify.traxx.sg"
}

Response code summary

7. Return URL

After payment completion, TRAXX redirects the customer browser to the merchant returnURL with payment result parameters appended as query strings.

Merchant handling requirements

• Validate the response signature.
• Check respCode and respMsg.
• Use the Return URL mainly to display the payment result to the customer.
• The final transaction status should be confirmed and updated based on the server-to-server notification sent to merNotifyURL. Refer to 8. Notification URL for instructions on updating payment status.

Sample Return URL:
https://your-return-url.com/?amount=2.00¤cyCode=SGD&hashcode=...&merNo=18888&orderNo=ABC12345&respCode=00&respMsg=success&terNo=88816&tradeNo=9fc4952d74a7db84&transType=sales

8. Notification URL

TRAXX sends asynchronous notifications to the merchant merNotifyURL to report payment results, including recurring payment events where applicable.

Acknowledgement requirement

HTTP/1.1 200 OK
Content-Type: application/json

{
  "merNotifyStatus": "1"
}

Notification Best Practices

Immediate acknowledgement: Merchant systems should return HTTP 200 OK as soon as the notification is received, together with the required acknowledgement JSON response. Any remaining business processing should be performed asynchronously using a queue, worker, or background job.

Returning the acknowledgement immediately helps reduce timeout retries and prevents duplicate notification handling caused by delayed responses.

Timeout and retry behaviour

• The acknowledgement timeout is currently set to 20 seconds.
• If acknowledgement is not received within the timeout window, the retry mechanism is triggered automatically.
• Merchant systems should process notifications idempotently to prevent duplicate updates.
• If the notification endpoint is unavailable, stopped, or under maintenance, the system may retry the notification up to 4 attempts.
• Multiple notifications for the same transaction can therefore occur when acknowledgements time out or fail.

Idempotency and duplicate handling

Merchant systems must implement duplicate checking when processing payment notifications. Use both orderNo and tradeNo as references.

tradeNo is unique per transaction. If multiple notifications are received with the same orderNo and tradeNo, they should be treated as duplicate notifications and must not result in duplicate records being created. This is particularly important for subsequent recurring payment notifications, where retry mechanisms may resend the same notification if the initial notification does not receive acknowledgement within the configured timeout period.

Operational recommendation

• Do not wait for all internal processing to finish before returning HTTP 200.
• Make notification processing idempotent.
• Log and reconcile retries using both orderNo and tradeNo.

9. Signature Generation

The hashKey is a secret key provided by TRAXX. It must be kept confidential and never exposed on the frontend.

All signatures must be generated using the SHA256 hashing algorithm.

General Rules

• Parameters must be concatenated in the exact order specified.
• Use & between each key-value pair.
• Append the hashKey at the end.
• Do not include extra spaces.
• Parameter names are case-sensitive.
• The final hash output must be represented as a lowercase hexadecimal SHA256 string.

9.1 Request Signature

Concatenate the following fields in exact order:

EncryptionMode=SHA256
CharacterSet={CharacterSet}
merNo={merNo}
terNo={terNo}
orderNo={orderNo}
currencyCode={currencyCode}
amount={amount}
payIP={payIP}
transType={transType}
transModel={transModel}
{hashKey}

Step-by-step process

1. Concatenate all parameters using &.
2. Append the hashKey at the end.
3. Apply SHA256 hashing.
4. Convert output to lowercase hexadecimal.

Example string before hashing

EncryptionMode=SHA256&CharacterSet=UTF8&merNo=168&terNo=88816&orderNo=109116361045¤cyCode=USD&amount=98.99&payIP=127.0.0.1&transType=sales&transModel=M&fb5677a2f9ab4c02a232d018b1eddfd6

After applying SHA256 hashing to the above string, the resulting value becomes the hashcode sent in the payment request.

9.2 Response and Notification Signature

Merchants must validate the response and notification signature to confirm that the data originated from TRAXX.

Concatenate the following fields in exact order:

amount={amount}
currencyCode={currencyCode}
merNo={merNo}
orderNo={orderNo}
respCode={respCode}
respMsg={respMsg}
terNo={terNo}
tradeNo={tradeNo}
transType={transType}
{hashKey}

Verification process

1. Concatenate the received parameter values.
2. Append the hashKey.
3. Apply SHA256 hashing.
4. Compare the generated hash with the received signature.
5. If values match → response is valid.
6. If values do not match → reject the response.

Important Notes

• The hash must follow the documented field order exactly.
• Always use the exact parameter values received or sent.
• Any mismatch in order, value, or format will result in signature failure.
• Signature validation is mandatory before updating payment status.

10. Refund

Endpoint

POST https://sandbox.traxx.sg/refund/doRefund

Request fields

{
  "merNo": "28888",
  "terNo": "28888",
  "tradeNo": "28888",
  "busAmount": "28888",
  "busCurrency": "28888",
  "refundAmount": "28888",
  "refundCurrency": "28888",
  "refundReason": "28888",
  "hashCode": "28888"
}

Response fields

{
  "merNo": "28888",
  "terNo": "28888",
  "tradeNo": "28888",
  "busAmount": "28888",
  "busCurrency": "28888",
  "refundAmount": "28888",
  "refundCurrency": "28888",
  "refundReason": "28888",
  "hashCode": "28888"
}

11. Query Transactions

Endpoint

POST https://sandbox.traxx.sg/external/query

Request fields

Example: 

Response fields

Example: 

12. Payment Method Identification

For Hosted Payment Page integrations where multiple payment methods are available, the merchant should submit the initial payment request using the primary terminal credentials provided for the checkout initiation request.

Initial request behaviour

• Use the primary terminal credentials in the initial payment request.
• At the point of request creation, the merchant does not yet know which payment method the payer will choose.
• The hosted payment page then presents the enabled payment methods to the payer.

Callback verification behaviour

Additional terminal credentials may be issued for specific payment methods such as PayNow, Google Pay, or Apple Pay. These credentials are not used to create the initial hosted payment page request. Instead, they are used to identify and verify the actual payment method used based on the API response or notification callback.

Example: if terminal IDs such as 88836, 88846, or 88856 are issued for specific payment methods, those values are used for callback interpretation and payment method tracking, not for the initial hosted page request.

13. Recurring Payments

Recurring payments are set up using the first successful payment transaction. The initial recurring setup payment must be submitted using transType=subscribe.

13.1 Recurring Payment Flow

13.2 Recurring Bill Date Rules

The next recurring charge date is determined based on the merchant's configured recurring day, where applicable. If no recurring day has been configured, the recurring charge date will default to one month from the initial payment date.

13.3 How the Merchant Is Notified

When a subsequent recurring payment is triggered, the merchant will be notified through the same notification callback flow used for other payment notifications.

The notification will be sent to the merchant's merNotifyURL, and the orderNo in the notification will remain the same as the original recurring setup transaction.

13.4 Best Practices

• Store the original orderNo from the first recurring setup transaction for reconciliation.
• Verify the notification signature before updating any payment status.
• Return HTTP 200 OK with the required acknowledgement JSON as soon as the notification is received.
• Process recurring notifications idempotently to prevent duplicate records in case of retries.

13.5 Example Summary

13.6 Stopping Recurring Payments

Termination Process

Merchants must submit a termination request manually using the Recurring Termination Request Form (template to be provided) when recurring payments are no longer required. The completed form should be sent to support@traxx.asia for processing.

Important Notes

• Recurring payments will continue to be triggered according to the configured billing cycle until the termination request has been processed.
• Merchants should submit termination requests in advance of the next billing cycle to avoid unintended charges.
• Termination requests are typically processed within 1-2 working days.
• Once termination is completed, no further recurring charges will be generated for the specified orderNo.

14. Live-Proofing and Go-Live Notes

Before Go-Live

Before proceeding to production, the merchant will receive the following credentials and configuration details from TRAXX.

• Provide the production server IP address for whitelisting.
• Configure the production credentials in the merchant environment.
• Complete transaction testing and record the results in the required live-proofing sheet.
• TRAXX will review the submitted test results before lifting transaction restrictions and enabling normal live processing.

Testing notes

• During pre-production or live-proofing, each test transaction may be subject to a maximum amount limit, depending on merchant setup.
• Where instructed, test transactions should not exceed $20.00 per transaction.
• Live test transactions should generally be kept to at least $2.00 to avoid reporting issues.

Recommended merchant checklist