WhenThen logoWhenThen logo
HomeCheckoutTokenisationPaymentsIntentNo-Code
Login
Contact Us
..

Intent SDK
Publicinfo icon

Installation

The Intent SDK is available on npm. See @whenthen/sdk-intent for an API Reference.

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

Install the Intent SDK package from npm public registry using npm or yarn.

Initialisation

import { WhenThenIntent } from '@whenthen/sdk-intent';

window.addEventListener('load', async () => {
  const intent = WhenThenIntent({ apiKey: 'PUBLIC_KEY_OR_CLIENT_TOKEN_XXX' });
  const { errors } = await intent.initialize();
});

Initialise the Intent SDK with your Public Key or a Client Token. You can view and manage your API keys in the WhenThen Web Application.

info icon

The Intent SDK must be initialized using the initialize() function before any checkout events are emitted.

WhenThenIntent() function also supports 2nd optional parameter: 

const intent = WhenThenIntent({
  apiKey: 'PUBLIC_KEY_OR_CLIENT_TOKEN_XXX',
  intentId: '84c76017-5c1c-4e23-b55e-c868f305d508'
});

Resume an existing Intent

Init Options Table

ValueType
  • intentIdString

    Allows restoring the previous Intent SDK state for the consequent updateIntent( ) and completeIntent( ) calls.

Init Result

Promise<{
	errors: Array<{ message: string; }>;
}>;

Start Intent

info icon

startIntent( ) will set the context for the consequent updateIntent( ) and completeIntent( ) calls. If the intent is already started - include intentId to options parameter of WhenThenIntent( ) function (See Init Options).

const { data, errors } = await intent.startIntent({
trackingId: '45ef20e0-7e1b-4b52-9e6e-a6dcd1db6792',
paymentFlowId: '88e5b224-1319-4040-9e43-c843372acfe1',
amount: {
    amount: 5999,
    currency: 'USD'
},
customer: {
    id: '65o5a442-1319-4040-9e43-c843372aclif',
    name: 'Joe Smith',
    email: 'john@test.com',
    isGuest: true
},
location: {
    country: 'USA'
},
cart: {
    id: '32fe20h0-7e1b-4b52-9e6e-a6dcd1db3609',
    weight: 12,
    itemCount: 1,
    items: [
      {
          id: '99l5h442-1319-4040-9e43-c843372acfil',
          quantity: 2,
          title: 'Some Title',
          variantTitle: 'Variant Title',
          weight: 64,
          taxable: true,
          requiresShipping: true,
          price: 30,
          sku: '69s3t442-3501-5050-9e43-c843372aflic',
          lineTotal: 100,
          image: 'https://image.url',
          discountedPrice: 21,
          totalDiscount: 21
      }
    ]
}
});
Start Intent Options Table
PropType
  • trackingIdString ﹡
    A unique tracking id for tracking the intent on your site e.g. an order id or checkout id.
  • paymentFlowIdString ﹡

    The id of payment flow to run this intent against.

    You can get this value from Settings -> Developers.

  • customerObject
    Customer object
  • customer.idString
    This can be your own customer id, or if you have a vault customer you can use that
  • customer.emailString
    Email of the customer to track
  • customer.nameString
    Name of the customer to track
  • customer.isGuestBoolean
    If the customer is a guest
  • amountObject ﹡
  • amount.amountnumber ﹡
    Total amount for checkout in minor units e.g. 5099 = 50.99
  • amount.currencyString ﹡

    ISO 4217 Code. Only "EUR" and "USD" currencies are supported at the moment.

  • locationObject
    If location is specified it will be used. If location is not specified we will use GeoLocation
  • location.countryString

    Three-letter country codes in ISO 3166-1 alpha-3.

  • cartObject
    Object describing the cart
  • cart.idString
    The id of the cart
  • cart.weightString
    The weight of the cart
  • cart.itemCountString
    The count of the cart items
  • cart.items[IntentCartItem] ﹡
    A list of cart items
