Single Card Payment

The following is a full example on how a card payment flow is expected to behave. For an example on other payment method different than card, on in combining several payment methods, please refer to the Multi-tender full example.

We are going to guide you on the usage of each delegate function for the Sale manager, and how they are used during a card payment. We will assume you build your Sale request with all the products, amounts, etc., and that your app UI is ready to use by, for example, a clerk.

The User Interface

From your UI, the app user will select a payment method (for example, card or cash). We will focus here in the case of Card.

After the user selects to proceed wth a card payment, your app will need to use the ePOS SDK to access the payment terminal, and then proceed to use this terminal to start the payment. If you implemented the SDK correctly, you should be subscribing (Android) or declaring the delegate methods (iOS) for such purpose. As you can see in the Object Models and samples below, actions for accepting signature, informing about progress, etc., will be called asynchronously when needed. You can run the Integration Tests provided to see it yourself on iOS and Android.

The iOS Object Model

The payment flow for purchase sales requests is largely handled by the six methods of the Sales Manager component shown below on the right side of the diagram. The completed sale is delivered in the Sale Response object:

• as a sale object if the processing was successful
• as an error object if the processing was not successful

Tip

In the provided Objective-C and Swift sample code, look first at the very bottom of the code to see the six Sales Manager methods that are used because this helps to understand the overall payment flow. Next, look at the preceding code to see the details of each method that is called in the payment flow.

The Android Object Model

The previous chapter presented the Android code for handling the various card-related events on the terminal so the sample code here has just this code, and the object model looks like this:

The Sample Code

