@nuskin/payment-client

JavaScript client for the Nu Skin Payment Service web API

Usage no npm install needed!

<script type="module">
  import nuskinPaymentClient from 'https://cdn.skypack.dev/@nuskin/payment-client';
</script>

README

Payment Service Client

JavaScript client for the Nu Skin Payment Service web API

Installing

Using npm:

$ npm install @nuskin/payment-client

Using Yarn:

$ yarn add @nuskin/payment-client

Initializing the Client

Initialize a new instance of the client by providing the following parameters to the constructor:

  • baseURL - The Nu Skin Payment Service web API base URL. Currently, this is the base URL of Nu Skin's AWS cloud web services, e.g. "https://api.cloud.nuskin.com".
  • clientID - The Nu Skin web API client ID.
  • clientSecret - The Nu Skin web API client secret.
  • country - Country code of the market that requests will be made for.
  • language - Language code of the market that requests will be made for.
  • userID - ID of the user that requests will be made for.
  • userToken - Auth token (eid) of the user that requests will be made for.

If the client is to be used to perform payment tokenization, the following parameters are also required:

  • paymetricURL - Paymetric XI Intercept tokenization URL.
  • paymetricMerchantID - Paymetric merchant GUID.

Example:

import { PaymentClient } from "@nuskin/payment-client";

// Basic payment client
const client = new PaymentClient({
  baseURL: "https://api.cloud.nuskin.com",
  clientID: "0123...aeae",
  clientSecret: "8888...aa00",
  country: "US",
  language: "en",
  userID: "US1234567",
  userToken: "aBCd....3Au0"
});

// Payment client ready for tokenization
const clientWithTokenization = new PaymentClient({
  baseURL: "https://api.cloud.nuskin.com",
  clientID: "0123...aeae",
  clientSecret: "8888...aa00",
  country: "US",
  language: "en",
  userID: "US1234567",
  userToken: "aBCd....3Au0",
  paymetricURL: "https://paymetric-xi-intercept-url",
  paymetricMerchantID: "12ab...9999"
});

Using the Client

Retrieving Payment Type Context Information

Call .getAllowedPaymentTypes() to retrieve market-specific payment type context information.

The method returns a promise that resolves to a list of payment type context information objects.

Example:

client.getAllowedPaymentTypes()
.then(paymentTypeContexts => {
  ...
});

The following options can be provided to .getAllowedPaymentTypes() to receive a more specific set of payment type context information:

  • country - Country code of the market the request is being made for.
  • shipToCountry - Country code of the country that an order would be shipped to, if different from country.
  • shopContext - Shopping context identifier.
  • orderType - Order type context identifier: "SINGLE ORDER", "ADR CREATE", "ADR OVERRIDE", "ADR MANAGE", "SHIP IMMEDIATE", "PROFILE".

Example:

client.getAllowedPaymentTypes({
  country: "ZZ",
  shipToCountry: "AA",
  orderType: "ADR CREATE"
})
.then(paymentTypeContexts => {
  ...
});

Creating a New Payment

Call .createPayment(payment) to create and save a new payment for the user. The payment argument should be a Payment Object.

The method returns a promise that resolves to the created Payment Object.

Example:

client.createPayment({
  paymentTypeId: 0,
  paymentName: "John Doe",
  paymentNumber: "1234567890123456",
  ...
})
.then(savedPayment => {
  ...
});

Retrieving Saved Payments

Call .getAllSavedPayments() to retrieve the user's entire list of saved payments.

The method returns a promise that resolves to a list of Payment Objects.

Example:

client.getAllSavedPayments()
.then(payments => {
  ...
});

Call .getAllowedSavedPayments(contextOptions) to retrieve the user's saved payments that are allowed in the given context.

The context options provided to this method may include any/all of the following:

  • country - Country code of the market the request is being made for.
  • shipToCountry - Country code of the country that an order would be shipped to, if different from country.
  • shopContext - Shopping context identifier.
  • orderType - Order type context identifier: "SINGLE ORDER", "ADR CREATE", "ADR OVERRIDE", "ADR MANAGE", "SHIP IMMEDIATE", "PROFILE".

The method returns a promise that resolves to a list of Payment Objects.

Example:

client.getAllowedSavedPayments({
  country: "AA",
  orderType: "PROFILE"
})
.then(payments => {
  ...
});

Updating a Saved Payment

Call .updatePayment(payment) to update a saved payment. The payment argument should be a Payment Object.

Saved payments include a bePaymentTypeId property assigned by the server. This property must be present on the payment object provided to this method, otherwise the request will fail.

The method returns a promise that resolves to the updated Payment Object.

Example:

