What's New in SDK 1.6.53

New Flow


Reward Pay (Surcharging)

We've introduced the flow in the SDK for this release to add support for processing sale with surcharge.

Availability

Device Platform Acquirer
Axium Android FDRC, TSYS
BBPos Chipper 3X Android, iOS TSYS
Pax Android FDRC, TSYS

Terminal Level Settings

There's a couple of required terminal settings to be configured for the new flow to work as expected.

You should ensure that the following settings are selected on the Processing Terminal > Features:

    • Allow surcharges
    • Surcharge (%)

Additional Settings

  • allowBypass - indicates whether merchants are able to bypass surcharging for specific transactions
  • discloseFee - indicates whether the surcharge fee should be disclosed to the cardholder for acceptance

Flow

Bypass allowed, with confirmation

  • allowBypass - YES
  • discloseFee - YES
  1. A transaction is initiated.
  2. The card is presented and read by the payment device.
  3. If bypassed, the sale is sent online straightaway for processing. (Skip to Step 5)
    Otherwise, the SDK checks if the card is eligible for surcharging through the gateway
  4. The cardholder is asked whether to accept the fee or opt out of the sale and pay by other means.
    If the cardholder accepted, the sale is sent online for processing.
    Otherwise, the transaction is cancelled.
  5. The cardholder is presented with the response contaning the amount breakdown with the surcharge fee if applied and not bypassed.

Bypass allowed, without confirmation

  • allowBypass - YES
  • discloseFee - NO
  1. A transaction is initiated.
  2. The card is presented and read by the payment device.
  3. The sale is sent online for processing.
  4. The cardholder is presented with the response contaning the amount breakdown with the surcharge fee if applied and not bypassed.

Bypass not allowed, with confirmation

  • allowBypass - NO
  • discloseFee - YES
  1. A transaction is initiated.
  2. The card is presented and read by the payment device.
  3. The SDK checks if the card is eligible for surcharging through the gateway
  4. The cardholder is asked whether to accept the fee or opt out of the sale and pay by other means.
    If the cardholder accepted, the sale is sent online for processing.
    Otherwise, the transaction is cancelled.
  5. The cardholder is presented with the response contaning the amount breakdown with the surcharge fee.

Bypass not allowed, without confirmation

  • allowBypass - NO
  • discloseFee - NO
  1. A transaction is initiated.
  2. The card is presented and read by the payment device.
  3. The sale is sent online for processing without requesting cardholder acceptance.
  4. The cardholder is presented with the response contaning the amount breakdown with the surcharge fee.

Please make sure that you're already familiar on setting up the SDK, initializing the device, and performing transactions. If not, please check the below links.

SDK Usage

1. Initiate a transaction.

Once the device is connected, start the sale by invoking the processSale method.

  • Android
  • IOS

    CoreSale sale = new CoreSale(BigDecimal.valueOf(Double.parseDouble(2.22)));
    AndroidTerminal.getInstance().processSale(sale);
    
        

    CoreSale *sale =[[CoreSale alloc] init];
    sale.amount = [NSNumber numberWithDouble: 2.22];
    [[WTPSTerminal singleton] processSale:sale];
    
        

To bypass surcharging for a specific transaction, you can set the CoreSale's bypassSurcharge field. If the field is not set, the default value is false.

  • Android
  • IOS

    CoreSale sale = new CoreSale(BigDecimal.valueOf(Double.parseDouble(2.22)));
    sale.setBypassSurcharge(true);
    AndroidTerminal.getInstance().processSale(sale);
    
        

    CoreSale *sale =[[CoreSale alloc] init];
    sale.amount = [NSNumber numberWithDouble: 2.22];
    [sale setBypassSurcharge:[NSNumber numberwithBool:YES]];
    [[WTPSTerminal singleton] processSale:sale];
    
        

2. Handle the surcharge confirmation.

If the discloseFee is enabled on the terminal settings and surcharging is not bypassed, the onRequestSurchargeConfirm callback will fire with the surcharge amount.

Otherwise, you can skip this step.

  • Android
  • IOS

    @Override
    public void onRequestSurchargeConfirm(CoreBinLookupResponse binLookupResponse) {
        ...
        ...
        ...
    }
    
        

    - (void) onRequestSurchargeConfirm:(CoreBinLookupResponse *)binLookupResponse {
        ...
        ...
        ...
    }
    
        

To accept the surcharge fee, you can use the confirmSurchargeFee with the parameter set to true

  • Android
  • IOS

    AndroidTerminal.getInstance().confirmSurchargeFee(true);
    
        

    [[WTPSTerminal singleton] confirmSurchargeFee:YES];
    
        

To decline and opt out of the sale, set the parameter to false.

This will cancel the transaction.

  • Android
  • IOS

    AndroidTerminal.getInstance().confirmSurchargeFee(false);
    
        

    [[WTPSTerminal singleton] confirmSurchargeFee:NO];
    
        

3. Retrieve the sale response

The onSaleResponse callback will fire on success. Here is where you can display receipts or do any other post transaction processing. You should find the surcharge amount, if applied and not bypassed, in the sale response.

  • Android
  • IOS

    @Override
    public void onSaleResponse(CoreSaleResponse response) {
        if (response.getSurcharge() != null) {
            BigDecimal surchargeAmount = response.getSurcharge().getAmount();
        }
        ...
        ...
        ...
    }
    
        

    -(void)onSaleResponse:(CoreSaleResponse*)sale{
        if(sale.surcharge != nil) {
            NSNumber *surchargeAmount = sale.surcharge.amount;
        }
        ...
        ...
        ...
    }