ObjC

	// It is necessary to implement WDPaymentDelegate methods to receive events from the payment flow
	@interface PaymentHandler : NSObject<WDPaymentDelegate>
	@end
	@implementation PaymentHandler
	// The end of the payment process
	- (void)completion:(WDSaleResponse * _Nullable)saleResponse saleResponseError:(NSError * _Nullable)saleResponseError {
	//sale - Is the completed Sale - contains the sale status, details, results
	//error - If any error is encountered during the sale it would be reported
	//in the form of error and hierarchy of underlying errors to give you as much details as possible
	NSLog(@"sale response: %@, error: %@", saleResponse, saleResponseError);
	}
	// Updates from the payment flow
	- (void)progress:(WDStateUpdate)paymentProgress {
	// statusUpdate - coded statuses are reported throughout the payment flow
	NSLog(@"progress: %zd", paymentProgress);
	}
	// In the case the Cardholder Signature is required by the Payment flow this block will be executed
	// Your task is to respond to it by collecting the signature image from the customer and
	// posting it back in the sendCollectedSignature method
	- (void)collectSignature:(WDSignatureRequest * _Nonnull)signatureRequest {
	//signatureRequest - comes from the payment flow and once you collect the signature from the customer
	// send it back in the signatureRequest.sendCollectedSignature
	signatureRequest.sendCollectedSignature([TestUtils signatureImageFromText:@"Test"], nil);
	//The signature image is transferred to the backend and stored with the Sale
	}
	// Note: Applicable to terminals without BUTTONS
	// In the case the Cardholder Signature was collected then the merchant is required to confirm it's validity
	// A. If the terminal has buttons that are used for Approving/Rejecting then this block is either never called from Payment flow
	// or it's signatureVerificationCallback comes nil
	// B. If the terminal does not have buttons then the Application must present a user interface to Approve/Reject the Cardholder Signature
	- (void)confirm:(WDPaymentConfirmationType)confirmationType paymentConfirmationResult:(PaymentConfirmationResult _Nullable)paymentConfirmationResult {
	if (paymentConfirmationResult) {
	// Here the simplified use of Approving the Cardholder Signature is demonstrated
	paymentConfirmationResult(WDPaymentConfirmationResultApproved);
	}
	};
	// Note: Applicable to terminals without BUTTONS
	// In the case the payment Card has more than one card application available then the client application
	// has to present user interface for the Cardholder to select preferred card application
	// The list of card applications is present in appSelectionRequest.appsArray as a list of Strings
	- (void)cardApplication:(WDAppSelectionRequest * _Nonnull)appSelectionRequest {
	// There is more than 1 card application available
	// Present the UI for the Cardholder to select preferred card application (Debit | Credit)
	if(appSelectionRequest.appsArray.count > 0){
	// Here we demonstrate the simplified use of selecting the first card application from the list of available card applications
	// and sending it to the Payment flow
	appSelectionRequest.selectCardApplication(0);
	}
	}
	@end
	// Create the property for payment method handler somewhere in your controller
	@property (nonatomic, strong) PaymentHandler *paymentHandler;
	//
	// The minimum body of the Payment method is shown here
	//
	-(void)pay{
	//End of SDK Setup process
	CurrentUserCompletion setupCompletion = ^( WDMerchantUser * _Nullable currentUser, WDMerchantCashier * _Nullable cashier, NSError * _Nullable error){
	//Current User is returned upon successful login
	//if the Cash Management is enabled and Cashier record exist for the current user then the Cashier is returned also
	};
	// The SDK is initialized as shared instance so can be accessed
	// from multiple View Controllers
	WDePOS *sdk = [WDePOS sharedInstance];
	// Set the SDK target environment - in this case Public Test
	// and the username and password to authenticate to it
	[sdk setupWithEnvironment:WDEnvironmentPublicTest
	username:@"yourUsername"
	password:@"yourPassword"
	completion:setupCompletion];
	// Create the instance of the Sale Request
	// Here the minimum data is depicted
	WDSaleRequestPurchase *saleRequest = [[WDSaleRequestPurchase alloc] initWithUniqueId:@"yourSaleUniqueID" // provide your unique ID to identify the Sale
	location:nil // provide the GPS location
	inclusiveTaxes:YES // Tax inclusive/exclusive flag
	currency:@"EUR" // Currency to use for this Sale
	note:@"Test Posmate Sale" // Top level note for this sale
	gratuityTaxRate:nil // Gratuity tax rate - nil if no gratuity to be set later in the payment flow
	];
	// Create one item named "Item 1" costing 10.00 EUR at 20% Tax
	[saleRequest addSaleItem:[NSDecimalNumber decimalNumberWithString:@"10.00"] // Item Unit price
	quantity:[NSDecimalNumber decimalNumberWithString:@"1"] // Item Quantity
	taxRate:[NSDecimalNumber decimalNumberWithString:@"20.00"] // Item Tax rate
	itemDescription:@"Item 1" // Item description
	productId:nil
	externalProductId:nil // External product ID - in the case you are using ERP - such as SAP and wish to refer to the product
	];
	// Create Payment Configuration to be used in the Pay API later with your Sale Request
	WDSaleRequestConfiguration *paymentConfiguration = [[WDSaleRequestConfiguration alloc] initWithSaleRequest:saleRequest];
	// Discover active terminals and use it - in this case we use the first one
	// Alternatively use the one discovered previously and stored in an instance variable (or user preferences)
	[sdk.terminalManager discoverDevices:WDPosMateExtensionUUID
	completion:^(NSArray<WDTerminal *> * _Nullable terminals, NSError * _Nullable devicesError)
	{
	// Set this Sale in total amount 10 EUR to be settled half by Card transaction (5 EUR)
	[saleRequest addCardPayment:[NSDecimalNumber decimalNumberWithString:@"5.00"]
	terminal:[terminals firstObject]];
	// Start the Payment flow
	[[sdk saleManager] pay:paymentConfiguration withDelegate:self.paymentHandler];
	}];
	}

view raw WDePOS-Payment.m hosted with ❤ by GitHub

