Home Checkout Tokenisation Payments Intent No-Code

Vault SDK

Follow this guide to use the Vault SDK if you are not using our Checkout SDK.

FYI, our Checkout SDK uses our Vault directly. Only use our Vault SDK if you are 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.

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