Payment

Last updated: August 1, 2026  |  Guide version: 1.0.8

Used to make a payment transaction. Supported transaction types are Sale, Void and Refund. If a payment request also consists of RegisterParameters, the registration process will be executed using the given values in case the current registered terminal does not match the provided one. The merchant (sales) app does not need to add register parameters if registration has already been completed with those credentials (MID, TID, Activation Code).

Amounts are in minor units. The amount field is always expressed in the currency's minor unit (cents) in every request and response. E.g. to charge 1,000.00 COP, send 100000, not 1000. Sending the amount in whole currency units will cause the processed amount to be 100x smaller than intended.

Transaction types

Code Meaning
200 Sales
300 Refund
400 Void
604 Tokenization

Payment parameters

Parameter Description Example
amount Amount for payment, expressed in the currency's minor unit (cents) 100000 (= 1,000.00)
orderId Client reference id for transaction 9bda71c6-a4b1-414b-97ec-5d36873216f2
transactionId txnID for original transaction (only for void or refund txn requests) 300001231240
transactionType Transaction type indicator, see Transaction types 200

Call example

PaymentParameters paymentParameters = new PaymentParameters();
paymentParameters.setAmount(150000); // amount is in cents: 150000 = 1,500.00 in local currency
paymentParameters.setTransactionId(12312312314); // For Void and Refund Transactions Only!!
paymentParameters.setOrderId("9bda71c6-a4b1-414b-97ec-5d36873216f2");
paymentParameters.setTransactionType(200);
app2AppRequest.setPaymentParameters(paymentParameters);

ConfigParameters configParameters = new ConfigParameters();
configParameters.setDrawerMenuEnabled(true);
configParameters.setSalesButtonEnabled(true);
configParameters.setVoidButtonEnabled(true);
configParameters.setRefundButtonEnabled(true);
configParameters.setHistoryButtonEnabled(true);
configParameters.setSettingsButtonEnabled(false);
configParameters.setSettlementButtonEnabled(false);
configParameters.setTipScreenEnabled(false);
configParameters.setUserPhotoEnabled(false);
configParameters.setInfoQuaryEnabled(false);
configParameters.setWorkingMode(0);
configParameters.setTimeout(-1);
// if timeout is set lower than zero, there is no timeout
// if timeout is set greater than zero, softPOS will wait for that second value

app2AppRequest.setConfigParameters(configParameters);

app2AppService.getPayment(app2AppRequest, eventListener);

Request and response

Request

// Note: amount is in minor units (cents). 140000 below corresponds to 1,400.00 in local currency.
{
  "amount": "140000",
  "transactionType": "200",
  "configParameters": {
    "drawerMenu": "1",
    "salesButton": "1",
    "voidButton": "1",
    "refundButton": "1",
    "historyButton": "1",
    "settingsButton": "1",
    "tipScreen": "0",
    "userPhoto": "1",
    "workingMode": "0"
  },
  "registerParameters": {
    "terminalId": "16010129",
    "merchantId": "000000009041042",
    "activationCode": "testCode"
  },
  "customMessage": "{\"blikCode\":\"777777\"}"
}

Success response

// Note: amount is in minor units (cents). 500000 below corresponds to 5,000.00 in local currency.
{
  "transactionType": "200",
  "appVersion": "1.2.10",
  "amount": "500000",
  "maskedPan": "**** **** **** 0516",
  "transactionStatus": "success",
  "customMessage": "{\"isoStan\":\"001017\"}",
  "refusalCode": "00",
  "transactionDate": "29-11-2022 15:47:24",
  "transactionId": "233394301141"
}

Declined response

{
  "transactionType": "200",
  "transactionStatus": "decline",
  "refusalCode": "96"
}

Refusal code 96

A system-level error that occurs when the terminal or host cannot complete the transaction. May be returned by the Host or the Payment Application (including kernel-related errors). When this happens, the Payment Application displays a detailed error message on the terminal screen. The Sales Application only receives the standardized refusal code 96, while the detailed description can be retrieved using the provided method.

Possible causes

  • System Error
  • Kernel-level error
  • EMV kernel failure
  • Card processing error
  • Payment Application internal error
  • Unexpected exception
  • Misconfigured or corrupted data
  • Host communication error
  • Host returned an unexpected or invalid response
  • Parameter or configuration issue
  • Terminal parameter mismatch

Reporting a 96 error. If you get a 96 error please provide the on-screen error message so the root cause can be analyzed more accurately.

See also