WhenThen logoWhenThen logo
Login
Contact Us
arrow iconDOCS

The Intent feature is about showing active, inactive (and potentially lost) payments. It achieves this by the user dropping an SDK on their checkout page, which is activated when a user lands on the page to checkout.

Start Intent

Mutation
Client TokenPrivate KeyPublic Key

startIntent starts a new Intent and returns a unique intentId. This starts the process of tracking the lifecycle of the checkout. You can also use the intentId in subsequent API calls. This starts the tracking process of a new checkout. Starting a new Intent also starts a new a instance of a payment processing automation. You can use this intentId when calling Optimise or Authorise Payment.

You must pass us your flowId when starting an Intent.

Request

ValueType
  • trackingIdID ﹡

    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
  • customerIntentCustomerInput
    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
  • amountIntentAmountInput
  • amount.amountLong
    Total amount for checkout in in minor units e.g. 5099 = 50.99
  • amount.currencyString

    ISO 4217 Code e.g. EUR

  • locationIntentLocationInput
    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.

  • cartIntentCart
  • cart.idString
    The cart identifier
  • cart.weightInt
    Weight
  • cart.itemCountInt
    The count of items
  • cart.items[IntentCartItemType]
    A list of cart items
CURL
curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation startIntent($trackingId: ID!,$paymentFlowId: ID!, $customer: IntentCustomerInput, $amount: IntentAmountInput!, $location: IntentLocationInput, $cart: IntentCartInput) {
  startIntent(trackingId: $trackingId, paymentFlowId: $paymentFlowId,customer: $customer, amount: $amount, location: $location, cart: $cart) {
    id
    trackingId
    paymentFlowId
    status
    statusDate
    date
    currency
    amount {
        formattedAmount
    }
    location {
        country
    }
    customer {
        id
        isGuest
    }
    timeline {
        intentStarted {
            status
            date
        }
        shipping {
            status
            date
        }
        delivery {
            status
            date
        }
        billing {
            status
            date
        }
        paymentAttempts {
          status
          date
       }
       completeIntent {
          status
          date
       }
    }
    linkedPayments {
      paymentId
      status
      time
      title
    }
    cart {
      id
      weight
      itemCount
      items {
          id
          quantity
          title
          variantTitle
          weight
          taxable
          requiresShipping
          price
          sku
          lineTotal
          image
          discountedPrice
          totalDiscount
      }
    }
  }
}",
	"variables": {
		"trackingId": "9f45995a-5129-438d-9459-dc4678510918",
    "paymentFlowId": "e76c5829-9928-425f-a815-7024d9164f2a",
		"customer": {
        "isGuest": true
    },
		"amount": {
        "amount": 5999,
        "currency": "USD"
    }
	}
}'
https://api.whenthen.com/api/graphql

Response

ValueType
  • idBoolean
    The intent id for future use and updates
  • dateDateTime
    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 to run this intent against
  • currencyString

    ISO 4217 Code e.g. EUR

  • amountAmount
  • statusCheckoutStatus
    Current status of this payment intent
  • statusDateDateTime
    Date the last status was changed
  • locationCheckoutLocation
  • location.country

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

  • customerCheckoutCustomer
    PII details are not exposed for SDK calls
  • customer.idString
    Id of the customer
  • customer.isGuestBoolean
    If the customer is a guest
  • customer.emailBoolean
    Email of the customer (Not available using SDK or Public Key)
  • customer.nameBoolean
    Name of the customer (Not available using SDK or Public Key)
  • timelinetimeline
    A timeline representing the status of various steps of the checkout stage
  • timeline.intentStartedIntentTimelineStep
  • timeline.shippingIntentTimelineStep
    Details for status of the shipping address section of the checkout form
  • timeline.deliveryIntentTimelineStep
    Details for status of the delivery option section of the checkout form
  • timeline.billingIntentTimelineStep
    Details for status of the billing address section of the checkout form
  • timeline.paymentAttempts[IntentTimelineStep]
    Set when a payment attempt has been made
  • timeline.completeIntentIntentTimelineStep
    Set when purchase is complete and completePaymentIntent is called
  • linkedPayments[LinkedPayment]
    list payment attempt that has been made
  • linkedPayments.paymentIdString
    id of the linked payment
  • linkedPayments.statusPaymentStatus
    status of the payment
  • linkedPayments.timeDateTime
    time of the payment attempt
  • linkedPayments.titleString
    title of the payment attempt
  • cartIntentCart
  • cart.idString
    The cart identifier
  • cart.weightInt
    Weight
  • cart.itemCountInt
    The count of items
  • cart.items[IntentCartItemType]
    A list of cart items
