UnionPay

UnionPay

This class represents a UnionPay component. Instances of this class have methods for fetching capabilities of UnionPay cards, enrolling a UnionPay card, and tokenizing a UnionPay card.

Constructor

new UnionPay(options)

You cannot use this constructor directly. Use braintree-web.unionpay.create instead.

Parameters:
Name Type Description
options object

See unionpay.create.
Source:

Methods

enroll(options, callback) → {void}

Enrolls a UnionPay card. Use fetchCapabilities to determine if the SMS enrollment process is required.

Parameters:
Name Type Description
options object

UnionPay enrollment options:

Properties
Name Type Attributes Description
card object <optional>

The card to enroll. Required if you are not using the hostedFields option.

Properties
Name Type Attributes Description
number string

The card number.
expirationDate string <optional>

The card's expiration date. May be in the form MM/YY or MM/YYYY. When defined expirationMonth and expirationYear are ignored.
expirationMonth string <optional>

The card's expiration month. This should be used with the expirationYear parameter. When expirationDate is defined this parameter is ignored.
expirationYear string <optional>

The card's expiration year. This should be used with the expirationMonth parameter. When expirationDate is defined this parameter is ignored.
hostedFields HostedFields <optional>

The Hosted Fields instance used to collect card data. Required if you are not using the card option.
mobile object

The mobile information collected from the customer.

Properties
Name Type Description
countryCode string

The country code of the customer's mobile phone number.
number string

The customer's mobile phone number.
callback callback

The second argument, data, is a enrollPayload.
Source:
Examples

With raw card data

unionpayInstance.enroll({
  card: {
    number: '4111111111111111',
    expirationMonth: '12',
    expirationYear: '2038'
  },
  mobile: {
    countryCode: '62',
    number: '111111111111'
  }
}, function (enrollErr, response) {
  if (enrollErr) {
     console.error(enrollErr);
     return;
  }

  if (response.smsCodeRequired) {
    // If smsCodeRequired, wait for SMS auth code from customer
    // Then use response.enrollmentId during UnionPay#tokenize
  } else {
    // SMS code is not required from the user.
    // UnionPay#tokenize can be called immediately
});

With Hosted Fields

unionpayInstance.enroll({
  hostedFields: hostedFields,
  mobile: {
    countryCode: '62',
    number: '111111111111'
  }
}, function (enrollErr, response) {
  if (enrollErr) {
    console.error(enrollErr);
    return;
  }

  if (response.smsCodeRequired) {
    // If smsCodeRequired, wait for SMS auth code from customer
    // Then use response.enrollmentId during UnionPay#tokenize
  } else {
    // SMS code is not required from the user.
    // UnionPay#tokenize can be called immediately
  }
});

fetchCapabilities(options, callback) → {void}

Fetches the capabilities of a card, including whether or not the SMS enrollment process is required.

Parameters:
Name Type Description
options object

UnionPay fetchCapabilities options

Properties
Name Type Attributes Description
card object <optional>

The card from which to fetch capabilities. Note that this will only have one property, number. Required if you are not using the hostedFields option.

Properties
Name Type Description
number string

Card number.
hostedFields HostedFields <optional>

The Hosted Fields instance used to collect card data. Required if you are not using the card option.
callback callback

The second argument, data, is a fetchCapabilitiesPayload.
Source:
Examples

With raw card data

unionpayInstance.fetchCapabilities({
  card: {
    number: '4111111111111111'
  }
}, function (fetchErr, cardCapabilities) {
  if (fetchErr) {
    console.error(fetchErr);
    return;
  }

  if (cardCapabilities.isUnionPay) {
    if (cardCapabilities.unionPay && !cardCapabilities.unionPay.isSupported) {
      // Braintree cannot process this UnionPay card.
      // Ask the user for a different card.
      return;
    }

    if (cardCapabilities.isDebit) {
      // CVV and expiration date are not required
    } else {
      // CVV and expiration date are required
    }

    // Show mobile phone number field for enrollment
  }
});

With Hosted Fields

// Fetch capabilities on `blur` inside of the Hosted Fields `create` callback
hostedFieldsInstance.on('blur', function (event) {
  // Only attempt to fetch capabilities when a valid card number has been entered
  if (event.emittedBy === 'number' && event.fields.number.isValid) {
    unionpayInstance.fetchCapabilities({
      hostedFields: hostedFieldsInstance
    }, function (fetchErr, cardCapabilities) {
      if (fetchErr) {
        console.error(fetchErr);
        return;
      }

      if (cardCapabilities.isUnionPay) {
        if (cardCapabilities.unionPay && !cardCapabilities.unionPay.isSupported) {
          // Braintree cannot process this UnionPay card.
          // Ask the user for a different card.
          return;
        }
        if (cardCapabilities.isDebit) {
          // CVV and expiration date are not required
          // Hide the containers with your `cvv` and `expirationDate` fields
        } else {
          // CVV and expiration date are required
        }
      } else {
        // Not a UnionPay card
        // When form is complete, tokenize using your Hosted Fields instance
      }

      // Show your own mobile country code and phone number inputs for enrollment
    });
  });
});

teardown(callbackopt) → {void}

Cleanly tear down anything set up by create. This only needs to be called when using UnionPay with Hosted Fields.

Parameters:
Name Type Attributes Description
callback callback <optional>

Called once teardown is complete. No data is returned if teardown completes successfully.
Source:
Example
unionpayInstance.teardown(function (teardownErr) {
  if (teardownErr) {
    console.error('Could not tear down UnionPay.');
  } else {
    console.log('UnionPay has been torn down.');
  }
});

tokenize(options, callback) → {void}

Tokenizes a UnionPay card and returns a nonce payload.

Parameters:
Name Type Description
options object

UnionPay tokenization options:

Properties
Name Type Attributes Default Description
card object <optional>

The card to enroll. Required if you are not using the hostedFields option.

Properties
Name Type Attributes Description
number string

The card number.
expirationDate string <optional>

The card's expiration date. May be in the form MM/YY or MM/YYYY. When defined expirationMonth and expirationYear are ignored.
expirationMonth string <optional>

The card's expiration month. This should be used with the expirationYear parameter. When expirationDate is defined this parameter is ignored.
expirationYear string <optional>

The card's expiration year. This should be used with the expirationMonth parameter. When expirationDate is defined this parameter is ignored.
cvv string <optional>

The card's security number.
hostedFields HostedFields <optional>

The Hosted Fields instance used to collect card data. Required if you are not using the card option.
enrollmentId string

The enrollment ID from UnionPay#enroll.
vault boolean <optional>
 false

When true, will vault the tokenized card. Cards will only be vaulted when using a client created with a client token that includes a customer ID.
smsCode string <optional>

The SMS code received from the user if UnionPay#enroll payload have smsCodeRequired. if smsCodeRequired is false, smsCode should not be passed.
callback callback

The second argument, data, is a tokenizePayload.
Source:
Examples

With raw card data

unionpayInstance.tokenize({
  card: {
    number: '4111111111111111',
    expirationMonth: '12',
    expirationYear: '2038',
    cvv: '123'
  },
  enrollmentId: enrollResponse.enrollmentId, // Returned from enroll
  smsCode: '11111' // Received by customer's phone, if SMS enrollment was required. Otherwise it should be omitted
}, function (tokenizeErr, response) {
  if (tokenizeErr) {
    console.error(tokenizeErr);
    return;
  }

  // Send response.nonce to your server
});

With Hosted Fields

unionpayInstance.tokenize({
  hostedFields: hostedFieldsInstance,
  enrollmentId: enrollResponse.enrollmentId, // Returned from enroll
  smsCode: '11111' // Received by customer's phone, if SMS enrollment was required. Otherwise it should be omitted
}, function (tokenizeErr, response) {
  if (tokenizeErr) {
    console.error(tokenizeErr);
    return;
  }

  // Send response.nonce to your server
});

Type Definitions

enrollPayload :object

Properties:
Name Type Description
enrollmentId string

UnionPay enrollment ID. This value should be passed to tokenize.
smsCodeRequired boolean

UnionPay smsCodeRequired flag.

true - the user will receive an SMS code that needs to be supplied for tokenization.

false - the card can be immediately tokenized.
Source:

fetchCapabilitiesPayload :object

Properties:
Name Type Description
isUnionPay boolean

Determines if this card is a UnionPay card.
isDebit boolean

Determines if this card is a debit card. This property is only present if isUnionPay is true.
unionPay object

UnionPay specific properties. This property is only present if isUnionPay is true.

Properties
Name Type Description
supportsTwoStepAuthAndCapture boolean

Determines if the card allows for an authorization, but settling the transaction later.
isSupported boolean

Determines if Braintree can process this UnionPay card. When false, Braintree cannot process this card and the user should use a different card.
Source:

tokenizePayload :object

Properties:
Name Type Description
nonce string

The payment method nonce.
type string

Always CreditCard.
details object

Additional account details:

Properties
Name Type Description
cardType string

Type of card, ex: Visa, MasterCard.
lastTwo string

Last two digits of card number.
description string

A human-readable description.
Source: