Documentation
HomeDocumentationAPI Reference
Start typing to search…

checkout()

checkout() launches the Paze user interface in a popup window. The flow is controlled by the actionCode and intent fields.

When actionCode is START_FLOW:

  • If canCheckout() has not returned true, the consumer will be prompted via the Paze UI to provide a lookup key (emailAddress or mobileNumber).

  • If canCheckout() has returned true, the SDK uses the lookup key provided in canCheckout() unless a new lookup key is passed into checkout().

  • If a lookup key is provided directly to checkout(), the SDK performs a lookup with that value before launching the UI.

  • The SDK hashes the consumer's lookup key before transmitting it.

  • If the consumer is not found or is ineligible, the SDK:

    • Displays an inline error in the Paze UI, or
    • Returns an error so the merchant can route the customer to an alternative payment method

  • If the consumer is found and is eligible to check out, Paze proceeds with:

    • Customer authentication
    • Card selection
    • Shipping address selection or entry (if configured in the checkout() request)

If actionCode is CHANGE_CARD or CHANGE_SHIPPING_ADDRESS, the SDK renders only the corresponding screens.

A new checkout session (START_FLOW) is required when:

  • Excessive time has elapsed. The session times out (warning after 6 minutes of inactivity, timeout after
  • The consumer indicates that they would like to use a different email address.

The response of checkout() will contain masked card, consumer, and billing and shipping address, per the corresponding checkout request.

Request Parameters

emailAddress string conditional

emailAddress as customer identity must conform to the RFC 5322 address-spec syntax (lowercase).

Max: 128 characters
Condition: Required if a mobileNumber is not provided. mobileNumber takes precedence if both are provided.

mobileNumber string conditional

mobileNumber as customer identity is only supported as US based phone numbers. Formatting can include hyphens and country codes such as:

  • 5125555555
  • 512-555-5555
  • 15125555555
  • 1-512-555-5555

mobileNumber value MUST conform to the E.164 format without the plus sign.

Max: 15 characters
Condition: mobileNumber is required if emailAddress is not provided. mobileNumber takes precedence if both are provided.

sessionId string optional
The session reference identifier generated by the merchant. If present here, it is returned in the checkout() response. This is recommended to be identical across the checkout() request and the complete() request.

Max: 255 characters
Note: This field is required if the merchant is enrolled in the Paze Fraud Liability Shift Program to maintain eligibility.

actionCode enum optional

Controls which portion of the Paze flow is launched on checkout() call.

Valid values are:

  • START_FLOW (default)
  • CHANGE_CARD
  • CHANGE_SHIPPING_ADDRESS

intent enum optional
Valid values are:

  • REVIEW_AND_PAY (default)
  • EXPRESS_CHECKOUT
  • ADD_CARD

Consider the primary intent of the call when setting this value. For example, if the consumer returns to a merchant order review page, use REVIEW_AND_PAY.
It is the merchant’s responsibility to ensure that the flow is correct for their consumers and aligns with the intended use of each intent value.

transactionValue Object(TransactionValue) conditional
Currency code, amount of transaction, discount, tax, and shipping inputs.

Note: No cart value will be displayed in the Paze UI if this is excluded from the request. It is not needed if the consumer is selecting a card to keep on file with the merchant. Merchants are recommended, but not explicitly required, to provide discount, tax, and shipping inputs.

Condition: Required if intent is EXPRESS_CHECKOUT. Invalid when intent is ADD_CARD.

confirmLaunch boolean optional
Determines whether a consumer needs to confirm their intention to launch Paze.

Note: Set to true for automatic initiation flows, such as when the merchant triggers Paze without a customer click. This displays an intermediate screen with context about Paze before launch. Set to false if the consumer has already clicked a Paze button on the merchant site—in this case, the intermediate screen is skipped and Paze launches immediately.

Default Value: false.

shippingPreference enum conditional
Determines whether the merchant wants to collect the shipping address.
Valid values:

  • ALL (default)
  • NONE

Note: NONE suppresses address selection and management screens.
Condition: shippingPreference must be set to NONE if intent is ADD_CARD.

billingPreference enum optional
The verbosity of billing address required by the merchant.
Valid values:

  • ALL (default)
  • ZIP_COUNTRY (scoped for future release)
  • NONE

cobrand List([Cobrand](Cobrand ) optional
Details for cobranded cards offered by the merchant. This field is used to highlight a consumer’s existing cobrand cards within the Paze UX, if available. If the merchant has multiple cobranded cards, the list should be ordered from highest to lowest display priority.

acceptedShippingCountries List(String) optional
Array of country codes in ISO 3166-1 alpha-2 format as shipping restrictions. An empty list or the absence of this data element means that all countries are accepted. Only US is currently supported.

acceptedPaymentCardNetworks List(String) conditional
An array of payment card networks. Valid values are:

  • VISA
  • MASTERCARD
  • DISCOVER

An empty list or the absence of this data element means that all card networks are accepted.

Condition: This field should be included if the merchant does not support a given card network so that Paze displays accepted cards.

Response Attributes

result enum required
Valid values are:

  • COMPLETE: Checkout completed successfully in Paze.
  • INCOMPLETE: Consumer exited Paze, failed authentication, did not complete checkout(), or their session expired.

checkoutResponse Object(CheckoutResponse) conditional
This is the JWS of the checkout response.

Condition: Applicable when checkout() result is COMPLETE.

Promise - Resolve and Reject

resolve()
This is the JS Promise (fulfilled) call when the request is successfully processed by the Paze SDK. A JSON object with attributes will be passed in the response as shown above.

reject()
This is the JS Promise call when there is an error. The object passed in is an error object as defined in the Errors section.

Business Errors

ACCT_INACCESSIBLE
The wallet exists but is not currently accessible. For example, the wallet is suspended.

CLIENT_DATA_INVALID

  • actionCode CHANGE_CARD will be conditionally invalid if the consumer’s wallet only has one card.
  • actionCode CHANGE_SHIPPING_ADDRESS will be conditionally invalid if shippingPreference is NONE.
  • shippingPreference ALL will be conditionally invalid if intent is ADD_CARD.
  • transactionValue being provided will be conditionally invalid if intent is ADD_CARD.
  • transactionValue not being provided will be conditionally invalid if intent is EXPRESS_CHECKOUT.

Code Example

await checkout({
  emailAddress: "[email protected]", // string (conditional)
  // mobileNumber: "15125555555",                    // string (conditional)
  sessionId: "YSr6zUH6gsAs3riQMhTL", // string (optional)
  actionCode: "START_FLOW", // enum (optional)
  intent: "REVIEW_AND_PAY", // enum (optional)
  transactionValue: {
    transactionCurrencyCode: "USD", // string (required if transactionValue provided)
    transactionAmount: "73.29" // string (required)
  },
  shippingPreference: "ALL", // enum (optional)
  billingPreference: "ZIP_COUNTRY", // enum (optional)
  cobrand: [
    {
      cobrandName: "Orchid Bonanza Optimum", // string (required)
      benefitsOffered: true // boolean (optional)
    }
  ],
  acceptedShippingCountries: ["US"], // string[] (optional)
  acceptedPaymentCardNetworks: ["VISA", "MASTERCARD", "DISCOVER"], // string[] (optional)
  enhancedTransactionData: {
    ecomData: {
      cartContainsGiftCard: true, // boolean (optional)
      orderForPickup: true, // boolean (optional)
      orderQuantity: "3", // string (optional)
      orderHighestCost: "54.17", // string (optional)
      finalShippingAddress: {
        name: "Another Customer", // string (optional)
        line1: "1234 Main St.", // string (required)
        line2: "Apt. 3A", // string (optional)
        city: "Evansville", // string (required)
        state: "Indiana", // string (required)
        zip: "47705", // string (required)
        countryCode: "US" // string (required)
      }
    }
  }
});

Response

{
  result: "COMPLETE",
  checkoutResponse: "eyJhdWQiOiJmaWxlOlwvXC8iLCJraWQiOi……..sAxxsSgJtrteqa3QadRQ" // JWS (present only when COMPLETE)
}

Decoded checkoutResponse

After receiving the checkoutResponse JWS, decode it with a Base64 decoder to extract the JSON payload. This payload contains useful, non-sensitive customer data such as firstName, lastName, emailAddress, and shippingAddress.

{
  "sessionId": "YSr6zUH6gsAs3riQMhTL", // string (echoed if provided)
  "consumer": {
    "firstName": "Another", // string (optional)
    "lastName": "Customer", // string (optional)
    "fullName": "Another Customer", // string (required)
    "emailAddress": "[email protected]", // string (required; RFC 5322)
    "mobileNumber": null // object (optional; null because not provided)
  },
  "maskedCard": {
    "digitalCardId": "uuid-1234-5678-9999", // string (required)
    "panLastFour": "4242", // string (required)
    "paymentAccountReference": "PAR1234567890", // string (required)
    "panExpirationMonth": "12", // string (conditional)
    "panExpirationYear": "2028", // string (conditional)
    "paymentCardDescriptor": "Orchid Bonanza Optimum", // string (required)
    "paymentCardType": "CREDIT", // enum (required)
    "paymentCardBrand": "VISA", // enum (required)
    "paymentCardNetwork": "VISA", // enum (required)
    "digitalCardData": {
      "artUri": "https://cdn.paze.com/cardart/visa.png", // string (required)
      "artHeight": 48, // number (required)
      "artWidth": 76 // number (required)
    },
    "billingAddress": {
      "line1": "1234 Main St.", // string (required)
      "line2": "Apt. 3A", // string (optional)
      "city": "Evansville", // string (required)
      "state": "Indiana", // string (required)
      "zip": "47705", // string (required)
      "countryCode": "US" // string (required)
    }
  },
  "shippingAddress": {
    "name": "Another Customer", // string (required)
    "line1": "1234 Main St.", // string (required)
    "line2": "Apt. 3A", // string (optional)
    "city": "Evansville", // string (required)
    "state": "Indiana", // string (required)
    "zip": "47705", // string (required)
    "countryCode": "US", // string (required; ISO 3166-1 alpha-2)
    "deliveryContactDetails": {
      "contactPhoneNumber": null, // object (optional; null because not provided)
      "contactFullName": "Another Customer" // string (optional)
    }
  }
}

Updated about 1 month ago