Web Content Display

Mobile Checkout SDKs

The Mobile Checkout SDKs provide a way to integrate Payoneer Orchestration Platform into native Android/iOS applications and enhance your checkout flow by displaying a payment method selection screen. The SDKs will render the available payment methods and handle all required communication to OPG to complete payment transactions.
 
Currently, our SDKs are in beta.
 
Supported Features
  • Credit/debit card payments are handled by the SDKs and allow you to keep a low PCI-DSS A rating
  • Direct payment methods (e.g. credit/debit cards, SEPA)
  • Real-time input validation
  • Credit/debit card SmartSwitch: certain credit/debit card schemes are offered as one option on the payment page; the form auto-detects the scheme based on the PAN entered by the end customer
  • Redirect payment methods (e.g. PayPal, Sofort) by using an external browser
  • Delayed Payment submission flow (Android Checkout SDK only)
  • Regular/recurring account registration
  • Custom theming: match the look & feel of the payment page to your shop application
 
Checkout SDK example applications
 
Both Checkout SDKs come with a "Checkout SDK Example" application which helps you get started with integrating the mobile SDKs into your native application. The examples demonstrate how to initialise and open the payment page and change the theme and receive payment results returned by the SDK.
 
Visualize your first payment page with example applications
 
The mobile SDKs consume LIST objects which were created with the MOBILE NATIVE integration (see https://www.optile.io/opg#24988394). Once you have a fully set-up merchant with configured contracts and routes on our Sandbox environment, create and paste a valid listUrl in the input field of either the Android or iOS Checkout SDK example application and hit the Show Payment Page button.
 
Github resources
Check out the resources here.

Web Content Display

iOS Checkout SDK

Note that the iOS Checkout SDK is still in beta phase and therefore may not be 100% stable. We encourage you to integrate and report any issues to our customer support: support.de@payoneer.com
 
Before you begin
  • Review the Mobile Checkout SDKs section for information relevant for both the Android and iOS Checkout SDK.
  • Review the MOBILE NATIVE integration documentation. This integration scenario is required for the iOS Checkout SDK. See Mobile Native reference.
  • Refer to our Github resources here.
 
Platforms
The minimum supported version is iOS 12.4
 
Examples

The iOS Checkout SDK comes with an example application, located in the /ExampleCheckout folder. To run the example application, run pod install in that folder and next open the ExampleCheckout.xcworkspace

Your first payment
To make a successful payment, complete the following process:
 
  1. Install the iOS Checkout SDK in your app
  2. Create a payment session and obtain the links.self URL from the LIST object.
  3. (Optional) Apply your custom theming to the payment page.
  4. Initialize and display the payment page using the links.self URL.
 
1. Install the iOS Checkout SDK
The iOS Checkout SDK is available through CocoaPods. To install it:
 
 a) Add the following line to your Podfile. For more on Podfile, see the Podfile reference.
target 'ExampleCheckout' do
  pod 'PayoneerCheckout', '~> latest_version'
end

b) Run pod install to integrate the pod into your application.

2. Create a payment session
Create a MOBILE_NATIVE integration payment session (see MOBILE NATIVE integration) and obtain the links.self URL from the LIST result. For a links.self example, see LIST request.
 
Create the LIST session from your backend system not the app.

 

3. Customise and control the payment page
If needed, you can customise the look and feel of the payment page. You can change the colors, shapes, and fonts to match the look and feel of your mobile shop application.
 
If you don't theme the page, we automatically apply the default theming.
 
Page theming
The theming of the iOS Checkout SDK screens, dialogs, and views is done using the Theme class. In order for theming to take effect, set the Theme.shared singleton to the custom Theme before showing the payment page.
See the example of custom theming on the right.
 
If you don't set a font (and you leave it set to nil), the default system font and sizes will be used.
When you set a custom font, all font sizes are automatically calculated based on the initial custom font's size. To increase or decrease all sizes set the size of the custom font.
 
 
4. Display the payment page
Initialise a view controller with links.self URL from the previous step and present it. Make sure you set delegate to handle the payment result.
 
let url: URL // URL obtained from links.self
let viewController = PaymentListViewController(listResultURL: url)
viewController.delegate = self
navigationController?.pushViewController(viewController, animated: true)

 

Currently only the push presentation style for the payment list view controller is supported.

 

Custom theming example

// Create a custom theme
let customTheme = Theme(
    font: UIFont(name: "Georgia", size: UIFont.preferredFont(forTextStyle: .body).pointSize)!,
    backgroundColor: .white,
    tableBorder: .init(red: 0.56, green: 0.58, blue: 0.60, alpha: 1),
    tableCellSeparator: .init(red: 0.94, green: 0.95, blue: 0.95, alpha: 1),
    textColor: .init(red: 0.2, green: 0.2, blue: 0.2, alpha: 1),
    detailTextColor: .init(red: 0.2, green: 0.2, blue: 0.2, alpha: 0.8),
    buttonTextColor: .white,
    tintColor: .init(red: 0, green: 0.26, blue: 0.67, alpha: 1),
    errorTextColor: .init(red: 1, green: 0.28, blue: 0, alpha: 1)
)

// Set the theme
Theme.shared = customTheme
Handle the payment result
After a payment has been attempted (either successfully or not) on the payment page, the Checkout SDK will return a payment result to your application through PaymentDelegate which was set when you created the payment list view controller. Manually dismiss the payment view controller after a payment result is received.
 
extension ViewController: PaymentDelegate {
  func paymentService(didReceivePaymentResult paymentResult: PaymentResult, viewController: PaymentListViewController) {
    print(paymentResult)
    navigationController?.popViewController(animated: true)
  }
}
 
Work with payment statuses
PaymentResult contains information about the payment status - it always contains either operationResult or errorInfo. 
 
To simplify parsing (to avoid optional unwrapping and working with an undefined state), use the computed variables resultInfo or interaction.
 
@objc public class PaymentResult: NSObject {
  public var operationResult: OperationResult?
  public var errorInfo: ErrorInfo?
  /// Contains value if something went wrong inside framework. In the most cases it would contain `InternalError` type.
  public var cause: Error?
  // MARK: Computed variables
  /// Contains result info from `operationResult` or `errorInfo`
  public var resultInfo: String
  /// A reference to `Interaction` object inside `operationResult` or `errorInfo`.
  public var interaction: Interaction
}
errorInfo will contain an error if something went wrong locally (e.g. connection problems or an internal error).  Server-side errors are contained in operationResult (e.g. payment was rejected). Make sure you check both properties for errors.

To perform any UI actions after the pop view controller dismissal animation, you can use the following extension:

 

extension UINavigationController {
  func popViewController(animated: Bool, completion: @escaping () -> Void) {
    popViewController(animated: animated)

    if let coordinator = transitionCoordinator, animated {
      coordinator.animate(alongsideTransition: nil) { _ in
        completion()
      }
    } else {
      completion()
    }
  }
}

Web Content Display

Android Checkout SDK

Please note that the Android Checkout SDK is still in beta phase and therefore may not be 100% stable. We encourage you to integrate and report any issues to our customer support at support.de@payoneer.com
 
Before you begin
  • Review the Mobile Checkout SDKs section for information relevant for both the Android and iOS Checkout SDK.
  • Review the MOBILE NATIVE integration documentation. This integration scenario is required for the Android Checkout SDK. See Mobile Native reference.
  • Refer to the Github resources here.
 
Platforms
This Android Checkout SDK is built using the new AndroidX material libraries and supports the Android API versions 21 - 30 (Lollipop 5.0 - Android 11).
 
Examples
The Android Checkout SDK comes with the following examples:
 
  • The Checkout SDK Example: it allows you to visualise payment pages quickly and debug possible results. The sources can be found here.
  • The Checkout Shop Example: it shows you how you could integrate the SDK into a real shop application. The sources can be found here.
 
Your first payment
To make a successful payment, complete the following process:
 
  1. Install the Android Checkout SDK in your app.
  2. Create a payment session and obtain the links.self URL from the LIST object.
  3. (Optional) Apply your custom theming to the payment page.
  4. Initialise and display the payment page using the links.self URL.
 
1. Install Android Checkout SDK
To install the Android Checkout SDK add the Android Checkout SDK dependency to your application Gradle build files. Follow the steps below:
 
a) Add the packagecloud.io repository to the top level build.gradle file, located in the root project directory.
 
allprojects {
    repositories {
        maven {
            url "https://packagecloud.io/optile/android/maven2"
        }
    }
}
b) Add the android-sdk dependency to the dependencies section in the app's build.gradle file, located in the app's module directory.
 
dependencies {
    implementation "com.payoneer:checkout-android:latest_version"
}
 
