WhenThen

Tokenise

Using our PCI DSS Level 1 compliant Vault you can securely tokenise payment methods. Then, whenever you're ready to instruct, you can use a token to instruct with any payment processor using our simple API. All while minimizing your PCI scope.

info icon

FYI, our Checkout SDK communicates with our Vault. You only need to use our Vault SDK using Vault standalone or if you are building a custom checkout experience.

Installation

The WhenThen Vault SDK is available on npm. See @whenthen/sdk-vault for an API reference.

npm install --save @whenthen/sdk-vault
# or
yarn add @whenthen/sdk-vault

Install WhenThen Vault SDK package from npm public registry using npm or yarn.


Currently our SDKs are published as private packages so you will need to use the following auth token to install from npm

echo "//registry.npmjs.org/:_authToken=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" > .npmrc

Initialisation

import { WhenThenVault } from '@whenthen/sdk-vault';

const options = {
  apiKey: 'CLIENT_TOKEN_XXX',
};

window.addEventListener('load', async () => {
  const vault = WhenThenVault(options);
});

Initialise WhenThen Vault SDK. You'll need to generate a Client Token on your backend using a private key.

Create Options Table

ValueType
  • apiKeyString

    Initialise WhenThen Vault SDK with a Client Token.

How it works

The Vault API provides you with three methods: createCustomer( ),tokenisePaymentMethod( ), and getPaymentMethods( ).

Create Customer

Creates a customer. If payment method data is provided, it also creates a payment method and assigns it to the new customer. The payment method is tokenised and stored in our secure vault.

The createCustomer( ) API enables you to create and manage customers. To setup a card for future payments, you must attach it to a Customer. You can also use the Customer to build card on file solutions.

const { data, errors } = await vault.createCustomer({
  data: {
    customer: {
      billingAddress: {
        line1: 'Bartlett Avenue',
        line2: 'no. 4',
        city: 'Southfield',
        postalCode: '48076',
        state: 'Michigan',
        country: 'USA',
      },
      description: 'description',
      email: 'john@test.com',
      name: 'John Smith',
      phone: '406-694-3629',
      shippingAddress: {
        address: {
          line1: 'Gruenauer Strasse 55',
          city: 'Buchhorst',
          postalCode: '16567',
          state: 'Brandenburg',
          country: 'DEU',
        },
        name: 'John Smith',
        phone: '04153 79 44141',
      },
    },
  },
});
Create Customer Options Table
PropType
  • data.customerObject
    Customer object
  • customer.billingAddressObject
    The customer’s billing address
  • customer.descriptionstring
    An arbitrary string attached to the object
  • customer.emailstring
    The customer’s email address
  • customer.namestring
    The customer’s full name or business name
  • customer.phonestring
    The customer’s phone number
  • customer.shippingAddressObject
    Mailing and shipping address for the customer
  • customer.companyCompanyInput
    Company details for customer
Create Customer Result
Promise<{
  data: CreateCustomerOutput;
  errors: Array<{ message: string; type: string; }>;
}>;
CreateCustomerOutput
CreateCustomerOutput Table
PropType
  • idString
    Unique identifier for the customer

Tokenise Payment Method

You can securely store a payment method in our vault. You should use our recommended payments integrations to perform this process client-side. This ensures that no sensitive card data touches your server, and allows your integration to operate in a PCI-compliant way. The payment method is tokenised and we return you a token for future use.

If customer id is provided, it assigns the payment method to that customer. If customer data is provided, it creates a new customer and assigns the payment method to that customer.

const idempotencyKey = '90e14226-d9f7-431d-a1df-831a7b2a0c9b';

const { data, errors } = vault.tokenisePaymentMethod(
  {
    data: {
      paymentMethod: {
        card: {
          number: '4000056655665556',
          expMonth: 8,
          expYear: 2026,
          cvc: '342',
          name: 'John Smith',
          billingAddress: {
            line1: 'Bartlett Avenue',
            line2: 'no. 4',
            city: 'Southfield',
            postalCode: '48076',
            state: 'Michigan',
            country: 'USA',
          },
          isDefault: true,
        },
        bankAccount: {
          number: '123456',
          accountHolderName: 'John Smith',
          bankName: 'Golden Horizon',
        },
      },
      customer: {
        id: '421dd9b0-0af6-41ee-9fc5-48f42d5ad640',
      },
    },
  },

  idempotencyKey
);
Tokenise Payment Method Options Table
PropType
  • paymentMethodObject
  • paymentMethod.cardObject
    The card this token will represent
  • customerObject
    Customer details to associate to the token
  • customer.idstring
    Unique identifier for the customer
  • customer.billingAddressObject
    The customer’s address
  • customer.descriptionstring
    An arbitrary string attached to the object
  • customer.emailstring
    The customer’s email address
  • customer.namestring
    The customer’s full name or business name
  • customer.phonestring
    The customer’s phone number
  • customer.shippingAddressObject
    Mailing and shipping address for the customer
  • customer.companyCompanyInput
    Company details for customer
  • idempotencyKeystring
    A unique value generated by the client which the server uses to recognize subsequent retries of the same request
Tokenise Payment Method Result
Promise<{
  data: TokenisePaymentMethodDataOutput;
  errors: Array<{ message: string; type: string; }>;
}>;
TokenisePaymentMethodDataOutput
TokenisePaymentMethodDataOutput Table
PropType
  • idString
    Unique identifier for the object
  • tokenString
    Value of the card token
  • customerObject
  • customer.idString
    Unique identifier for the customer

Get Payment Methods

You can list customer payment methods.

const { data, errors } = await vault.getPaymentMethods({
  customerId: '421dd9b0-0af6-41ee-9fc5-48f42d5ad640',
});
Get Payment Methods Options Table
PropType
  • customerIdString
    Unique identifier for the customer
Get Payment Methods Result
Promise<{
  data: Array<PaymentMethod>;
  errors: Array<{ message: string; type: string; }>;
}>;
PaymentMethod
PaymentMethod Table
PropType
  • tokenString
    Value of the card token
  • numberString
    Masked card number
  • expMonthNumber
    Two-digit number representing the card’s expiration month
  • expYearNumber
    Four-digit number representing the card’s expiration year
  • nameString
    Cardholder name
  • isDefaultBooleam
    Is default payment method
  • brandString
    Card brand