Swift

	// It is necessary to implement WDPaymentDelegate methods to receive events from the payment flow
	class PaymentHandler : NSObject, WDPaymentDelegate {
	// Updates from the payment flow
	func progress(_ paymentProgress: WDStateUpdate) {
	// statusUpdate - coded statuses are reported throughout the payment flow
	}
	// In the case the Cardholder Signature is required by the Payment flow this block will be executed
	// Your task is to respond to it by collecting the signature image from the customer and
	// posting it back in the sendCollectedSignature method
	func collectSignature(_ signatureRequest: WDSignatureRequest) {
	//signatureRequest - comes from the payment flow and once you collect the signature from the customer
	// send it back in the signatureRequest.sendCollectedSignature
	signatureRequest.sendCollectedSignature(UIImage(),nil)
	//The signature image is transferred to the backend and stored with the Sale
	}
	// Note: Applicable to terminals without BUTTONS
	// In the case the Cardholder Signature was collected then the merchant is required to confirm it's validity
	// A. If the terminal has buttons that are used for Approving/Rejecting then this block is either never called from Payment flow
	// or it's signatureVerificationCallback comes nil
	// B. If the terminal does not have buttons then the Application must present a user interface to Approve/Reject the Cardholder Signature
	func confirm(_ confirmationType: WDPaymentConfirmationType, paymentConfirmationResult: PaymentConfirmationResult? = nil) {
	if let paymentConfirmationResult = paymentConfirmationResult {
	// Here the simplified use of Approving the Cardholder Signature is demonstrated
	paymentConfirmationResult(WDPaymentConfirmationResult.approved)
	}
	}
	// Note: Applicable to terminals without BUTTONS
	// In the case the payment Card has more than one card application available then the client application
	// has to present user interface for the Cardholder to select preferred card application
	// The list of card applications is present in appSelectionRequest.appsArray as a list of Strings
	func cardApplication(_ appSelectionRequest: WDAppSelectionRequest) {
	// There is more than 1 card application available
	// Present the UI for the Cardholder to select preferred card application (Debit | Credit)
	if ((appSelectionRequest.appsArray?.count) != nil) {
	// Here we demonstrate the simplified use of selecting the first card application from the list of available card applications
	// and sending it to the Payment flow
	appSelectionRequest.selectCardApplication(UInt(0))
	}
	}
	// The end of the payment process
	func completion(_ saleResponse: WDSaleResponse?, saleResponseError: Error?) {
	//sale - Is the completed Sale - contains the sale status, details, results
	//error - If any error is encountered during the sale it would be reported
	//in the form of error and hierarchy of underlying errors to give you as much details as possible
	}
	}
	// Create the property for payment method handler somewhere in your controller
	static let paymentHandler = PaymentHandler()
	//
	// The minimum body of the Payment method is shown here
	//
	func pay(){
	// The SDK is initialized as shared instance so can be accessed
	// from multiple View Controllers
	let sdk: WDePOS = WDePOS.sharedInstance()
	//End of SDK setup process
	let setupCompletion: CurrentUserCompletion = {( currentUser:WDMerchantUser?, cashier:WDMerchantCashier? , error:Error?) in
	//Current User is returned upon successful login
	//if the Cash Management is enabled and Cashier record exist for the current user then the Cashier is returned also
	}
	// Set the SDK target environment - in this case Public Test
	// and the username and password to authenticate to it
	sdk.setup(with: WDEnvironment.publicTest,
	username: "yourUsername",
	password: "yourPassword",
	completion: setupCompletion)
	// Create the instance of the Sale Request
	// Here the minimum data is depicted[WDSSharedSessionManager shared]
	let saleRequest:WDSaleRequest = WDSaleRequestPurchase(uniqueId: "yourSaleUniqueID", // provide your unique ID to identify the Sale
	location: nil, // provide the GPS location for this payment e.g. the mobile device location
	inclusiveTaxes: true, // Tax inclusive/exclusive flag
	currency: "EUR", // Currency to use for this Sale
	note: "Test Sale", // Top level note for this sale
	gratuityTaxRate: nil // Gratuity tax rate - nil if no gratuity to be set later in the payment flow
	)!
	// Create one item named "Item 1" costing 10.00 EUR at 20% Tax
	saleRequest.addSaleItem(NSDecimalNumber(value: 10), // Item Unit price
	quantity: NSDecimalNumber(value: 10), // Item Quantity
	taxRate: NSDecimalNumber(value: 20), // Item Tax rate
	itemDescription: "Item 1", // Item description
	productId: nil,
	externalProductId: nil // External product ID - in the case you are using ERP - such as SAP and wish to refer to the product
	)
	// Discover active terminals and use it - in this case we use the first one
	// Alternatively use the one discovered previously and stored in an instance variable (or user preferences)
	sdk.terminalManager.discoverDevices(WDExtensionTypeUUID.WDPosMateExtensionUUID) { (terminals:[WDTerminal]?, error:Error?) in
	if let terminalsArr = terminals{
	//Here we assume that at least one terminal is present
	let terminal:WDTerminal! = terminalsArr.first
	// Set this Sale to be settled by Card transaction
	saleRequest.addCardPayment(NSDecimalNumber(value: 10), terminal: terminal!)
	// and half by Cash transaction (5 EUR)
	saleRequest.addCashPayment(NSDecimalNumber(value: 5))
	// Create Payment Configuration to be used in the Sale API later
	let paymentConfiguration: WDSaleRequestConfiguration! = WDSaleRequestConfiguration(saleRequest: saleRequest)
	// Start the Payment flow
	sdk.saleManager.pay(paymentConfiguration, with: type(of:self).paymentHandler) // Block to be executed at the end of the Payment process
	}
	else{
	NSLog("No active terminal found")
	}
	}
	}

view raw WDePOS-Payment.swift hosted with ❤ by GitHub

The code demonstrates very simplistic usage of each unit of behaviour

	import com.jakewharton.rxrelay2.BehaviorRelay;
	import com.jakewharton.rxrelay2.Relay;
	import de.wirecard.epos.util.events.Event;
	import de.wirecard.epos.util.events.TerminalEvent;
	import de.wirecard.epos.util.events.acceptance.AppSignatureConfirmationEvent;
	import io.reactivex.android.schedulers.AndroidSchedulers;
	Relay<Event> eventRelay = BehaviorRelay.create();
	eventRelay
	.observeOn(AndroidSchedulers.mainThread())
	// Updates during the payment flow
	.subscribe(event -> {
	if (event instanceof TerminalEvent.SignatureRequest) {
	// In the case when the Cardholder Signature is required by the Payment flow
	// Your task is to respond to it by collecting the signature image from the customer and
	// posting it back in the signatureEntered method
	String img = "signature image in Base64 format";
	((TerminalEvent.SignatureRequest) event).signatureEntered(img.getBytes()); // image in base 64
	((TerminalEvent.SignatureRequest) event).signatureCanceled(); // sale canceled, because signature was not collected
	}
	else if (event instanceof TerminalEvent.SignatureConfirmation) {
	// In the case when the Cardholder Signature was collected then the merchant is required to confirm its validity
	// A. If the terminal has buttons that are used for Approving/Rejecting then this is either never called from Payment flow
	// or its AppSignatureConfirmationEvent comes null
	// B. If the terminal does not have buttons then the Application must present a user interface to Approve/Reject the Cardholder Signature
	((TerminalEvent.SignatureConfirmation) event).getEnteredSignature(); // signature confirmation can be performed in terminal or in app
	if (event instanceof AppSignatureConfirmationEvent) { // this event indicates it has to be confirmed in app side
	((AppSignatureConfirmationEvent) event).signatureConfirmed(); // signature confirmed in app
	((AppSignatureConfirmationEvent) event).signatureCanceled(); // signature confirmation canceled in app
	}
	}
	else if (event instanceof TerminalEvent.PaymentInfo) {
	// provided some information during payment which can be shown to user
	((TerminalEvent.PaymentInfo) event).getAppLabel();
	((TerminalEvent.PaymentInfo) event).getApplicationId();
	((TerminalEvent.PaymentInfo) event).getCardholderName();
	((TerminalEvent.PaymentInfo) event).getPanTag();
	}
	else if (event instanceof Event.Update) {
	// update events indicates change of progress
	((Event.Update) event).getMessage(context);
	}
	else if (event instanceof Event.PasswordConfirmation) {
	//wechat payment method can ask for confirmation, that customer entered pin
	onPasswordConfirmation((Event.PasswordConfirmation) event);
	}
	});

view raw EposSDK-Payment.java hosted with ❤ by GitHub

Universal Windows Platform SDK coming soon