BuildPaySDK Developer Guide

Overview

BuildPaySDK seamlessly connects your iOS applications to Build, enabling secure card provisioning. It allows cardholders to add card details directly to their device’s payment wallet from within the app, eliminating the need for manual input.

SDK Features

  • Query card theme style
  • Query card details
  • Add cards to Apple Wallet directly from within the app

Requirements

To begin, ensure you have the following:

  • BuildPaySDK installed
  • Xcode IDE installed
  • **Apple Wallet permissions:**Required for adding cards to Apple Wallet. Getting Started with Apple Wallet (link to Apple’s official documentation)

iOS SDK Integration Guide

Adding the Framework to Your Project

  1. Open your project in Xcode.
  2. In the Project Navigator, select your project to open the Project Editor.
  3. Choose the target for your project.
  4. In the General tab, scroll to the Frameworks, Libraries, and Embedded Content section and click +.
  5. Click Add Other… and navigate to BuildPaySDK.xcframework.
  6. Select the framework, click Open, and then click Finish.
  7. Ensure that Embed & Sign is selected.

Initialize BuildPaySDK

  1. Do the following to configure your project:
#import <BuildPaySDK/BuildPaySDK.h>
  1. To configure SDK in your app, initialize the SDK by using the following method:
BuildPayAppConfig *config = [[BuildPayAppConfig alloc] init];
config.isDebug = NO;// if YES, will use test api, and log more information in console
config.uid = @"xxx";//build uid
config.customerId = @"";//customerId
config.deviceId = @"";//IDFV
config.secret = @"";//api secret key
config.clientId = @"";//your user id, used to mark users in logs.
config.isNetworkReportEnabled = YES;//Whether to allow network error reporting
config.netowkReportKey = @"xxx";//Key for network error reporting
[BuildPaySDK configureBuildPay:config completion:^(NSError * _Nullable error) {
    if (error == nil) {
        //success
    }
}];

Configuration Parameters

  • isDebug: YES for testing mode, NO for production.
  • uid: Unique identifier for Build (required).
  • customerId: Customer identifier (required).
  • deviceId:Unique identifier for device, like IDFV. (required).
  • secret: Api key, from server side, following Get secret (required).
  • clientId: Unique identifier for user tracking and logging (optional).
  • isNetworkReportEnabled: Whether to allow network error reporting, default is NO (optional).
  • netowkReportKey: Key for network error reporting (optional).

Add to Apple Wallet

Step 1: Create an “Add to Apple Wallet” Button

Use the system-provided button PKAddPassButton or create a custom button following Apple’s badge guidelines.

Step 2: Check Available Cards for the Device

Check if the card is available on the device to decide whether to show the Add to Apple Wallet button:

NSArray *cardSurffixArr = @[@"card surffix"];
[BuildPaySDK checkAppleWalletInfoWithCardNumberSurffixArray:cardSurffixArr completion:^(NSArray<BuildPayAppleWalletResult *> * _Nonnull array) {
    /*
    more infomation, see BuildPayAppleWalletResult.h
    BuildPayAppleWalletResult *result = array[0];
    result.cardIdentifier;
    result.needsShowAddWalletButtonInCurrentDevice;
    result.needsShowAddWalletButtonInRemoteSecureElement;
    result.hasBindCurrentDevice;
    result.hasBindRemoteSecureElement;
    result.hasAbilityWithRemoteSecureElement;
     */
}];

Step 3: Add card to AppleWallet

When the Add to Apple Wallet button is shown, use the following method to add the card to the device:

[BuildPaySDK addToWalletWithCardIdentifier:@"card_id" fromViewController:fromController phoneLast4:@"phone_last4" completionHandler:^(BOOL success, NSError * _Nullable error) {
    if (completion) {
        completion(success);
    }
    if (error) {
        //error
    }

}];

Note: After successfully adding the card, re-run the “Check Available Cards” method to update the button’s display.

Card Details Retrieval

To maintain security, sensitive data is encrypted. To retrieve card details:

[BuildPaySDK checkDetailInfoWithCardIdentifier:@"card_id" phoneLast4:@"phone_last4" completion:^(BuildPayCardDetailResult * _Nullable cardDetail, NSError * _Nullable error) {
    /*
    more infomation, see BuildPayAppleWalletResult.h
    cardDetail.cardIdentifier;
    cardDetail.cardNumber;
    cardDetail.holderName;
    cardDetail.expiry;
    cardDetail.cvv;
    */
}];

Note: Ensure you follow best practices for secure handling of sensitive information, such as storing card details in a secure manner and limiting access.

Retrieve Card Profile Information

To get the latest card theme information:

[BuildPaySDK checkCardProfileWithCardIdentifier:@"card_id" completion:^(BuildPayCardProfileResult * _Nullable cardResult, NSError * _Nullable error) {
   /*
    more infomation, see BuildPayAppleWalletResult.h
    cardResult.cardIdentifier;
    cardResult.profile;
    */
}];

Error Handling and Common Issues

  • Permissions: Ensure Apple Wallet permissions are configured correctly, as this is required for wallet-related functionality.
  • Error Codes: Each method’s completion block returns an NSError object if an error occurs. Refer to BuildPaySDK/BuildPayErrorDefine.h and Apple's documentation on error handling to resolve common errors.
  • Testing Mode: Set isDebug to YES for testing, which uses a sandbox API and outputs additional logs for troubleshooting.

Security Best Practices

  • Encryption: Always store card data securely and ensure sensitive information is encrypted.
  • Error Display: Provide clear feedback for errors related to Apple Wallet integration to enhance user experience.