npm package: @nuskin/payment-profile-sdk
Description: Client SDK for the payment profile service
Latest version: 1.1.2

# @nuskin/payment-profile-sdk

This SDK provides functions and data types for working with the Payment Profile API.

## Installing

Usng npm:

```bash
npm add @nuskin/payment-profile-sdk
```

Usng yarn:

```bash
yarn add @nuskin/payment-profile-sdk
```

---

## Example Usage

```js
import { PaymentProfileClient } from "@nuskin/payment-profile-sdk";

const client = new PaymentProfileClient({
  env: "prod",
  userSapId: "US12345678",
  userEid: "aBcD...1234",
  clientId: "1a2b...9e0f",
  clientSecret: "aaff...8080",
  market: "US",
  language: "en"
});
```

Parameters:

- `env`: (REQUIRED) runtime environment ("dev", "test", or "prod")
- `userSapId`: (REQUIRED) SAP ID of the user
- `userEid`: (REQUIRED) EID auth token of the user
- `clientId`: (REQUIRED) client ID
- `clientSecret`: (REQUIRED) client secret
- `market`: (REQUIRED) market country code
- `language`: (REQUIRED) market language code
- `paymetricMerchantGuid`: (_OPTIONAL_) Paymetric merchant GUID; required only for payment tokenization

### Get available payment types

This method retrieves a list of the payment types (e.g. VISA, MasterCard, SEPA, etc.) that are available for use in a given shopping context.

```js
const paymentTypes = await client.getPaymentTypesByContext({
  market: "NL",
  shipToCountry: "BE",
  shopContext: "PROFILE",
  orderType: "NO CONTEXT",
  isSignup: false
})
```

Parameters:

- `market` {string}: (_OPTIONAL_) market country code, if different from the payment profile client's market country code
- `shipToCountry` {string}: (_OPTIONAL_) country code to which orders would be shipped, if different from the market country code
- `shopContext` {string}: (_OPTIONAL_) shopping context for orders
- `orderType` {string}: (_OPTIONAL_) order type
- `isSignup` {boolean}: (_OPTIONAL_) flag indicating that this is a signup context

