Surcharge flow

Surcharge Architecture

POS-based Surcharge: Driven by the POS, it is the ability to send a separate surcharge amount to add to a payment. The requirement here is that surcharging is enabled on the EFTPOS terminal and the transaction amount and surcharge amount are separated. This surcharge amount will override a surcharge that is configured on the EFTPOS terminal and can be applied to Purchases and Cashout type transactions.

//Payment request from the POS will include a surcharge amount
//as a seperate line item and not part of the transaction request.

function initiatePurchase(
  purchaseAmount: 1000,
  tipAmount: 0,
  cashoutAmount: 0,
  surchargeAmount: 100,
  promptForCashout: false
)

spiInstance.InitiatePurchaseTxV2(
  posRefId,
  purchaseAmount,
  tipAmount,
  cashoutAmount,
  surchargeAmount,
  promptForCashout);

//TRANSACTION RESPONSE
// Surcharge is accepted from the EFTPOS Terminal and will be reported as part of transaction response.
//Please review the information below

Received:
{"message":{
  "id":"prchs11",
  "event":"purchase_response",
  "data":{"success":true,
  "pos_ref_id":"purchase-2022-03-06T23:29:12.934Z",
  "purchase_amount":1000,
  "bank_noncash_amount": 1000,
  "cash_amount":0,
  "tip_amount":0,
  "surcharge_amount":100,
  "bank_cash_amount":0,
  "host_response_code":"000",
  "host_response_text":"APPROVED",
  "account_type":"CREDIT",
  "auth_code":"000000",
  "bank_date":"0000000",
  "bank_time":"000000",
  "bank_settlement_date":"000000",
  "card_entry":"EMV_CTLS",
  "currency":"AUD",
  "emv_actioncode":"TC",
  "emv_actioncode_values":"00000000000000000",
  "emv_pix":"0000",
  "emv_rid":"A000000000",
  "emv_tsi":"0000",
  "emv_tvr":"0000000000",
  "expiry_date":"00/0000",
  "masked_pan":"............0000",
  "merchant_addr":"",
  "merchant_city":"",
  "merchant_country":"",
  "merchant_name":"",
  "merchant_postcode":"",
  "online_indicator":"Y",
  "scheme_app_name":"Visa Credit",
  "scheme_name":"VISA",
  "stan":"000000",
  "rrn":"00000000000",
  "transaction_type":"PURCHASE",
  "merchant_id":"00000000",
  "terminal_id":"00000000",
  "customer_receipt":"",
  "merchant_receipt":""
         },
  "datetime":"2022-03-07T10:29:31.222",
  "pos_id":"POS2",
  "conn_id":"232625226"
}

Terminal based Surcharge: This feature automatically adds a predefined surcharge to a purchase transaction at the time the card is presented to the terminal. The POS is required to accept the surcharging field in the response back from the EFTPOS terminal.

//Terminal-based surcharge request will not include a surcharge amount in the request

function initiatePurchase(
  purchaseAmount: 1000,
  tipAmount: 0,
  cashoutAmount: 0,
  surchargeAmount: 0,
  promptForCashout: false
)

spiInstance.InitiatePurchaseTxV2(
  posRefId,
  purchaseAmount,
  tipAmount,
  cashoutAmount,
  surchargeAmount,
  promptForCashout);

//TRANSACTION RESPONSE
// Surcharge is applied from the EFTPOS Terminal and will be reported as part of transaction response.
//Please review the information below

Received:
{"message":{
  "id":"prchs11",
  "event":"purchase_response",
  "data":{"success":true,
  "pos_ref_id":"purchase-2022-03-06T23:29:12.934Z",
  "purchase_amount":1000,
  "bank_noncash_amount": 1000,
  "cash_amount":0,
  "tip_amount":0,
  "surcharge_amount":100,
  "bank_cash_amount":0,
  "host_response_code":"000",
  "host_response_text":"APPROVED",
  "account_type":"CREDIT",
  "auth_code":"000000",
  "bank_date":"0000000",
  "bank_time":"000000",
  "bank_settlement_date":"000000",
  "card_entry":"EMV_CTLS",
  "currency":"AUD",
  "emv_actioncode":"TC",
  "emv_actioncode_values":"00000000000000000",
  "emv_pix":"0000",
  "emv_rid":"A000000000",
  "emv_tsi":"0000",
  "emv_tvr":"0000000000",
  "expiry_date":"00/0000",
  "masked_pan":"............0000",
  "merchant_addr":"",
  "merchant_city":"",
  "merchant_country":"",
  "merchant_name":"",
  "merchant_postcode":"",
  "online_indicator":"Y",
  "scheme_app_name":"Visa Credit",
  "scheme_name":"VISA",
  "stan":"000000",
  "rrn":"00000000000",
  "transaction_type":"PURCHASE",
  "merchant_id":"00000000",
  "terminal_id":"00000000",
  "customer_receipt":"",
  "merchant_receipt":""
         },
  "datetime":"2022-03-07T10:29:31.222",
  "pos_id":"POS2",
  "conn_id":"232625226"
}