Start Intent Result
Promise<{
  data: StartIntentOutput;
  errors: Array<{ message: string; }>;
}>;
StartIntentOutput
StartIntentOutput Table
PropType
  • idString
    The intent id for future use and updates
  • dateDate
    Date the intent was created
  • trackingIdString
    A unique tracking id for tracking the intent on your site e.g. an order id or checkout id
  • paymentFlowIdString
    The id of payment flow this intent is run against
  • currencyString

    ISO 4217 Code e.g. EUR

  • amountObject
  • amount.formattedAmountString
    Formatted amount
  • amount.rawAmountnumber
    Raw amount
  • statusObject

    Current status of this payment intent. See Checkout Status options

  • statusDateDate
    Date the last status was changed
  • locationObject
  • location.countryString

    Three-letter country codes in ISO 3166-1 alpha-3.

  • customerObject
    PII details are not exposed for SDK calls
  • customer.idString
    Id of the customer
  • customer.isGuestBoolean
    If the customer is a guest
  • timelineObject
    A timeline representing the status of various steps of the checkout stage
  • timeline.intentStartedObject
  • timeline.shippingObject
    Details for status of the shipping address section of the checkout form
  • timeline.deliveryObject
    Details for status of the delivery option section of the checkout form
  • timeline.billingObject
    Details for status of the billing address section of the checkout form
  • timeline.paymentAttempts[Object]
    Set when a payment attempt has been made
  • timeline.completeCheckoutObject
    Set when purchase is complete and completePaymentIntent is called
  • cartObject
    Object describing the cart
  • cart.idString
    The id of the cart
  • cart.weightString
    The weight of the cart
  • cart.itemCountString
    The count of the cart items
  • cart.items[IntentCartItem]
    A list of cart items

Update Intent

Use updateIntent( ) to update any of the intent details or status. For example, here we are changing the shipping form status to COMPLETE and delivery options status to IN_PROGRESS

const { data, errors } = await intent.updateIntent({
  shipping: {
    status: 'COMPLETE'
  },
  delivery: {
    status: 'IN_PROGRESS'
  }
});
Update Intent Options Table
PropType
  • trackingIdString
    A unique tracking id for tracking the intent on your site e.g. an order id or checkout id.
  • customerObject
    Customer object
  • customer.idString
    This can be your own customer id, or if ou have a vault customer you can use that
  • customer.emailString
    Email of the customer to track
  • customer.nameString
    Name of the customer to track
  • customer.isGuestBoolean
    If the customer is a guest
  • amountObject
  • amount.amountNumber
    Total amount for checkout in minor units e.g. 5099 = 50.99
  • amount.currencyString

    ISO 4217 Code e.g. EUR

  • locationObject
    If location is specified it will be used. If location is not specified we will use GeoLocation
  • location.countryString

    Three-letter country codes in ISO 3166-1 alpha-3.

  • cartObject
    Object describing the cart
  • cart.idString
    The id of the cart
  • cart.weightString
    The weight of the cart
  • cart.itemCountString
    The count of the cart items
  • cart.items[IntentCartItem] ﹡
    A list of cart items
  • billingObject
  • billing.statusString

    Status for billing address. See Form Step Status options

  • shippingObject
  • shipping.statusString

    Status for shipping address. See Form Step Status options

  • deliveryObject
  • delivery.statusString

    Status for delivery option. See Form Step Status options.

Update Intent Result
Promise<{
  data: UpdateIntentOutput;
  errors: Array<{ message: string; }>;
}>;
UpdateIntentOutput
UpdateIntentOutput Table
See Start Intent Result

Complete Intent

Call this when the payment is authorised and the customer has completed the checkout. The Intent will be updated to COMPLETE and the Intent will be linked to the payment in WhenThen. You should pass the reference for the payment from your payment processor in the API call in the paymentReference parameter.

When using the authorisePayment API, we automatically complete any linked Intent so you don't need to use this API. We handle the logic for you

info icon

Only use completeIntent if the payment is not being authorised using the WhenThen authorisePayment API

const { data, errors } = await intent.completeIntent({
  paymentReference: '88e5b224-1319-4040-9e43-c843372acfe1'
});
Complete Intent Options Table
PropType
  • paymentReferenceString
    The payment reference from the payment processor
Complete Intent Result
Promise<{
  data: CompleteIntentOutput;
  errors: Array<{ message: string; }>;
}>;
CompleteIntentOutput
CompleteIntentOutput Table
See Start Intent Result