c) Add the following Activity definition in the AndroidManifest.xml file of the android app. 
 
This is required to enable payment with redirect networks (where the SDK opens a 3rd party website in a custom browser tab). Without it, the customer can't be taken back to the app once they've completed the process.
 
View the example below to see how to add the Activity:
 
 <activity
     android:name="com.payoneer.checkout.redirect.PaymentRedirectActivity"
     android:launchMode="singleTask">
     <intent-filter>
         <action android:name="android.intent.action.VIEW"/>
         <data android:scheme="${applicationId}.mobileredirect"/>
         <category android:name="android.intent.category.DEFAULT"/>
         <category android:name="android.intent.category.BROWSABLE"/>
    </intent-filter>
</activity>
 
2. Create a payment session
Create a MOBILE_NATIVE integration payment session (see Mobile Native integration) and obtain the links.self URL from the LIST result. For a links.self example, see LIST request.
 
Create the LIST session from your backend system not the app

 

3. (Optional) Customise and control the payment page
 
If needed, you can customize the look and feel of the payment page. You can change the colors, shapes, and fonts to match the look and feel of your mobile shop application. The Android Checkout SDK interface is built using material.io. You can find more information on how material.io works here.
 
If you don't theme the page, we automatically apply the default theming. 
 
Page theming
 
The theming of the Android Checkout SDK screens, dialogs, and views is done using the PaymentTheme class. In order for theming to take effect, set the the customized PaymentTheme instance in the PaymentUI class before showing the payment page.
 
The PaymentTheme class contains a set of parameters defining the customized theming for the PaymentList and ChargePayment screens. You can find the default theming of the android-sdk in the themes.xml and styles.xml files.
 
Theming the PaymentList screen
 
To change the theme of the PaymentList screen:
1 Create a new theme in your themes.xml file and add material settings like primaryColor in this newly created theme. 
2. When the theme is in your themes.xml file, set it in the PaymentTheme. The PaymentList screen contains a toolbar with back button, so use a custom theme including theming of the toolbar. 
 
Code sample of how to create and set a custom PaymentList theme:
 
PaymentTheme.Builder builder = PaymentTheme.createBuilder();
builder.setPaymentListTheme(R.style.CustomTheme_Toolbar);
 
The examplecheckout-sdk app contains a themes.xml file that contains the custom theme for the PaymentList screen.
 
PaymentList fonts
 
You can change the font style of labels in the PaymentList screen by modifying the settings of the corresponding material typography attributes. 
 
Theming ChargePayment screen
 
Similarly to the theming of the PaymentList screen, you can also theme the ChargePayment screen by creating a custom theme and setting it in the PaymentTheme. Unlike the PaymentList screen, the ChargePayment screen doesn't contain a toolbar and the custom theme should not contain the theming of a toolbar.
 
Code sample of how to create and set a custom ChargePayment theme:
 
PaymentTheme.Builder builder = PaymentTheme.createBuilder();
builder.setChargePaymentTheme(R.style.CustomTheme_NoToolbar);
 
The themes.xml file in the example-sdk app also contains the custom theme without toolbar.
 
Page orientation
 
By default, the orientation of the payment page will be locked based on the orientation in which the payment page was opened. For example if the mobile app is shown in the landscape mode the payment page will also be opened in the landscape mode. This can't be changed anymore by rotating the phone.
 
Code sample of how to set the fixed orientation mode:
 
//
// Orientation modes supported by the Payment Page
// ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE
// ActivityInfo.SCREEN_ORIENTATION_PORTRAIT
// ActivityInfo.SCREEN_ORIENTATION_REVERSE_LANDSCAPE
// ActivityInfo.SCREEN_ORIENTATION_REVERSE_PORTRAIT
//
PaymentUI paymentUI = PaymentUI.getInstance();
paymentUI.setOrientation(ActivityInfo.SCREEN_ORIENTATION_LANDSCAPE);
paymentUI.showPaymentPage(this, PAYMENT_REQUEST_CODE);
 
 
 

 

Code sample how to create and set a custom PaymentTheme:

 

PaymentTheme.Builder builder = PaymentTheme.createBuilder();
builder.setPaymentListTheme(R.style.CustomTheme_Toolbar);
builder.setChargePaymentTheme(R.style.CustomTheme_NoToolbar);

PaymentUI paymentUI = PaymentUI.getInstance();
paymentUI.setPaymentTheme(builder.build());
paymentUI.showPaymentPage(this, PAYMENT_REQUEST_CODE);
4. Display the payment page
The Android SDK provides a class called PaymentUI which is used to initialise and display the payment page. You don't need to create an Activity to show the payment page - the Android SDK takes care of that. You need to implement the  onActivityResult() method to receive the result from the payment page Activity.  For details, see the Handling the payment result section.

View the code sample to see how to initialise and display the payment page:

 

// Request code to identify the response in onActivityResult()
int PAYMENT_REQUEST_CODE = 1;

// links.self URL obtained from your backend
String listUrl = "";

// Show the Payment Page
PaymentUI paymentUI = PaymentUI.getInstance();
paymentUI.setListUrl(listUrl);
paymentUI.showPaymentPage(this, PAYMENT_REQUEST_CODE)
Handle the payment result
After a payment has been attempted (either successfully or not) on the payment page Activity, the SDK will return a payment result to your application through the onActivityResult() method in the Activity.
 
To get a payment result:
 
1. Create a PaymentActivityResult from the parameters provided in the onActivityResult() method. The PaymentActivityResult is used to store the requestCode, resultCode and an optional PaymentResult returned by the Android-SDK.
 
2. Check the value of the resultCode. 
 
  • If the resultCode is Activity.RESULT_CANCELED, it means the user closed the payment page and no further information is available. 
  • When the resultCode is RESULT_CODE_PROCEED or RESULT_CODE_ERROR, the PaymentActivityResult contains a PaymentResult providing the information about the payment.
Code sample for obtaining the PaymentResult from the onActivityResult() method:
 
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
    PaymentActivityResult activityResult = PaymentActivityResult.fromActivityResult(requestCode, resultCode, data);
    handlePaymentActivityResult(activityResult);
}
 
private void handlePaymentActivityResult(PaymentActivityResult activityResult) {
 
    switch (activityResult.getResultCode()) {
        case PaymentActivityResult.RESULT_CODE_PROCEED:
        case PaymentActivityResult.RESULT_CODE_ERROR:
            PaymentResult paymentResult = activityResult.getPaymentResult();
            break;
 
        case Activity.RESULT_CANCELED:
            // This resultCode is returned when the user closed the payment page
    }
}
 
The resultInfo and Interaction can be obtained from the PaymentResult. The resultInfo contains a textual description of the result. The Interaction provides a recommendation on how to proceed.
 
Code sample of how to obtain the resultInfo and Interaction from the PaymentResult:
 
String resultInfo = paymentResult.getResultInfo();
Interaction interaction = paymentResult.getInteraction();
 
Payment Submission or Error
To make the processing of the payment result easier, the resultCode provided in the onActivityResult() method defines two flows. 
 
  • The payment submission flow (RESULT_CODE_PROCEED) used to indicate that the payment was successful or that the user may proceed to the next step, as used in Delayed Payment Submission mode. 
  • The error flow (RESULT_CODE_ERROR) used when the payment failed or an internal error occurred inside the Android SDK.
 
Work with the summary page (delayed payment submission)
In the delayed payment submission mode, the Android SDK will render a slightly different variation of the payment page. The only noticeable difference is the CTA (Call to Action) button which will be labeled "Continue" instead of "Pay". 
 
When clicked, the SDK will PRESET the selected method (without charging it), close the payment page and return a PaymentResult through the onActivityResult() method. At this stage, you may display a summary page to the end customer, typically with the final "Pay" button. 
 
Charging the PRESET account
When reloading, the ListResult from the Payment API contains a PresetAccount. This PresetAccount represents the payment method previously selected by the user in the payment page. You can use the Android SDK to charge this PresetAccount by using the chargePresetAccount() method in the PaymentUI class. After calling this method an Activity will be launched showing the sending progress and it will post a charge request to the Payment API. Once the charge is completed, the PaymentResult is returned through the onActivityResult() method.
 

Code sample for charging a PresetAccount:

 

// Request code to identify the response in onActivityResult()
int PAYMENT_REQUEST_CODE = 1;

// get the preset account from the ListResult
PresetAccount account = listResult.getPresetAccount();

// list URL obtained from your backend
String listUrl = "";

// Show the charge preset account page
PaymentUI paymentUI = PaymentUI.getInstance();
paymentUI.setListUrl(listUrl);
paymentUI.chargePresetAccount(this, PAYMENT_REQUEST_CODE, account);