JSON
{
   "id":"88b56c86-3e0f-4630-ae27-37b3dfa44ba2",
   "date":"2022-03-31T08:28:08.022971Z",
   "paymentFlowId":"1a1b53d2-e97d-4626-b8fc-20f758ae42c1",
   "trackingId":"d8c239e8-7bb5-4575-9473-ba0f3c67b97d",
   "currency":"USD",
   "amount":{
      "rawAmount":100,
      "currency":"USD",
      "formattedAmount":"$1.00"
   },
   "status":"ACTIVE",
   "statusDate":"2022-03-31T08:28:08.02318Z",
   "location":{
      "country":"USA"
   },
   "customer":{
      "id":null,
      "isGuest":true,
      "email":"test@email.com",
      "name":"Customer Name"
   },
   "timeline":{
      "intentStarted":{
         "status":"IN_PROGRESS",
         "date":"2022-03-31T08:28:08.024711Z"
      },
      "shipping":{
         "status":"NOT_STARTED",
         "date":null
      },
      "delivery":{
         "status":"NOT_STARTED",
         "date":null
      },
      "billing":{
         "status":"NOT_STARTED",
         "date":null
      },
      "paymentAttempts":[
         {
            "status":"NOT_STARTED",
            "date":null
         }
      ],
      "completeIntent":{
         "status":"NOT_STARTED",
         "date":null
      }
   },
   "linkedPayments":[
      {
         "paymentId":"payments:32e7a92b-aa07-48d9-86f2-b717c54d0e12",
         "status":"ACTIVE",
         "time":"2022-03-31T08:28:08.317531Z",
         "title":"Payment attempt #1"
      }
   ],
   "cart":{
      "id":"b5022fb1-1fc6-4791-a993-fe2fc5e19b0d",
      "weight":12,
      "itemCount":1,
      "items":[
         {
            "id":"4c5296c6-b3a8-4cb6-8a7e-2cb2cf4f3cad",
            "quantity":2,
            "title":"Test Title",
            "variantTitle":"Variant Title",
            "weight":64,
            "taxable":true,
            "requiresShipping":true,
            "price":30,
            "sku":"d4241bf4-618a-4f33-a843-e4b0ffb310c8",
            "lineTotal":100,
            "image":"some image url",
            "discountedPrice":21,
            "totalDiscount":21
         }
      ]
   }
}

Get Intent

Query
Client TokenPrivate KeyPublic Key

Use getIntent to get the details of a particular checkout by passing in the id.

Request

ValueType
  • idString ﹡
    The intent id
CURL
curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "query getIntent($id: ID!) {
    getIntent(id: $id) {
        id
        trackingId
        paymentFlowId
        status
        statusDate
        date
        currency
        amount {
            formattedAmount
            rawAmount
        }
        location {
            country
        }
        customer {
            id
            isGuest
            email
            name
        }
        timeline {
            intentStarted {
                status
                date
            }
            shipping {
                status
                date
            }
            delivery {
                status
                date
            }
            billing {
                status
                date
            }
            paymentAttempts {
              status
              date
            }
            completeIntent {
              status
              date
            }
        }
        linkedPayments {
          paymentId
          status
          time
          title
        }
        cart {
          id
          weight
          itemCount
          items {
              id
              quantity
              title
              variantTitle
              weight
              taxable
              requiresShipping
              price
              sku
              lineTotal
              image
              discountedPrice
              totalDiscount
          }
        }
     }
	}",
	"variables": {
    "id": "811ab3e2-6f24-493d-bcaa-a95395bc16a2"
	}
}'
https://api.whenthen.com/api/graphql

Response

Update Intent

Query
Client TokenPrivate KeyPublic Key

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 form status to IN_PROGRESS

Request

ValueType
  • idID ﹡
    The intent id for future use and updates
  • trackingIdString

    A unique tracking id for tracking the intent on your site

    e.g. an order id or checkout id

  • customerIntentCustomerInput
    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
  • amountIntentAmountInput
  • amount.amountLong
    Total amount for checkout in in minor units e.g. 5099 = 50.99
  • amount.currencyString

    ISO 4217 Code e.g. EUR

  • locationIntentLocationInput

    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.

  • cartIntentCartInput
  • cart.items[IntentCartItem]
    A list of cart items
  • billingIntentShippingInput
  • billing.statusFormStepStatus
    status for billing address
  • shippingIntentShippingInput
  • shipping.statusFormStepStatus
    status for shipping address
  • deliveryIntentDeliveryInput
  • delivery.statusFormStepStatus
    status for delivery option
CURL
curl
-X POST
-H "Content-Type: application/json"
-H "Authorization: Bearer xxxxxxx"
-d '{
	"query": "mutation updateIntent($id: ID!, $trackingId: String, $customer: IntentCustomerInput, $amount: IntentAmountInput, $shipping: IntentShippingInput, $delivery: IntentDeliveryInput, $location: IntentLocationInput) {
     updateIntent(id: $id, trackingId: $trackingId, customer: $customer, amount: $amount, shipping: $shipping, delivery: $delivery, location: $location){
        id
        trackingId
        paymentFlowId
        status
        date
        currency
        amount {
            formattedAmount
        }
        location {
            country
        }
        customer {
            id
            isGuest
        }
        timeline {
            intentStarted {
                status
                date
            }
            shipping {
                status
                date
            }
            delivery {
                status
                date
            }
            billing {
                status
                date
            }
            completeCheckout {
                status
                date
            }
        }
    }
  }",
  "variables": {
      "id": "811ab3e2-6f24-493d-bcaa-a95395bc16a2",
      "customer": {
          "id": "2",
          "email": "john@test.com",
          "name": "John Smith"
        },
      "amount": {
            "amount": 222,
            "currency": "EUR"
        },
      "paymentIntent": {
          "status": "NOT_STARTED",
          "outcome": "DECLINED",
          "paymentMethod": "CARD 2",
          "sca": true
      },
      "shipping": {
          "status": "IN_PROGRESS"
      },
      "delivery": {
          "status": "COMPLETE"
      }
  }
}'
https://api.whenthen.com/api/graphql

Response

Complete Intent

Mutation
Client TokenPrivate KeyPublic Key

Use completeIntent to complete any of the intent details or status..

Request

ValueType
  • idID ﹡
    The intent id for future use and updates
  • paymentReferenceID
    The payment reference from the payment processor
CURL
curl 
-X POST 
-H "Content-Type: application/json" 
-H "Authorization: Bearer xxxxxxx" 
-d '{
	"query": "mutation completeIntent($id: ID!, $paymentReference: ID) {
  completeIntent(id: $id, paymentReference: $paymentReference){
        id
        trackingId
        paymentFlowId
        status
        date
        currency
        amount {
            formattedAmount
        }
        location {
            country
        }
        customer {
            id
            isGuest
        }

        timeline {
            intentStarted {
                status
                date
            }
            shipping {
                status
                date
            }
            delivery {
                status
                date
            }
            billing {
                status
                date
            }
            completeCheckout {
                status
                date
            }
        }
    }
	}",
	"variables": {
		"id": "811ab3e2-6f24-493d-bcaa-a95395bc16a2",
	    "paymentReference": "f6sepsen"
	}
}' 
https://api.whenthen.com/api/graphql

Response

Amount

Value
  • rawAmount

    amount in minor units.

  • currency

    ISO 4217 Code e.g. EUR

  • formattedAmount

    formatted amount

Checkout Status

Type
  • INTENT

    Currently in Intent status. The beginning of the life cycle.

    Status when startIntent is called.

  • ACTIVE

    The payment intent is active. Status once updateIntent is called

  • INACTIVE

    The payment intent is no longer active. Occurs after 5 mins of inactivity

  • COMPLETE

    The payment intent is completed. The customer has completed their purchase

Form Step Status

Type
  • NOT_STARTED
    Not started yet
  • IN_PROGRESS
    Currently in progress
  • COMPLETE
    Completed