Advanced Options

Here you can find some examples of advanced workflow customization for our ready-to-use UI.

Quick links:

Brand management
Skipping CVV
Skipping card holder
Protect payments with device authentication
Display total amount
Override card holder validation
Display installment options

Brand management

There are 2 possible ways to set brands for your checkout:

In your app (see Configuring Checkout Settings)
In the merchant and administration portal - allowing to update the brands offered to shoppers without requiring an update of the mobile app.

Located under "Administration > COPYandPAY > Categories > Brands", you optionally can define which brands are displayed in the checkout by configuring the "Allowed Brands" on a channel, or any of its parents/ancestors.

To activate the brand configuration through the merchant and administration portal, first set the "Activate Brand Management" to TRUE.

The last setting "Override shop brands" is used to decide on the policy to propagate new Brands you enter to the checkout:

Either override whatever was defined in the shop. (Value TRUE)
Or offer only brands for payment, that are both specified in the BIP and in the checkout settings in the app (Value FALSE, default)

Skipping CVV

Checkout project provides an opportunity to skip CVV request for all cards or only for stored ones.

You can manage this by updating option skipCVV of OPPCheckoutSettings class:

OPPCheckoutSkipCVVModeNever - Always request CVV for card payments. This is set by default.
OPPCheckoutSkipCVVModeForStoredCards - Skip CVV check only for payments by stored cards.
OPPCheckoutSkipCVVModeAlways - Always skip CVV check. CVV field won't be displayed in card payment forms.

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];
checkoutSettings.skipCVV = OPPCheckoutSkipCVVModeForStoredCards;

let checkoutSettings = OPPCheckoutSettings()
checkoutSettings.skipCVV = .forStoredCards

You can manage this by updating CheckoutSkipCVVMode of CheckoutSettings class:

CheckoutSkipCVVMode.NEVER - Always request CVV for card payments. This is set by default.
CheckoutSkipCVVMode.FOR_STORED_CARDS - Skip CVV check only for payments by stored cards.
CheckoutSkipCVVMode.ALWAYS - Always skip CVV check. CVV field won't be displayed in card payment forms.

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);
checkoutSettings.setSkipCVVMode(CheckoutSkipCVVMode.FOR_STORED_CARDS);

Skipping card holder

If you are not going to collect holder name for the card payments, you can just hide this field using appropriate configuration of the OPPCheckoutSettingsCheckoutSettings:

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];
checkoutSettings.cardHolderVisible = NO;

let checkoutSettings = OPPCheckoutSettings()
checkoutSettings.isCardHolderVisible = false

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);
checkoutSettings.setCardHolderVisible(false);

Protect payments with Touch ID / Face ID

You can provide additional security for your shoppers by enabling biometric authentication for payment confirmation.
To complete payment shopper will have to authenticate with Touch ID of Face ID, if they are set on device, otherwise device passcode will be requested.

It's recommended to enable this protection for tokens (stored cards and back account information).
Biometrics authentication can be configured for any payment brands as well.

There are three modes of requesting device authentication:

Never OPPSecurityPolicyModeDeviceAuthNotRequired
If available OPPSecurityPolicyModeDeviceAuthRequiredIfAvailable
Always OPPSecurityPolicyModeDeviceAuthRequired

To configure device authentication create an appropriate OPPSecurityPolicy and add it to the securityPolicies option of the OPPCheckoutSettings.
OPPSecurityPolicy applies specified mode for tokens or list of payment brands.

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];

OPPSecurityPolicy *securityPolicyForTokens = [OPPSecurityPolicy securityPolicyForTokensWithMode:OPPSecurityPolicyModeDeviceAuthRequired];
NSArray *paymentBrands = @[@"VISA", @"MASTER"];
OPPSecurityPolicy *securityPolicyForPaymentMethods = [OPPSecurityPolicy securityPolicyWithPaymentBrands:paymentBrands mode:OPPSecurityPolicyModeDeviceAuthRequiredIfAvailable];
        
checkoutSettings.securityPolicies = @[securityPolicyForPaymentMethods, securityPolicyForTokens];

let checkoutSettings = OPPCheckoutSettings()

let securityPolicyForTokens = OPPSecurityPolicy(forTokensWith: .deviceAuthRequired)
let paymentBrands = ["VISA", "MASTER"]
let securityPolicyForPaymentBrands = OPPSecurityPolicy(paymentBrands: paymentBrands, mode: .deviceAuthRequiredIfAvailable)

checkoutSettings.securityPolicies = [securityPolicyForPaymentBrands, securityPolicyForTokens]

Protect payments with device authentication

NOTE: This functionality available only for Android 5.0 (API level 21) and higher.

You can provide additional security for your shoppers by enabling payment confirmation with device authentication.
To complete payment shopper will have to provide their credentials (Pattern, PIN, Password or Fingerprint if available).

It's recommended to enable this protection for tokens (stored cards and back account information).
Protection with device authentication can be configured for any payment brands as well.

There are three modes of requesting device authentication

Never CheckoutSecurityPolicyMode.DEVICE_AUTH_NOT_REQUIRED
If available CheckoutSecurityPolicyMode.DEVICE_AUTH_REQUIRED_IF_AVAILABLE
Always CheckoutSecurityPolicyMode.DEVICE_AUTH_REQUIRED

You can configure device authentication per payment brand. For example:

Set<String> paymentBrands = new LinkedHashSet<String>();

paymentBrands.add("VISA");
paymentBrands.add("MASTER");
paymentBrands.add("DIRECTDEBIT_SEPA");

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);

checkoutSettings.setSecurityPolicyModeForBrand("VISA", CheckoutSecurityPolicyMode.DEVICE_AUTH_REQUIRED);
checkoutSettings.setSecurityPolicyModeForBrand("MASTER", CheckoutSecurityPolicyMode.DEVICE_AUTH_REQUIRED_IF_AVAILABLE);

Set device authentication for tokens:

checkoutSettings.setSecurityPolicyModeForTokens(CheckoutSecurityPolicyMode.DEVICE_AUTH_REQUIRED);

Display total amount

By default total amount is not shown in ready-to-use UI. Since version 2.23.0 you can enable this option by setting boolean property displayTotalAmount of OPPCheckoutSettings class.

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];
checkoutSettings.displayTotalAmount = YES;

let checkoutSettings = OPPCheckoutSettings()
checkoutSettings.displayTotalAmount = true

By default total amount is not shown in ready-to-use UI. Since version 2.23.0 you can enable this option by setting boolean property isTotalAmountRequired of CheckoutSettings class.

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);
checkoutSettings.setTotalAmountRequired(true);

Total amount will be shown on the payment method selection screen and on the payment forms right in the button like on the screenshots below.

Override card holder validation

Since version 2.29.0 ready-to-use UI allows you to override holder validation for the card payments.

The OPPCheckoutProviderDelegate protocol provides you a validateCardHolder callback to override holder validation.

// Adopt a OPPCheckoutProviderDelegate protocol
@interface CheckoutViewController () <OPPCheckoutProviderDelegate>
@end

@implementation CheckoutViewController
...
- (IBAction)checkoutButtonAction:(id)sender {
    // Set a delegate property for the OPPCheckoutProvider instance
    self.checkoutProvider.delegate = self;
    ...
}

// Implement a callback, it will be called after holder text field loses focus or Pay button is pressed
- (BOOL)checkoutProvider:(OPPCheckoutProvider *)checkoutProvider validateCardHolder:(nullable NSString *)cardHolder {
    // Implement your internal validation
    // return `YES` if the card holder is valid, otherwise `NO`
}

@end

// Adopt a OPPCheckoutProviderDelegate protocol
class CheckoutViewController: UIViewController, OPPCheckoutProviderDelegate {
    ...
    @IBAction func checkoutButtonAction(_ sender: UIButton) {
        // Set a delegate property for the OPPCheckoutProvider instance
        self.checkoutProvider.delegate = self
        ...
    }

    // Implement a callback, it will be called after holder text field loses focus or Pay button is pressed
    func checkoutProvider(_ checkoutProvider: OPPCheckoutProvider, validateCardHolder cardHolder: String?) -> Bool {
        // Implement your internal validation
	// return `true` if the card holder is valid, otherwise `false`
    }
}

Implement IPaymentFormListener listener to catch payment form events and pass it to the CheckoutSettings.
Listener also should implement Parcelable interface as it will be passed through intent.

// Create your listener to override holder validation
public class CustomFormListener implements IPaymentFormListener {
    public CustomFormListener() {}
    
    @Override
    public CheckoutValidationResult onCardHolderValidate(String holder) {
        // Your intenal validation here
        if (isHolderValid(holder)) {
            return CheckoutValidationResult.VALID;
        } else {
            return CheckoutValidationResult.NOT_VALID;
        }
    }

    @Override
    public int describeContents() {
        return 0;
    }

    @Override
    public void writeToParcel(Parcel parcel, int i) {}
    
    private CustomFormListener(Parcel in) {}

    public static final Creator<CustomFormListener> CREATOR = new Creator<CustomFormListener>() {
        @Override
        public CustomFormListener createFromParcel(Parcel in) {
            return new CustomFormListener(in);
        }

        @Override
        public CustomFormListener[] newArray(int size) {
            return new CustomFormListener[size];
        }
    };
}

Pass created listener to the CheckoutSettings.

CheckoutSettings checkoutSettings = new CheckoutSettings(checkoutId, paymentBrands, providerMode);

CustomFormListener listener = new CustomFormListener();
checkoutSettings.setPaymentFormListener(listener);

Display installment options

By default the installment option is disabled. Since version 2.30.0 you can enable this option by configuring OPPCheckoutSettings in the following way:

Enable installment payments
Set your list of options if needed. Default is 1, 3, 5.

OPPCheckoutSettings *checkoutSettings = [[OPPCheckoutSettings alloc] init];
checkoutSettings.installmentEnabled = YES;
checkoutSettings.installmentOptions = @[@1, @2, @3];

let checkoutSettings = OPPCheckoutSettings()
checkoutSettings.isInstallmentEnabled = true
checkoutSettings.installmentOptions = [1, 2, 3]

To display installment options configure CheckoutSettings in the following way:

Enable installment payments
Set your list of options if needed. Default is 1, 3, 5.

CheckoutSettings checkoutSettings = new CheckoutSettings(
        checkoutId, paymentBrands, providerMode);

checkoutSettings.setInstallmentEnabled(true);
checkoutSettings.setInstallmentOptions(new Integer[] { 1, 2, 3 });