DocumentationRecipesAPI ReferenceChangelog
Documentation

Payment

The Payment API allows merchants to accept contactless credit and debit card payments via compatible NFC-enabled devices.

📘

API Method

SoftPOS SDK API Interface

🚧

References

SDK Payment Classes
SDK Payment Enums


1. Generate Payment Token

To prepare a payment token request, refer to the required parameters below.

📘

Payment Token API

Refer to: Payment Token API

{
    "merchantID": "JT04",
    "invoiceNo": "1595219400",
    "description": "2 days 1 night hotel room",
    "amount": 10.0,
    "currencyCode": "THB",
    "nonceStr": "a8092512-b144-41b0-8284-568bb5e9264c",
    "paymentChannel": ["ALL"]
}

2. Receive Payment Token Response

To receive a payment token response, refer to the sample payment token response below. The response will contain the payment token ID which must be passed to the merchant application.

String paymentToken = "roZG9I1hk/GYjNt+BYPYbxQtKElbZDs9M5cXuEbE+Z0QTr/yUcl1oG7t0AGoOJlBhzeyBtf5mQi1UqGbjC66E85S4m63CfV/awwNbbLbkxsvfgzn0KSv7JzH3gcs/OIL";
val paymentToken = "roZG9I1hk/GYjNt+BYPYbxQtKElbZDs9M5cXuEbE+Z0QTr/yUcl1oG7t0AGoOJlBhzeyBtf5mQi1UqGbjC66E85S4m63CfV/awwNbbLbkxsvfgzn0KSv7JzH3gcs/OIL"

3. Prepare Payment Request

To prepare a payment request, refer to the parameters below.

📘

Request API Parameters

Refer to: Payment Request API Parameters

String profileId = "prof_01XXXXXXXXXXX1";

PaymentRequest paymentRequest = new PaymentBuilder(getActivity(), paymentToken)
                                .profileId(profileId)
                                .posType(SoftPOSType.Terminal)
                                .build();
val profileId = "prof_01JQB8Y9EMCRBG27NWXXXCRNA1"

val paymentRequest = PaymentBuilder(activity, paymentToken)
                     .profileId(profileId)
                     .posType(SoftPOSType.Terminal)
                     .build()

4. Receive Payment Response

To receive a payment response, refer to the parameters below.

📘

Response API Parameters

Refer to: Payment Response API Parameters

SoftPOSSDK.getInstance().pay(paymentRequest, new PaymentResultResponseCallback<SoftPOSPaymentResultResponse>() {

     @Override
     public void onResponse(SoftPOSPaymentResultResponse response) {

         if (response.getResponseCode().equals(SoftPOSPaymentResponseCode.PaymentSuccess)) {  
           
             //Read payment response. 
         } else {
 
             //Get error response and display error.
         }
     }

     @Override
     public void onFailure(@NonNull Throwable error) {

         //Get error response and display error.
     }
});
SoftPOSSDK.getInstance().pay(paymentRequest, object : PaymentResultResponseCallback<SoftPOSPaymentResultResponse> {
                             
      override fun onResponse(response: SoftPOSPaymentResultResponse) {
  
            if (response.equals(SoftPOSPaymentResponseCode.PaymentSuccess)) {
                
                  //Read payment response.
            } else {
 
                  //Get error response and display error.
            }
      }

      override fun onFailure(error: Throwable) {
          
            //Get error response and display error.
      }
})

 
The following shows a sample response in the message parameter that is returned in SoftPOSResult:

{
    "tranId": "tran_01K1W4DY3FXH7G8SZMXQSNG6M5",
    "tranType": "{SALE, REFUND, AUTH}",
    "tranStatus": "{PROCESSING, APPROVED, DECLINED, VOIDED, REVERSED, AUTH_ONLY, ADJUSTED}",
    "amount": {
        "value": "1.00",
        "currency": "SGD"
    },
    "paymentMethod": "VISA",
    "entryMode": "NFC",
    "accountMasked": "411111******1111",
    "accountBin": "411111",
    "accountLast4": "1111",
    "issCountryCode": "0702",
    "cvmPerformed": "{NO_CVM, SIGNATURE, PIN, CDCVM}",
    "cvmSignatureUrl": null,
    "cvmSignatureBase64": null,
    "aid": "a0000000031010",
    "appName": "Visa Credit",
    "tc": "9d33108efe8b7c47",
    "tvr": "0000000000",
    "tsi": "0000",
    "atc": "0018",
    "profileId": "{YOUR_PROFILE_ID}",
    "acceptanceId": "acpt_01JQBJ31YYRVTYZTWPNC9276Q7",
    "acptId": "acpt_01JQBJ31YYRVTYZTWPNC9276Q7",
    "sdkId": "32587546edd67f5b",
    "posReference": "2805250901908",
    "trace": "022293",
    "merchantName": "{YOUR_MERCHANT_NAME}",
    "merchantAddr": "{YOUR_MERCHANT_ADDRESS}",
    "mcc": "-",
    "primaryMid": "{YOUR_MERCHANT_MID}",
    "primaryTid": "{YOUR_MERCHANT_TID}",
    "subMid": "702702000004191",
    "subTid": "0098402",
    "hostMessageFormat": "CARD_NOW",
    "providerReference": "ms_314920883496",
    "providerMchId": "{PROVIDER_MERCHANT_ID}",
    "extraData": "{\"paymentToken\":\"{YOUR_PAYMENT_TOKEN}\",\"clientIp\":\"{YOUR_CLIENT_IP}\"}",
    "rrn": "250805112933",
    "approvalCode": "112933",
    "batchId": "batch_01K1W3KB5CC9A394KT44SMXJSA",
    "batchNo": "003969",
    "actions": [
        {
            "actionId": "act_01K1W4DY3FMMPZB29TTEABV3JR",
            "trace": "022293",
            "actionType": "{NEW, ADJUST, VOID, AUTH_COMP}",
            "actionStatus": "{PROCESSING, SUCCESS, REJECTED, TIMEOUT, REVERSED, TO_BE_REVERSED}",
            "requestId": "req_01K1W4DMBZS5BDR6YQ7CYCT806",
            "amount": {
                "value": "1.00",
                "currency": "SGD"
            },
            "tranId": "tran_01K1W4DY3FXH7G8SZMXQSNG6M5",
            "reason": "HostSuccess",
            "hostRespCode": "00",
            "posReference": "{YOUR_INVOICE_NUMBER}",
            "extraData": "{\"paymentToken\":\"{YOUR_PAYMENT_TOKEN}\",\"clientIp\":\"{YOUR_CLIENT_IP}\"}",
            "createdAt": "2025-08-05T03:29:33.818Z"
        }
    ],
    "srsTranId": "M1952572659856105473",
    "consumerPaymentDevice": "Card",
    "createdAt": "2025-08-05T03:29:33.813Z"
}

Full Sample Code

The following sample code demonstrates requests and parameters for each step of the process.

//Step 1: Generate payment token.
String paymentToken = "roZG9I1hk/GYjNt+BYPYbxQtKElbZDs9M5cXuEbE+Z0QTr/yUcl1oG7t0AGoOJlBhzeyBtf5mQi1UqGbjC66E85S4m63CfV/awwNbbLbkxsvfgzn0KSv7JzH3gcs/OIL";
 
//Step 2: Construct payment request.
String profileId = "prof_01XXXXXXXXXXX1";

PaymentRequest paymentRequest = new PaymentBuilder(getActivity(), paymentToken)
                                .profileId(profileId)
                                .posType(SoftPOSType.Terminal)
                                .build();
 
//Step 3: Retrieve payment response.
SoftPOSSDK.getInstance().pay(paymentRequest, new PaymentResultResponseCallback<SoftPOSPaymentResultResponse>() {

     @Override
     public void onResponse(SoftPOSPaymentResultResponse response) {

         if (response.getResponseCode().equals(SoftPOSPaymentResponseCode.PaymentSuccess)) {  
           
             //Read payment response. 
         } else {
 
             //Get error response and display error.
         }
     }

     @Override
     public void onFailure(@NonNull Throwable error) {

         //Get error response and display error.
     }
});
//Step 1: Generate payment token.
val paymentToken = "roZG9I1hk/GYjNt+BYPYbxQtKElbZDs9M5cXuEbE+Z0QTr/yUcl1oG7t0AGoOJlBhzeyBtf5mQi1UqGbjC66E85S4m63CfV/awwNbbLbkxsvfgzn0KSv7JzH3gcs/OIL"
 
//Step 2: Construct payment request.
val profileId = "prof_01JQB8Y9EMCRBG27NWXXXCRNA1"

val paymentRequest = PaymentBuilder(activity, paymentToken)
                     .profileId(profileId)
                     .posType(SoftPOSType.Terminal)
                     .build()
 
//Step 3: Retrieve payment response.
SoftPOSSDK.getInstance().pay(paymentRequest, object : PaymentResultResponseCallback<SoftPOSPaymentResultResponse> {
                             
      override fun onResponse(response: SoftPOSPaymentResultResponse) {
  
            if (response.equals(SoftPOSPaymentResponseCode.PaymentSuccess)) {
                
                  //Read payment response.
            } else {
 
                  //Get error response and display error.
            }
      }

      override fun onFailure(error: Throwable) {
          
            //Get error response and display error.
      }
})