client.updatePayment({
  bePaymentTypeId: 123456,
  paymentTypeId: 0,
  paymentName: "Jane Doe",
  ...
})
.then(payment => {
  ...
});

Deleting a Saved Payment

Call .deletePayment(paymentID) to delete a saved payment. The paymentID argument should be the bePaymentTypeId of the payment to delete.

The method returns a promise that resolves to a boolean flag: true if the deletion was successful, false otherwise.

Example:

client.deletePayment(123456)
.then(hasSucceeded => {
  ...
})

Tokenizing a Payment Number

Call .tokenizePaymentNumber(pan) to convert a payment number to a payment token. The pan argument is the payment number to tokenize.

client.tokenizePaymentNumber("1234567890")
.then(tokenizedPAN => {
  ...
});

Alternatively, tokenization may be performed in a single step when creating a new payment by providing an additional options argument to .createPayment(), as shown in the following example:

client.createPayment(newPayment, {
  tokenize: true
})
.then(savedPayment => {
  ...
});

NOTE: successful tokenization requires the Payment Service Client to have been initialized as described in Initializing the Client.

Data Types

The following are the data types accepted and returned by the Payment Service Client.

Payment Objects

Payment objects accepted and returned by the Payment Service Client take the following form:

// Object representing a payment
interface Payment {
  // Payment ID
  // Set by the server when a payment is first created.
  // Do not alter.
  bePaymentTypeId?: number;

  // ID of the payment type associated with this payment
  paymentTypeId: number;

  // Payment type description
  // Set by the server.
  paymentTypeDescription?: string;

  // Name of payer
  paymentName: string;

  // Payment number
  // In new payments submitted for creation, this should be a raw or tokenized payment number
  // In saved payments returned by the client or submitted for updating, this is a masked payment number
  paymentNumber: string;

  // Tokenized payment number
  // Set by the server.
  // Do not alter.
  ccToken?: string;

  // Two-digit expiry month
  // Example: January = "01", February = "02", etc.
  expMonth?: string;

  // Two-digit expiry year
  // Example: year 2023 = "23"
  expYear?: string;

  // Billing address line 1
  address1?: string;

  // Billing address line 2
  address2?: string;

  // Billing city
  city?: string;

  // Billing district/county
  district?: string;

  // Billing region/state
  region?: string;

  // Billing country code
  countryCode?: string;

  // Billing postal code
  paymentPostalCode?: string;

  // Flag indicating whether this is the user's default payment
  defaultPayment?: boolean;
}

Payment Type Context Objects

Payment type context objects returned by the Payment Service Client take the following form:

// Object representing market-specific payment type information
interface PaymentTypeContext {
  // Payment type ID number
  id: number;

  // Payment type ID code: "VISA", "MC", "SDD", etc.
  ofsId: string;

  // Payment class: "CCARD", "WIRE", "DIRECTDEBIT", "COMPANYCREDIT"
  paymentClass: string;

  // Payment type localized name
  localizedName: string;

  // Name of legacy payment form associated with this payment type
  formName: string;

  // URL of payment type icon
  ccImageUrl?: string;

  // Flag indicating whether this payment type is blocked
  blocked?: boolean;

  // Flag indicating whether this payment type is disabled
  disabled?: boolean;

  // Payment processor ID code
  processorCode?: string;

  // Flag indicating whether installments are allowed with this payment type
  installmentsAllowed?: boolean;

  // Allowed installment numbers
  installmentNumbers?: number[];

  // Minimum installment amount
  minimumInstallmentAmount?: number;

  // Flag indicating whether this payment type requires client-side tokenization
  needsTokenization?: boolean;

  // Flag indicating whether this payment type requires a CVV
  cvvRequired?: boolean;
}

Handling Errors

Promises returned by the Payment Service Client may reject with either a plain Error instance or with a PaymentServiceError instance.

The PaymentServiceError class represents errors caused by the web API rejecting a request. The class takes the following form:

// Payment Service Error
class PaymentServiceError extends Error {
  // HTTP status code returned by the web API
  status: number;

  // List of messages returned by the web API
  messages: Array<{
    // Message level: "iNFO", "WARN", "ERROR"
    level: string;

    // Error code
    code: string;

    // Server exception type
    type: string;

    // Localized message text for display to the user
    message: string;

    // Technical message text for debugging
    technicalMessage: string;
  }>;
}

The list of messages included in a PaymentServiceError instance are intended to provide useful information to the user. The following is an example of how this might be handled:

import { PaymentClient, PaymentServiceError } from "@nuskin/payment-client";

const client = new PaymentClient({...});

client.createPayment(payment)
.then(...)
.catch(e => {
  if (e instanceof PaymentServiceError) {
    e.messages.forEach(msg => {
      // display error message text to the user
    })
  } else {
    // handle other types of error
  }
})