---
title: "Create Session"
method: POST
path: "/v1/checkout/sessions/create"
tags: ["Checkout Session"]
---

# Create Session

`POST /v1/checkout/sessions/create`

Enables merchant to create the session/context needed for a native mobile checkout experience.
This will return a URL that can be launched in a webView by the merchant for a Paze checkout.

## Request body

- CheckoutSessionCreateRequest — Checkout Session Create Request
  - `clientContext` string — Customer-defined transaction identifier, reflected in response. Referred to as “sessionId” in web integration. Session reference identifier generated by the Merchant. If present here, it will be returned in the Checkout response. This is recommended to be identical across the Checkout request and the /wallets/sessions/checkout/complete request.
  - `data` object — Payload containing all fields that can be passed to this API.
    - `client` ClientObject, required — Client refers to the Merchant that is integrating with PazeSM
      - `id` string, required — Client identifier. This is generated by PazeSM and shared with client during onboarding.
      - `name` string — Display name associated with the Client to be used for presentation purposes within the user experience.
      - `profileId` string — Represents a Client's profile to be used during checkout.<br>The client's default profile will be used with profileId is not provided during this call.
    - `sessionId` string, required — Session reference identifier generated by the Merchant. This must be reused across all the Paze APIs involved during a checkout session so all the system activity can be correctly correlated for that single checkout session.
    - `phoneNumber` string — Optional. Required if emailAddress is not provided.
    - `emailAddress` string — Optional. Required if phoneNumber is not provided.
    - `callbackURLScheme` string, required — This is Merchant app's ID, for iOS it's bundle identifier and Android it's application Id.<br>The callback URL scheme to use to return to the Merchant's mobile app. <br>This is used by the Paze UX running in the WebView to return the consumer back to the Merchant's native mobile app after the consumer exits the Paze UX, either after finishing all the steps or canceling out before the last step.<br>On redirect to this schema, Paze will append a query string parameter of "status" with one of the following values - <br>* success the consumer successfully completed the Paze checkout steps, and the Merchant can utilize the other Paze APIs to get data to display or to get the secure payload<br>* cancelled the consumer cancelled out of the Paze UX before the last step<br>* failed there was some error encountered during the Paze UX flow
    - `intent` 'REVIEW_AND_PAY' | 'EXPRESS_CHECKOUT' | 'ADD_CARD' — Consider the primary intent of the API call when setting this value. For example, a consumer may simultaneously check out and ask to retain the same card on file. In that case, intent should be set to REVIEW_AND_PAY.
    - `transactionType` 'PURCHASE' | 'CARD_ON_FILE' | 'BOTH' — Required if intent is ADD_CARD the allowed value is CARD_ON_FILE. When a Discover card is selected in the checkout flow and returned to the merchant in the checkout response, then the Merchant must provide "PURCHASE" or "BOTH" only as Discover does not support "CARD_ON_FILE". When "BOTH" is provided, only a dynamicDataType equal to PURCHASE will be returned.
    - `transactionValue` TransactionValue — Recommended for consumer reference in the case of an immediate intent to pay. No cart value will be displayed in the Paze UI if this is excluded from the request. Not needed if the consumer is selecting a card to keep on file with Merchant. <br>NOTE - Required if intent is EXPRESS_CHECKOUT. Request will be invalid when transactionValue is provided if intent is ADD_CARD.
      - `transactionCurrency` 'AED' | 'AFN' | 'ALL' | 'AMD' | 'ANG' | 'AOA' | 'ARS' | 'AUD' | 'AWG' | 'AZN' | 'BAM' | 'BBD' | 'BDT' | 'BGN' | 'BHD' | 'BIF' | 'BMD' | 'BND' | 'BOB' | 'BOV' | 'BRL' | 'BSD' | 'BTN' | 'BWP' | 'BYN' | 'BZD' | 'CAD' | 'CDF' | 'CHE' | 'CHF' | 'CHW' | 'CLF' | 'CLP' | 'CNY' | 'COP' | 'COU' | 'CRC' | 'CUP' | 'CVE' | 'CZK' | 'DJF' | 'DKK' | 'DOP' | 'DZD' | 'EGP' | 'ERN' | 'ETB' | 'EUR' | 'FJD' | 'FKP' | 'GBP' | 'GEL' | 'GHS' | 'GIP' | 'GMD' | 'GNF' | 'GTQ' | 'GYD' | 'HKD' | 'HNL' | 'HTG' | 'HUF' | 'IDR' | 'ILS' | 'INR' | 'IQD' | 'IRR' | 'ISK' | 'JMD' | 'JOD' | 'JPY' | 'KES' | 'KGS' | 'KHR' | 'KMF' | 'KPW' | 'KRW' | 'KWD' | 'KYD' | 'KZT' | 'LAK' | 'LBP' | 'LKR' | 'LRD' | 'LSL' | 'LYD' | 'MAD' | 'MDL' | 'MGA' | 'MKD' | 'MMK' | 'MNT' | 'MOP' | 'MRU' | 'MUR' | 'MVR' | 'MWK' | 'MXN' | 'MXV' | 'MYR' | 'MZN' | 'NAD' | 'NGN' | 'NIO' | 'NOK' | 'NPR' | 'NZD' | 'OMR' | 'PAB' | 'PEN' | 'PGK' | 'PHP' | 'PKR' | 'PLN' | 'PYG' | 'QAR' | 'RON' | 'RSD' | 'RUB' | 'RWF' | 'SAR' | 'SBD' | 'SCR' | 'SDG' | 'SEK' | 'SGD' | 'SHP' | 'SLE' | 'SOS' | 'SRD' | 'SSP' | 'STN' | 'SVC' | 'SYP' | 'SZL' | 'THB' | 'TJS' | 'TMT' | 'TND' | 'TOP' | 'TRY' | 'TTD' | 'TWD' | 'TZS' | 'UAH' | 'UGX' | 'USD' | 'USN' | 'UYI' | 'UYU' | 'UYW' | 'UZS' | 'VED' | 'VES' | 'VND' | 'VUV' | 'WST' | 'XAF' | 'XAG' | 'XAU' | 'XBA' | 'XBB' | 'XBC' | 'XBD' | 'XCD' | 'XDR' | 'XOF' | 'XPD' | 'XPF' | 'XPT' | 'XSU' | 'XTS' | 'XUA' | 'XXX' | 'YER' | 'ZAR' | 'ZMW' | 'ZWG', required — ISO 4217 currency code.
      - `transactionAmount` string, required — The amount of the transaction. Must include dollar and cents value in proper format. Digits before and after the decimal point "." are required, including trailing zeros.
      - `subtotal` string
      - `taxAmount` string
      - `shippingAmount` string
      - `discountAmount` string
    - `alwaysEnableCheckout` boolean — Set to true to indicate that the Merchant wants to enable Paze checkout even if the provided email address or phone number does not match a Paze wallet.<br> This will result in the checkoutUrl being provided in the response. This way the user will not have to enter their email address or phone number if they matched, or will be prompted to enter them in case they use different values, such as say a shopping email address that does not match their banking email address.
    - `shippingPreference` 'ALL' | 'NONE' — Whether Merchant wants to have shipping address collected. <br> NOTE - NONE suppresses address selection/management screens. <br> shippingPreference must be set to NONE if intent is ADD_CARD.
    - `billingPreference` 'ALL' | 'NONE' — Verbosity of billing address required by the Merchant.
    - `cobrand` CobrandObject[] — Details for cobranded cards offered by the Merchant.<br>This field will be used to highlight consumers' existing cobrand cards within the PazeSM UX, if available. If the Merchant has multiple cobranded cards, the list should be ordered from highest to lowest display priority.
      - `name` string, required — Product name of the cobrand card. Must match exactly with the card name received from the network.
      - `benefitsOffered` boolean
    - `useCase` 'RMG'
    - `acceptedShippingCountries` CountryCode[] — Optional ISO 3166-1 alpha-2 codes
    - `acceptedPaymentCardNetworks` string[] — An empty list or the absence of this data element means that all card networks are accepted. This field may be updated with additional enums as PazeSM onboards other card networks.

