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. Only call this method if the card needs to be enrolled. Use fetchCapabilities to determine if the user's card needs to be enrolled.

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 Description
number string

The card number.
expirationMonth string

The card's expiration month.
expirationYear string

The card's expiration year.
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 errback

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 (err, response) {
  if (err) {
     console.error(err);
     return;
  }

  // Wait for SMS auth code from customer
  // Then use response.enrollmentId in tokenization
});

With Hosted Fields

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

  // Wait for SMS auth code from customer
  // Then use response.enrollmentId in tokenization
});

fetchCapabilities(options, callback) → {void}

Fetches the capabilities of a card, including whether or not the card needs to be enrolled before use. If the card needs to be enrolled, use enroll.

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 errback

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

With raw card data

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

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

  if (cardCapabilities.unionPay && cardCapabilities.unionPay.isUnionPayEnrollmentRequired) {
    // Show mobile phone number field for enrollment
  }
});

With Hosted Fields

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

      if (cardCapabilities.isUnionPay) {
        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
      }

      if (cardCapabilities.unionPay && cardCapabilities.unionPay.isUnionPayEnrollmentRequired) {
        // 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 errback <optional>

Called once teardown is complete. No data is returned if teardown completes successfully.
Source:
Example
unionpayInstance.teardown(function (err) {
  if (err) {
    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 Description
card object

The card to enroll.

Properties
Name Type Description
number string

The card number.
expirationMonth string

The card's expiration month.
expirationYear string

The card's expiration year.
cvv string

The card's security number.
options object

Additional options.
enrollmentId string

The enrollment ID if UnionPay#enroll was required.
smsCode string

The SMS code recieved from the user if UnionPay#enroll was required.
callback errback

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' // Sent to customer's phone
}, function (err, response) {
  if (err) {
    console.error(err);
    return;
  }

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

With Hosted Fields

unionpayInstance.tokenize({
  hostedFields: hostedFieldsInstance,
  enrollmentId: enrollResponse.enrollmentId, // Returned from enroll
  smsCode: '11111' // Sent to customer's phone
}, function (err, response) {
  if (err) {
    console.error(err);
    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.
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.
isUnionPayEnrollmentRequired boolean

Notifies if enrollment should be completed.
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: