Flutter SDK

Introduction

The SDK for Flutter helps you to communicate with the Client API, offering: 

• convenient Dart wrappers for API responses
• user-friendly formatting of payment data such as card numbers and expiry dates
• input validation
• check to determine to which payment provider a card number is associated
• handling of all the details concerning the encryption of payment details

The source code of the SDK and installation instructions are available on GitHub

Main payment steps

1. Initialize the Flutter SDK for this payment. This is done using information such as session and customer identifiers, connection endpoints and payment information like currency and total amount.
2. Retrieve the payment items and accounts on file that can be used for this payment from the Client API. Your app uses this data to create the payment product selection screen.
3. Retrieve all the details about the payment product fields from the Client API. Your app can use this information to create the payment product details screen. Your consumer will need to provide the information requested, based on the selected payment product or account on file.
4. Encrypt all the provided payment information using the Client API. Your app sends the encrypted result to your e-commerce server, which sends it to our Server API.
5. Use the response from the Server API call to guide the consumer to the next step in the payment process. This can be a simple "payment successful" or "payment failed" screen or a redirect to a third party that completes the payment.

Initialize the Flutter SDK

Once the SDK is initialized you can use the singleton class ConnectSDK from anywhere in your application. This class contains the Client API class that gives access to all calls to the Worldline platform.

To initialize the SDK, you have to provide the SDK with the required authentication information to connect the Client API. Also required is the payment context, needed to return the correct data.

This information can be provided using the parameters ConnectSDKConfiguration and PaymentConfiguration. The ConnectSDKConfiguration has the following properties:

• SessionConfiguration object (mandatory)
• enableNetworkLogs (optional)
• applicationId (optional)
• ipAddress (optional)

The PaymentConfiguration object needs the following information:

• paymentContext (mandatory)
• groupPaymentProducts (optional)

final sessionConfiguration = SessionConfiguration(
	clientSessionId : "1234",
	customerId : "5678",
	clientApiUrl : "https://clientapi.com",
	assetUrl : "https://assets.com"
);

final connectSDKConfiguration = ConnectSDKConfiguration(
	sessionConfiguration,
	enableNetworkLogs: true,
	applicationId: "Example Application/v1",
	ipAddress: "127.0.0.1"
);

final paymentContext = PaymentContext(
	AmountOfMoney(
		1000,
		"USD"
	), 
	"US", // country code
	false, // Whether payment is recurring.
	forceBasicFlow: false, // Whether basic flow is forced.
	locale: Locale("en", "US") // Optional
);

final paymentConfiguration = PaymentConfiguration(
	paymentContext,
	groupPaymentProducts: false
);
ConnectSDK.connectSDK.initialize(
	connectSDKConfiguration: connectSDKConfiguration,
	paymentConfiguration: paymentConfiguration
);

Session configuration

SessionConfiguration must be initialized with the information needed to authenticate with our servers. This can be retrieved by making a Client Session API request using one of our Server SDKs. The following data will be returned, and serve as input for SessionConfiguration:

• A client session identifier and a customer identifier, which identify you and the created session.
• The client-api-url and asset-url that the SDK will connect to. The asset-url serves static resources that are used by the SDK, such as logos of payment products and tooltip images.

Payment context

PaymentContext holds the information needed to request available payment items, such as an AmountOfMoney object that contains a total amount and a currency code, a country code, and a setting for whether the payment is a single payment or a recurring payment.

Making requests to the Client API

The class ClientApi wraps the Worldline Connect API, making it easy for you to send and receive network requests. An instance of ClientApi can be obtained from ConnectSDK after initialization. All Client APIs are available through the SDK. When making a request, the result will be one of three statuses:

1. Success, the call was successful and a response object is returned.
2. Error, the call failed and an ApiErrorResponse object is returned.
3. Failure, an unknown error has occurred and a NativeException is returned.

Get payment items

When retrieving payment Items, all methods that are available within the current payment context are returned. This includes payment products, groups and accounts on files. These are then bundled into a list as BasicPaymentItems. Possible AccountOnFiles are in a separate list. The code example below shows how an instance of BasicPaymentItems can be obtained.

ConnectSDK.connectSDK.getClientApi().getPaymentItems(
	onSuccess: (basicPaymentItems) {
	// Process BasicPaymentItems object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
}); 

BasicPaymentProduct & BasicPaymentProductGroup

The SDK offers four classes to represent information about payment products: BasicPaymentProduct, its subclass PaymentProduct, BasicPaymentProductGroup and its subclass PaymentProductGroup. Practically speaking,  BasicPaymentProduct and BasicPaymentProductGroup contain the information to display a payment product (group) distinguishable from others in a list of available options.

Use the information in PaymentItems, BasicPaymentProduct and BasicPaymentProductGroup to display a list of available payment items. The BasicPaymentProduct contains: 

• identifier
• field indicating the payment method of this product
• field indicating the payment product group this product belongs to
• two fields that indicate the minimal and maximal amount required to pay with this payment product
• field indicating whether payment data can be stored as an account on file
• field indicating whether payment data can be stored automatically as an account on file
• field indicating whether or not a recurring payment can be processed with this payment product
• field indicating whether the payment method uses a redirect to a 3rd party
• MobileIntegrationLevel indicating whether there is optimised, basic or no mobile support for this payment product
• list of accounts on file for this payment product
• display hints that can be used to render the BasicPaymentProduct, containing:
  • index indicating at which position the payment product belongs in a list of payment products
  • label
  • logo

Instances of BasicPaymentProductGroup contain:

• identifier
• list of accounts on file for payment products in this group
• display hints that can be used to render the BasicPaymentProductGroup, containing:
  • index indicating at which position the payment product belongs in a list of payment products
  • label
  • logo

AccountOnFile

For some payment products, consumers can indicate that they want the Worldline platform to store part of the data they enter while using such a payment product. For example, it is possible to store the card holder name and the card number for certain card-based payment products. The stored data is referred to as an account on file. When the consumer wants to use the same payment product for another payment, it is possible to select one of the stored accounts on file for this payment. In such cases, the consumer doesn't have to enter the information that is already stored in the account on file.

Instances of the class BasicPaymentProduct and BasicPaymentProductGroup also contain a list of accounts on file that are available within the session. An AccountOnFile contains the following fields

• identifier for the account on file
• identifier for the corresponding payment product
• collection of key value pairs that have been stored as part of the account on file
• display hints that contain information about how the account on file should be rendered
• method that produces a label that describes the account on file

Get payment product

This method retrieves a single payment product, containing all details, including field information that can be used to show a payment product detail page. The code fragment below shows how a PaymentProduct call can be made.

ConnectSDK.connectSDK.getClientApi().getPaymentProduct(
	paymentProductId: "1",
	onSuccess: (paymentProduct) {
	// Process PaymentProduct object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Get payment product group

This method retrieves a single payment product group. Currently the only available group is "cards". The code fragment below shows how a PaymentProductGroup call can be made.

ConnectSDK.connectSDK.getClientApi().getPaymentProductGroup(
	onSuccess: (paymentProductGroup) {
	// Process PaymentProductGroup object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

PaymentProduct & PaymentProductGroup

The classes PaymentProduct and PaymentProductGroup extend BasicPaymentProduct and BasicPaymentProductGroup, and therefore contain the same information that can be used to display them. They also contain extra information in the form of PaymentProductField. For some payment products, the consumer is required to provide additional information, such as an address, a bank account number, a credit card number, or an expiry date. Each payment item can have a number of fields that need to be provided to process a payment. These fields need to be displayed to your consumer, so that they can provide the information.

PaymentProductField

The fields of payment items are represented by instances of PaymentProductField. Each field has an identifier, a type, a list of restrictions that apply to the value of the field, and information about how the field should be presented graphically to the consumer. Additionally, there are some helper functions that can be used to determine whether a given value is a valid value for the field.

In the code fragment below, the field with identifier "cvv" is retrieved from a payment product. The data restrictions of the field are inspected to see whether this field is a required field or an optional field. Additionally, the display hints of the field are inspected to see whether the values a consumer provides should be obfuscated in a user interface. Finally, the value "123" is validated and the number of validation errors is inspected to see whether the provided value is valid.

final PaymentProductField field =  paymentRequest.paymentProduct.getPaymentProductFieldById("cvv");

final bool isRequired = field.dataRestrictions.isRequired;
final bool shouldBeObfuscated = field.displayHints.obfuscate;

paymentRequest.setValue(field.id, "123");

final List errorMessages = field.validateValue(paymentRequest);

final isFieldInputValid = errorMessages.isEmpty;

ValidationErrorMessage, ValidationRule and its subclasses

The class PaymentProductField contains a list of instances of ValidationRule, which determine how a field value is validated. When validating a value of a PaymentProductField, all those validation rules are applied to the value of the field. This returns a list of instances of ValidationErrorMessage, each containing a translatable error message identifier, and the corresponding ValidationRule. When translating this error message identifier, you can use the ValidationRule that triggered the validation error to get additional information that you can show to the consumer.

For example, the minlength and maxlength properties on a ValidationRuleLength indicate the smallest and largest valid field values. This error can be used to give consumer feedback when there are issues with the information they provide. The following subclasses of ValidationRule have extra information that can be used while constructing an error message:

• ValidationRuleLength indicates that the supplied value has an invalid length. The minimal length is defined by the property minLength and the maximal length is defined by the property maxLength.
• ValidationRuleRange indicates that the supplied value does not fall within the required range of values. The smallest value is defined by the property minValue and the largest value is defined by the property maxValue.

Get IIN details

The first six digits of a payment card number are known as the Issuer Identification Number (IIN). An instance of ClientApi can be used to check which payment products are associated with an IIN. The check is performed asynchronously, which means that the result of the check is not available immediately. The result of this check is an instance of IinDetailsResponse. This class has a couple of properties:

• Field IinStatus that indicates the result of the check. The different possible statusses are:
  • SUPPORTED indicates that the IIN is associated with a payment product that is supported by the Worldline platform.
  • UNKNOWN indicates that the IIN is not recognized.
  • NOT_ENOUGH_DIGITS indicates that fewer than six digits have been provided.
  • EXISTING_BUT_NOT_ALLOWED indicates that the IIN is recognized, but that it cannot be payed with in the current situation.
• Field that holds the identifier of the primary payment product that is associated with this IIN.
• Field that holds the country code of the primary payment product that is associated with this IIN.
• Field that indicates whether it is allowed to do a payment with the primary payment product based on the payment context.
• List of instances of IinDetail, which depict co-brands for the current IIN.

It is possible that a single credit card has multiple brands associated to it. We call these co-brands. The details of the first payment product, that can be payed with in the current payment context, are always stored in the toplevel fields of the IinDetailsResponse. If a card is a multibranded card, the list of instances of IinDetail contains all brands associated with the card, including the payment product that is stored in the toplevel fields. This list should be used to provide your consumer with the option to select the brand they want to use for the current payment. If there is only one payment product associated with the credit card the list of IIN Details is empty.

If the value of status is not SUPPORTED the other fields of IinDetailsResponse will all be null (or false in case of the isAllowedInContext field).

The code fragment below shows how an instance of IinDetailsResponse can be obtained.

ConnectSDK.connectSDK.getClientApi().getIINDetails(
	partialCreditCardNumber: "123456",
	onSuccess: (iinDetailsResponse) {
	// Process IinDetailsResponse object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Convert amount

To help converting amounts from one currency to another, the SDK offers the convertAmount method of the ClientApi class. This method takes an amount in cents, and a source and target currency, which are both three-letter ISO currency codes, and returns the converted amount in cents. The code fragment below shows how an amount can be converted.

ConnectSDK.connectSDK.getClientApi().convertAmount(
	source: "USD",
	target: "EUR",
	amount: 1000,
	onSuccess: (convertedAmount) {
	// Process ConvertedAmount object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Retrieve logo

To retrieve logos from the resource server, the Flutter SDK offers an implementation of the Flutter Image.network() widget. This method offers all optional arguments that the Image.network() offers, except for headers. The logoUrl argument takes a partial url, as returned on DisplayHints or ToolTip. This url gets prefixed with the assetUrl provided in the SessionConfiguration. The appropriate authorization header is automatically added by the SDK.

Retrieving an image, using all default arguments for Image, is shown in the code example below.

final Image logo = ConnectSDK.connectSDK.getClientApi().retrieveLogo(
	logoUrl: "example.png"
);

Get third party status

Polls a third party for the status of the payment.

Currently only available for payments performed with payment products 3012 (Bancontact) and 863 (WeChat Pay). In the case of Bancontact, it is used to determine if the consumer is paying using the Bancontact app and if so, what the payment status is. The code example below shows how an instance of ThirdPartyStatusResponse can be obtained.

ConnectSDK.connectSDK.getClientApi().getThirdPartyStatus(
	paymentId: "payment identifier",
	onSuccess: (thirdPartyStatusResponse) {
	// Process ThirdPartyStatusResponse object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Get payment product directory

Certain payment products have directories that the consumer needs to pick from. An example is the list of banks for the Dutch iDeal payment product from which the consumer needs to select a bank. If you want to retrieve the directory information, you can use the getPaymentProductDirectory method of the ClientApi class.

This method takes a payment product identifier and returns an instance of PaymentProductDirectory, as shown in the code fragment below.

ConnectSDK.connectSDK.getClientApi().getPaymentProductDirectory(
	paymentProductId: "809",
	onSuccess: (paymentProductDirectory) {
	// Process PaymentProductDirectory object
},	onApiError: () {
	// Indicate that an API error occurred
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Each instance of PaymentProductDirectory contains a list of instances of DirectoryEntry, which contain the following information:

• identifier of the issuing bank
• name of the issuing bank
• list of countries of the issuing bank
• string that indicates how the issuers should be sorted

Encrypt payment details

To protect the payment details that are provided by your consumer, they must be encrypted before sending them to your servers. The code fragment below shows how ConnectSDK can be used to encrypt an instance of PaymentRequest. The result is an instance of the class EncryptedPaymentRequest which contains two properties, encryptedFields and encodedClientMetaInfo. These should be sent to the Worldline platform from your e-commerce server in the Create Payment API.

final request = SdkPreparePaymentRequest(paymentRequest);
ConnectSDK.connectSDK.preparePaymentRequest(
	paymentRequest: request,
	onSuccess: (encryptedPaymentRequest) {
	// Process EncryptedPaymentRequest object
},	onFailure: (exception) {
	// Indicate that an error occurred
});

Payment request

When your consumer selected a payment product and you have retrieved this product from the API, a payment request can be constructed. In the payment request, the payment details can be stored, such as the product retrieved, field values and other payment settings. The code example below shows how to make a payment request.

final paymentRequest = PaymentRequest(
	paymentProduct : paymentProduct,
	tokenize : true, // Whether to store the payment details as an account on file. False by default.
	accountOnFile: accountOnFile // Provide account on file to be used here, if the customer selected one, null otherwise.
);
paymentRequest.setValue("cardNumber", "4111111111111111");
paymentRequest.setValue("expiryDate", "1225");
paymentRequest.setValue("cardholderName", "John Doe");
paymentRequest.setValue("cvv", "123");

Once all values have been provided, the payment request can be used to validate the values, as shown below. After validation, a list of errors is available. If this list is empty, the provided values are valid and the payment request is ready for encryption.

final List validationResult = paymentRequest.validate();

if (validationResult.isEmpty) {
	// Encrypt the paymentRequest.
} else {
	// Indicate that a validation error has occurred.
}

Logging

During development, you may want to turn on logging of the requests and responses that make up the communication with Worldline. You can enable request and response logging in the SDK by initializing with "enableNetworkLogs" set to "true".