UnionPay
Client-Side Implementation
Checkout form
Dual-branded cards
Dual-branded cards include both the UnionPay logo and another card brand logo – such as Visa, Mastercard, or American Express – and can be processed through either brand's network. If your business is based outside of China, card network rules around dual-branded UnionPay cards dictate that your customers must be able to select which card brand they want their transaction to process through at checkout.
To maintain compliance with this rule, make sure to include an option in your checkout form for customers to select UnionPay as their card brand. You should only process UnionPay cards directly via the UnionPay network if the customer specifies that they want the card processed this way. Otherwise, dual-branded cards should be processed via the other card brand network.
Card capabilities
UnionPay cards can either be credit or debit. This capability determines what information you will need to collect in your checkout form, as well as your options for processing the transaction on your server:
- Credit cards
- Require CVV and expiration date
- Support both immediate and delayed settlement – you can either submit the transaction for settlement upon creation or make a separate submit for settlement call
- Debit cards
- Do not always require CVV or expiration date
- Support only immediate settlement
Setup
To set up the Braintree Android SDK, see the installation guide.
Check card capabilities
UnionPay only supports authorization via client tokens.
Use the card number to check the card capabilities. 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:
- Java
mBraintreeFragment = BraintreeFragment.newInstance(activity, "CLIENT_TOKEN_FROM_SERVER");
// When the customer has finished entering the card number
UnionPay.fetchCapabilities(mBraintreeFragment, cardNumber);
@Override
public void onCapabilitiesFetched(UnionPayCapabilities capabilities) {
// Determines if the card is UnionPay
if (capabilities.isUnionPay()) {
// Persist UnionPayCapabilities for configuration changes
mUnionPayCapabilities = capabilities;
if (!mUnionPayCapabilities.isSupported()) {
// This UnionPay card can't be processed by Braintree.
// Ask the customer to try a different card
return;
}
if (mUnionPayCapabilities.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 us to tokenize the card.
If the enrollment indicates that the SMS code is not required, you can tokenize it immediately.
Begin by collecting the card details and customer's mobile phone number:
- Java
mUnionPayCardBuilder.mobileCountryCode("62")
.mobilePhoneNumber("11111111111");
UnionPay.enroll(mBraintreeFragment, mUnionPayCardBuilder);
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:
- Java
@Override
public void onSmsCodeSent(String enrollmentId, boolean smsCodeRequired) {
// Persist enrollmentId for configuration changes
mEnrollmentId = enrollmentId;
if (smsCodeRequired) {
// Get SMS auth code from customer input
waitForAuthCodeFromCustomer(new AuthCodeListener() {
@Override
public void onAuthCodeSubmittedFromCustomer(String authCode) {
// Add the SMS auth code and enrollment ID to the UnionPayCardBuilder
mUnionPayCardBuilder.smsCode(authCode);
mUnionPayCardBuilder.enrollmentId(mEnrollmentId);
UnionPay.tokenize(mBraintreeFragment, mUnionPayCardBuilder);
}
});
} else {
// No SMS auth code sent to the customer, tokenize immediately.
// Add the enrollment ID to the UnionPayCardBuilder
mUnionPayCardBuilder.enrollmentId(mEnrollmentId);
UnionPay.tokenize(mBraintreeFragment,mUnionPayCardBuilder);
}
}
Handling cancel and error responses
Attaching a BraintreeErrorListener
to BraintreeFragment
allows your app to view any error
responses coming back from BraintreeFragment
.
Use this to check for any issues during fetchCapabilities
and enroll
:
- Java
@Override
public void onError(Exception error) {
// Check the error for any issues with fetching capabilities or enrolling.
}
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 Page: Server-side →