## Response `200`

Successfully located a wallet for the provided identity key

- CheckoutSessionCreateResponse — Beginning of every response body
  - `clientContext` string
  - `ewSID` string, required — Globally unique identifier generated by Early Warning. Returned in the response message in response to the initial request. This identifier ties all information about the session together and should be easily accessible by customer staff submitting support requests to Early Warning. Character set a-f, 0-9, -.
  - `timestampISO8601` string, date-time, required — Timestamp of message in ISO8601 extended combined format. Format: {YYYY}-{MM|-{DD}T{HH}:{MM}:{SS}Z Example: 2015-12-31T17:18Z Time stamp when response is sent by the Service Operator Services.
  - `data` object — Payload containing all fields that can be passed to this API.
    - `canCheckout` boolean, required — If no email address and phone number was provided in the request, or an email address and/or phone number was provided in the request and a Paze wallet is associated with the provided values and has at least one card, this will be set to true. If the email address or phone number did not match any wallet, or if only one wallet was found and had zero card or was suspended, etc., this will be set to false.
    - `checkoutUrl` string, required — Session URL for launching the UI/UX from the native mobile application in a WebView within the App.Available if the canCheckout is true or if "alwaysEnableCheckout" was set to true in the request.

## Other responses

- `400` — Bad request. Incorrectly formatted request, may be missing id parameter
- `401` — Unauthorized. Access token missing or no longer valid.
- `422` — The error occurred at the TSP while processing the provisioning request. The error structure will provide the details as provided by the TSP.
- `500` — Internal Server Error

---

[API](https://skmtc.dev/paze/apis/paze-checkout-api.md) · [All operations](https://skmtc.dev/paze/apis/paze-checkout-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/paze/paze-checkout-api/revisions/81670e227b06/schema)