availability

UnionPay is currently in beta and is only available to EU merchants. To request beta access, contact our Accounts team.

Setup

If you are using CocoaPods, add the following to your Podfile:

Ruby
pod 'Braintree/UnionPay', '~> 4.3.0'

If you are using Carthage, update your Cartfile:

Ruby
github 'braintree/braintree_ios' ~> 4.3.0

Next, run carthage update and add BraintreeUnionPay.framework to your app.

UnionPay only supports authorization via client tokens.

Card capabilities

UnionPay cards may or may not require additional information before they can be tokenized. For example, some older UnionPay debit cards do not have CVVs or expiration dates. These fields are not required if the customer's UnionPay card is debit.

Use the card number to check which information is necessary to process a UnionPay card. This should be done as soon as the customer has finished entering the card number, since you may need to update your form based on the response:

Objective-C Swift
#import "BraintreeUnionPay.h"

BTAPIClient *apiClient = [[BTAPIClient alloc] initWithAuthorization:@"CLIENT_TOKEN_FROM_SERVER"];
BTCardClient *cardClient = [[BTCardClient alloc] initWithAPIClient:apiClient];

// User has finished entering the card number
[cardClient fetchCapabilities:cardNumber completion:^(BTCardCapabilities *cardCapabilities, NSError *error) {
    if (error) { // Handle error
        return;
    }

    if (cardCapabilities.isUnionPay) {
        if (!cardCapabilities.isSupported) {
          // This UnionPay card cannot be processed by Braintree.
          // Ask the customer to try a different card
          return;
        }

        // Some older UnionPay debit cards do not have CVVs or expiration dates.
        // These fields are not required if cardCapabilities.isDebit == YES
        if (cardCapabilities.isDebit) {
            // CVV and expiration date fields not required
        } else {
            // CVV and expiration date fields required
        }
    }
    // Show mobile phone number field
}];

Enrollment and tokenization

UnionPay cards require enrollment before they can be tokenized. The enrollment process may require customer action, where UnionPay sends an authorization code via SMS to the customer's mobile phone number. Your integration then collects the SMS auth code from the customer and provides it to Braintree to tokenize the card.

If the enrollment indicates that the SMS code is not required, you can tokenize it immediately.

note

When an enrollment is completed for a UnionPay card, you will no longer be able to update the card number, expiration date, expiration month, or expiration year.

Begin by collecting the card details and customer's mobile phone number:

Objective-C Swift
BTCard *card = [[BTCard alloc] initWithNumber:@"6211111111111111" expirationMonth:@"12" expirationYear: @"2038" cvv: @"123"];
BTCardRequest *request = [[BTCardRequest alloc] initWithCard:card];
request.mobileCountryCode = @"62";
request.mobilePhoneNumber = @"11111111111";

[cardClient enrollCard:request completion:^(NSString *enrollmentID, NSError *error) {
    ...
}];

When attempting to enroll a UnionPay card, it is your responsibility to provide it with the enrollment ID and (if required) the SMS auth code collected from the customer during tokenization:

Objective-C Swift
[cardClient enrollCard:request completion:^(NSString *enrollmentID, BOOL smsCodeRequired, NSError *error) {
    if (error) {
        // Handle error
        return;
    }

    if (smsCodeRequired) {
      // Get SMS auth code from customer input

      [self getAuthCodeFromCustomer:^(NSString *authCode) {
          // Add the SMS auth code and enrollment ID to the card request
          request.smsCode = authCode;
          request.enrollmentID = enrollmentID;

          // Card is ready for tokenization
          [client tokenizeCard:request options:nil completion:^(BTCardNonce *cardNonce, NSError *error) {
              // Handle tokenization result
          }];
      }];
    } else {
      // No SMS auth code sent to the customer, tokenize immediately.
      // Add the enrollment ID to the card request
      request.enrollmentID = enrollmentID;

      // Card is ready for tokenization
      [client tokenizeCard:request options:nil completion:^(BTCardNonce *cardNonce, NSError *error) {
          // Handle tokenization result
      }];
    }
}];
note

Validating UnionPay is performed during the enrollment process. As such, there is no extra validation process that can be performed during tokenization and the validate property should not be passed when tokenizing a UnionPay card.

Special considerations

AVS and CVV validation does not apply

AVS and CVV validation does not apply to UnionPay cards, since the enrollment process handles card validation. Any AVS and CVV rules you've enabled for credit cards will be ignored for UnionPay cards.

Next: Testing →

Still Have Questions?

If you can’t find an answer, give us a call at 877.434.2894 or contact our Support team