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
Get the SDK
Add the following in your app-level build.gradle:
- Kotlin
- Groovy
dependencies {
implementation("com.braintreepayments.api:union-pay:4.49.1")
}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:
- Kotlin
- Java
class MyActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState);
braintreeClient = BraintreeClient(this, "<#CLIENT_AUTHORIZATION#>");
unionPayClient = UnionPayClient(braintreeClient);
}
private fun fetchUnionPayCapabilities() {
unionPayClient.fetchCapabilities("4111111111111111") { capabilities, error ->
// inspect Union Pay capabilities
}
}
}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.
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.
- Kotlin
- Java
class MyActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState);
braintreeClient = BraintreeClient(this, "<#CLIENT_AUTHORIZATION#>");
unionPayClient = UnionPayClient(braintreeClient);
}
private fun enrollUnionPay() {
// Collect the card details and customer's mobile phone number to enroll
val unionPayCard = UnionPayCard();
unionPayCard.number = "4111111111111111";
unionPayCard.expirationMonth = "12";
unionPayCard.expirationYear = "22";
unionPayCard.cvv = "123";
unionPayCard.postalCode = "12345";
unionPayCard.mobileCountryCode = "1";
unionPayCard.mobilePhoneNumber = "1234567890";
unionPayClient.enroll(unionPayCard) { enrollment, error ->
unionPayCard.smsCode = "1234";
unionPayCard.enrollmentId = enrollment.id;
tokenizeUnionPay(unionPayCard);
}
}
private fun tokenizeUnionPay(unionPayCard: UnionPayCard) {
unionPayClient.tokenize(unionPayCard) { cardNonce, error ->
// send cardNonce.string to your server
}
}
}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.