Initiate Payment or Authorization

Applies to in-person POS payments

This API sends payment or authorization instructions from the merchant's App to the POS payment App.

The merchant's App must be signed, packaged, and uploaded to the TMS marketplace.

Initiate payment:

The POS terminal comes with the Switchio Pay payment App preinstalled. The merchant's App must interact with the Switchio Pay payment App to perform payment or authorization. Call it as follows:

URI = "app://switchiopay/api/main/v7/payment"

Sample code:

 /**
     * Process an ECR payment according to the specification
     * @param transactionId Transaction ID
     * @param amount Payment amount in minor units
     * @param invoiceNumber Custom transaction number
     * @param currencyCode ISO 4217 numeric currency code (for example, 978=EUR, 208=DKK)
     * @param callback Callback interface
     */
    public void processPayment(String transactionId, int amount, String invoiceNumber, String currencyCode, ECRCallback callback) {
        this.ecrCallback = callback;
        
        try {
            // Build the ECR v7 URI
            JSONObject paymentData = new JSONObject();
            paymentData.put("transactionId", transactionId);
            paymentData.put("amount", amount);
            paymentData.put("currencyCode", Integer.parseInt(currencyCode));
            paymentData.put("invoiceNumber", invoiceNumber);
                        
            // Build the URI manually to ensure correct formatting
            String uriString = "app://switchiopay/api/main/v7/payment?data=" + 
                android.net.Uri.encode(paymentData.toString());
            Uri uri = Uri.parse(uriString); 
            Intent intent = new Intent(ECR_ACTION, uri);
            intent.addFlags(Intent.FLAG_ACTIVITY_REORDER_TO_FRONT);
            intent.putExtra("data", paymentData.toString());
            intent.putExtra("transactionId", transactionId);
            intent.putExtra("amount", amount);
            intent.putExtra("currencyCode", Integer.parseInt(currencyCode));
            intent.putExtra("invoiceNumber", invoiceNumber); 
            // Launch the Activity and wait for the result
            activity.startActivityForResult(intent, ECR_PAYMENT_REQUEST_CODE);   
            Log.d(TAG, "ECR payment Intent sent; waiting for the result...");
            
        } catch (Exception e) {
            Log.e(TAG, "Payment processing exception", e);
            Log.e(TAG, "Exception details: " + e.getMessage());
            if (callback != null) {
                callback.onError("Payment processing error: " + e.getMessage());
            }
        }
        Log.d(TAG, "=== processPayment completed ===");
    }

Request example:

app://switchiopay/api/main/v7/preauth?data={"transactionId":"88bb2366-716d-11ed-a1eb-0242ac120002","amount": 1200,"currencyCode":978,"invoiceNumber": "123456789012345678"}

Response example:

{
    "aid": "A0000000283101",
    "amount": 500,
    "cashbackAmount": 1500,
    "aosa": "null",
    "appCryptogram": "5F52BA71C7B45441",
    "appLabel": "Air Bank",
    "authCode": "114546",
    "availableBalance": "1000",
    "brand": "MASTERCARD",
    "cardHolderMessage": "Approved",
    "cardInputType": "CLESS",
    "cid": "80",
    "currency": 203,
    "cvmTypeList": [
        "PIN_ONLINE"
    ],
    "dateTimeServer": "Jul 16, 2025 14:40:50",
    "dateTimeTerminal": "Jul 16, 2025 14:39:37",
    "driverNumber": "123456",
    "emvResponseData": {
        "smartCardScheme": "1",
        "authorisationResponseCode": "00"
    },
    "expiration": "****",
    "invoiceNumber": "VS353464556789780",
    "isReversed": false,
    "merchantIdAcquirer": "TNEXGO01",
    "merchantIdIssuer": "1357",
    "merchantMessage": "Approved",
    "monetToken": "MONETTOKEN",
    "odometer": 65403,
    "pan": "970348******3910",
    "par": "PAR",
    "panSequenceNumber": "00",
    "refundId": "1234567890",
    "responseCode": "OK",
    "responseMessage": "potvrzeno",
    "reversal": false,
    "sequenceNumber": "001001614",
    "tipAmount": 100,
    "terminalIdAcquirer": "M1TNEXGO01",
    "terminalIdIssuer": "M1TNEXGO01",
    "tokens": [
        "fkdfkjbekjrhljb"
    ],
    "transactionId": "48a3ea7d-b82f-4b42-abbb-5043365e4faa",
    "transactionType": "SALE_ONLINE",
    "vehicleCode": "1A21234",
    "licensePlate": "EL100AC",
    "authorizationResponseCode": "00"
}

Response result:

1. If the call succeeds, "responseCode": OK or Approved is returned.

2. If the call fails, "responseCode": other value is returned.

Note: To obtain the user's card identifier, save the returned par value.