Resolves to a list of [Payment Type](#payment-type) objects.

### Get Saved Payments

This method retrieves a list of the user's saved payment methods.

```js
const payments = await client.getSavedPayments();
```

```js
const payments = await client.getSavedPayments({
  includeAll: true
});
```

Parameters:

- `includeAll` {boolean}: (_OPTIONAL_): Flag indicating that the returned saved payments should include all payment types, specifically those like WIRE and SEPA that would normally be omitted.

Resolves to a list of [Payment](#payment) objects.

### Save New Payment

This method saves a new payment method to the user's profile.

```js
const newPayment = {
  paymentTypeId: 2,
  paymentName: "John Doe",
  paymentNumber: "1234567890123456",
  paymentPostalCode: "9001",
  /* ... */
};

const savedPayment = await client.createPayment(newPayment);
```

Accepts a [Payment Draft](#payment-draft) object and resolves to a [Payment](#payment) object.

### Update Saved Payment

This method updates a saved payment method.

```js
const paymentToUpdate = {
  bePaymentTypeId: 314159
  paymentTypeId: 0,
  paymentName: "John Doe",
  paymentNumber: "*********1234",
  expMonth: "08",
  expYear: "29"
  /* ... */
};

const updatedPayment = await client.updatePayment(paymentToUpdate);
```

Accepts a [Payment](#payment) object and resolves to a [Payment](#payment) object.

### Delete Saved Payment

This method deletes a saved payment method from the user's profile.

```js
const paymentToDelete = {
  bePaymentTypeId: 314159
  paymentTypeId: 0,
  paymentName: "John Doe",
  paymentNumber: "*********1234",
  expMonth: "08",
  expYear: "29"
  /* ... */
};

await client.deletePayment(paymentToDelete.bePaymentTypeId);
```

Accepts the BE Payment Type ID (`bePaymentTypeId`) field of the payment method to delete. Resolves when the payment method is deleted successfully.

### Tokenize Payment Number

This method converts a given payment number to a token that can be used in that payment number's place.

```js
const tokenizedPaymentNumber = await client.tokenizePaymentNumber("1234567890123456");
```

Accepts a payment number (e.g. a CC number or IBAN) as a `string` and resolves to a token as a `string`.

### List of Payment Types

The SDK exposes an object containing the IDs of all supported payment types:

```js
import { PaymentTypes } from "@nuskin/payment-profile-sdk";

PaymentTypes.VISA // = 0

PaymentTypes.MC // = 1

PaymentTypes.JCB // = 21

PaymentTypes.SDD // = 54

PaymentTypes.CITI // = 121
```

### List of Credit Card Payment Types

The SDK also exposes a list of the payment type IDs of all credit-card payment types:

```js
import { CreditCardPaymentTypeIds } from "@nuskin/payment-profile-sdk";

CreditCardPaymentTypeIds; // [0, 1, 2, 3, 21, ...]
```

---

## Data Types

This SDK uses the following data types.

### Payment Type

Object representing a payment type and its settings.

- `id` {number}: Payment type ID.
- `ofsId` {string}: Payment type OFS ID.
- `blocked` {boolean}: Flag indicating that this payment type is blocked.
- `processorCode` {string}: Payment processor for this payment type.
- `formName` {string}: Name of the payment form used with this payment type.
- `paymentClass` {string}: Payment class.
- `localizedName` {string}: Payment type's localized name.
- `installmentsAllowed` {boolean}: Flag indicating that installments are allowed with this payment type.
- `binListInstallmentCheck` {boolean}: Flag indicating that a BIN list installment check is required.
- `cvvRequired` {boolean}: Flag indicating that a CVV code is required with this payment type.
- `needsTokenization` {boolean}: Flag indicating that this payment type requires tokenization.
- `hideInstallmentOptions` {boolean}: Flag indicating that installment options should be hidden.
- `updateTimestamp` {number}: timestamp when this payment type information was last updated.
- `context` {string}: context code to which this payment type information applies.

### Payment Draft

Object representing a new payment method to be saved.

- `paymentTypeId` {number}: ID of the payment type.
- `paymentName` {string}: (_OPTIONAL_) Payment name or billing name.
- `paymentNumber` {string}: (_OPTIONAL_) CC or IBAN number. Saved payments are returned with this field masked.
- `expMonth` {string}: (_OPTIONAL_) Two-digit string representing the month this payment expires. Examples: "01" = January, "12" = December.
- `expYear` {string}: (_OPTIONAL_) Two-digit string representing the year this payment expires. Examples: "99" = 1999, "00" = 2000, "25" = 2025.
- `address1` {string}: (_OPTIONAL_) Billing address line 1.
- `address2` {string}: (_OPTIONAL_) Billing address line 2.
- `city` {string}: (_OPTIONAL_) Billing address city.
- `district` {string}: (_OPTIONAL_) Billing address distric/county name.
- `region` {string}: (_OPTIONAL_) Billing address region/state code.
- `paymentPostalCode` (_OPTIONAL_) {string}: Billing address postal code.
- `countryCode` {string}: (_OPTIONAL_) Billing address country code.
- `email` {string}: (_OPTIONAL_) Billing email address.
- `phone` {string}: (_OPTIONAL_) Billing phone number.
- `ccToken` {string}: (_OPTIONAL_) Tokenized CC or IBAN number.
- `defaultPayment` {boolean}: (_OPTIONAL_) Flag indicating that this is the user's default payment method.
- `storedCredentialsAgreementDate` {string}: (_OPTIONAL_) Date when the stored credentials agreement was signed.
- `storedCredentialsNetworkTransactionId` {string}: (_OPTIONAL_) ID of the stored credentials network transaction.

### Payment

Object representing a saved payment method.

- `bePaymentTypeId` {number}: ID of this payment. Assigned by the server. Do not alter.
- `paymentTypeId` {number}: ID of the payment type.
- `paymentTypeDescription` {string}: (_OPTIONAL_) localized description of the payment type.
- `paymentName` {string}: (_OPTIONAL_) Payment name or billing name.
- `paymentNumber` {string}: (_OPTIONAL_) CC or IBAN number. Saved payments are returned with this field masked.
- `expMonth` {string}: (_OPTIONAL_) Two-digit string representing the month this payment expires. Examples: "01" = January, "12" = December.
- `expYear` {string}: (_OPTIONAL_) Two-digit string representing the year this payment expires. Examples: "99" = 1999, "00" = 2000, "25" = 2025.
- `address1` {string}: (_OPTIONAL_) Billing address line 1.
- `address2` {string}: (_OPTIONAL_) Billing address line 2.
- `city` {string}: (_OPTIONAL_) Billing address city.
- `district` {string}: (_OPTIONAL_) Billing address distric/county name.
- `region` {string}: (_OPTIONAL_) Billing address region/state code.
- `paymentPostalCode` (_OPTIONAL_) {string}: Billing address postal code.
- `countryCode` {string}: (_OPTIONAL_) Billing address country code.
- `email` {string}: (_OPTIONAL_) Billing email address.
- `phone` {string}: (_OPTIONAL_) Billing phone number.
- `ccToken` {string}: (_OPTIONAL_) Tokenized CC or IBAN number.
- `defaultPayment` {boolean}: (_OPTIONAL_) Flag indicating that this is the user's default payment method.
- `storedCredentialsAgreementDate` {string}: (_OPTIONAL_) Date when the stored credentials agreement was signed.
- `storedCredentialsNetworkTransactionId` {string}: (_OPTIONAL_) ID of the stored credentials network transaction.