Documentation
HomeDocumentationAPI Reference
Start typing to search…

Objects


Address

Used in checkout() and complete() (for shipping/billing/final shipping addresses).

The following structure details the Address object.

name string optional
Name of the organization/entity at the address.

Min: 0 characters | Max: 100 characters

line1 string conditional
Line 1 of the address.

Min: 0 characters | Max: 75 characters
Condition: Returned if billingPreference is ALL.

line2 string optional
Line 2 of the address.

Min: 0 characters | Max: 75 characters

line3 string optional
Line 3 of the address.

Min: 0 characters | Max: 75 characters

city string conditional
Name of the city.

Min: 0 characters | Max: 50 characters
Condition: Returned if billingPreference is ALL.

state string conditional
Name of the state.

Min: 0 characters | Max: 30 characters
Condition: Returned if billingPreference is ALL.

zip string required
Postal code for this address.

Min: 0 characters | Max: 10 characters

countryCode string required
The country code for this address. The underlying countryCode value MUST conform to the ISO 3166-1 alpha-2 country code.

Min: 2 characters | Max: 2 characters

Code Example

// Address object used in Checkout / Complete responses
const address = {
  name: "Another Customer", // string (optional)
  line1: "1234 Main St.", // string (conditional)
  line2: "Apt. 3A", // string (optional)
  line3: "", // string (optional)
  city: "Evansville", // string (conditional)
  state: "Indiana", // string (conditional)
  zip: "47705", // string (required)
  countryCode: "US", // string (required) — ISO 3166-1 alpha-2
};

Checkout Response

Used in checkout().

The following structure details the Checkout Response object.

sessionId string conditional
Session reference identifier generated by the Merchant. Returned when sessionId is present in the checkout() request.

Min: 0 characters | Max: 255 characters

consumer object(Consumer) required
Details associated with the authenticated consumer.

maskedCard object(MaskedCard) required
Masked card details of the selected card.

shippingAddress object(ShippingAddress) conditional
Selected shipping address. Returned only when shippingPreference is not NONE.

Code Example

// CheckoutResponse object (logical shape of the JWS payload)
const checkoutResponse = {
  sessionId: "YSr6zUH6gsAs3riQMhTL", // string (conditional)
  consumer: {
    fullName: "Another Customer", // string (required)
    firstName: "Another", // string (optional)
    lastName: "Customer", // string (optional)
    emailAddress: "[email protected]", // string (optional)
    mobileNumber: {
      countryCode: "1", // string (required)
      phoneNumber: "5125555555", // string (required)
    },
    countryCode: "US", // string (optional)
    languageCode: "en_US", // string (optional)
  },
  maskedCard: maskedCard, // MaskedCard (required)
  shippingAddress: {
    name: "Another Customer", // string (required)
    line1: "1234 Main St.", // string (required)
    line2: "Apt. 3A", // string (optional)
    line3: "", // string (optional)
    city: "Evansville", // string (required)
    state: "Indiana", // string (required)
    zip: "47705", // string (required)
    countryCode: "US", // string (required)
    deliveryContactDetails: {
      contactFullName: "Another Customer", // string (optional)
      contactPhoneNumber: {
        countryCode: "1", // string (required)
        phoneNumber: "5125555555", // string (required)
      },
    },
  }, // ShippingAddress (conditional)
};

Client

Used in initialize().

The following structure details the client. For the purposes of this document, “client” refers to the Merchant that is integrating with Paze.

id string required
Client identifier. This is generated by Paze and shared with client during onboarding.

Min: 0 characters | Max: 50 characters

name string optional
Alphanumeric display name associated with the Client to be used for presentation purposes within the user experience.

Min: 0 characters | Max: 50 characters

profileId string optional
Represents a client’s profile to be used during checkout.

Note: If profileId was used during onboarding, the same value should be used during SDK initialization. The client’s default profile will be used when profileId is not provided during Initialize.

Min: 0 characters | Max: 50 characters

externalSubMerchantId string optional
Merchant identifier within the merchant’s system.

Min: 0 characters | Max: 50 characters

merchantCategoryCode string optional
MCC for the merchant.

Format: String; exactly 4 chars (between 0000 and 9999 both inclusive).

brandName string optional
Alphanumeric brand name in case a single merchant has multiple brands or stores that it wants to uniquely identify with.

Min: 0 characters | Max: 50 characters

statementDescriptor string optional
This field captures how the transaction would appear on the buyer’s statement.

Min: 0 characters | Max: 25 characters

url string optional
The URL of the page from which the SDK is initialized and buyer is taking the action to checkout with Paze.

Min: 0 characters | Max: 2083 characters

Code Example

// Client object used in initialize()
const client = {
  id: "mOYSSfG9VQonnTRZ8Zct5h2GnAeNj38lGHQy0xIeCWsrmE1LY", // string (required)
  name: "Orchid Bonanza", // string (optional)
  profileId: "orchidBonanzaMain", // string (optional)
  externalSubMerchantId: "019718e7-dbc1-74b5-9019-032260d9f074", // string (optional)
  merchantCategoryCode: "0303", // string (optional)
  brandName: "Orchid West", // string (optional)
  statementDescriptor: "PAZE ORCHID 0303 $13.00", // string (optional)
  url: "https://www.example.com/myapp", // string (optional)
};

Cobrand

Used in checkout().

The following structure details the Cobrand object.

cobrandName string required
The product name of the cobrand card. It must match exactly with the card name received from the network.

Min: 0 characters | Max: 25 characters

benefitsOffered boolean optional

Default value is false.

Note: This value will not drive variation in the Paze UX until a future release.

Code Example

// Cobrand object used in Checkout
const cobrand = {
  cobrandName: "Orchid Bonanza Optimum", // string (required)
  benefitsOffered: true, // boolean (optional) — default false
};

Complete Response

Used in complete().

The following structure details the Complete Response object.

payloadId string required
Unique identifier generated by Paze to track and link wallet transaction-specific messages.

Min: 0 characters | Max: 50 characters

sessionId string conditional
Session reference identifier generated by the Merchant. Returned if sessionId was provided by the Merchant.

Min: 0 characters | Max: 255 characters

securedPayload Object(SecuredPayload) conditional
Information necessary to process payment. Returned when transactionOptions.payloadTypeIndicator is PAYMENT.

Code Example

// CompleteResponse object (logical shape of the JWS payload)
const completeResponse = {
  payloadId: "paze-payload-123456", // string (required)
  sessionId: "YSr6zUH6gsAs3riQMhTL", // string (conditional)
  securedPayload: "eyJhbGciOiJ...JWE-of-JWS-of-Payload...", // JWE<JWS<Payload>> (conditional)
};

Consumer Data

Used in checkout() and complete().

The following structure details the Consumer object:

firstName string optional
Consumer first name.

Min: 0 characters | Max: 100 characters

lastName string optional
Consumer last name.

Min: 0 characters | Max: 100 characters

fullName string required
Consumer full name.

Min: 0 characters | Max: 100 characters

emailAddress string optional
Consumer email address. MUST conform to RFC 5322, lowercase.

Min: 0 characters | Max: 128 characters

mobileNumber object(PhoneNumber) optional
Consumer mobile phone number.

countryCode string optional
Consumer-provided country code (ISO 3166-1 alpha-2), e.g. “US”.

Min: 0 characters | Max: 2 characters

languageCode string optional
Consumer’s preferred language based on ISO 639-1 and alpha-2 country code separated with _, e.g. en_US.

Min: 0 characters | Max: 10 characters

Code Example

// Consumer object used in Checkout / Complete
const consumer = {
  firstName: "Another", // string (optional)
  lastName: "Customer", // string (optional)
  fullName: "Another Customer", // string (required)
  emailAddress: "[email protected]", // string (optional)
  mobileNumber: {
    countryCode: "1", // string (required)
    phoneNumber: "5125555555", // string (required)
  }, // PhoneNumber (optional)
  countryCode: "US", // string (optional)
  languageCode: "en_US", // string (optional)
};

Delivery Contact Details

Used in checkout().

The following structure details the DeliveryContactDetails object.

contactFullName string optional
Consumer-provided name of the contact person.

Min: 0 characters | Max: 100 characters

contactPhoneNumber object(PhoneNumber) optional
Consumer-provided phone number for the contact person.

Code Example

// DeliveryContactDetails used inside ShippingAddress
const deliveryContactDetails = {
  contactFullName: "Another Customer", // string (optional)
  contactPhoneNumber: {
    countryCode: "1", // string (required)
    phoneNumber: "5125555555", // string (required)
  }, // PhoneNumber (optional)
};

Digital Card Data

Used in checkout().

Digital Card Data contains digital card art that is usable for presentation.

The following structure details the Digital Card Data object.

artUrl URL required
HTTPS (full) URL for the card art.

artHeight number required
Height of the card art image in pixels.

artWidth number required
Width of the card art image in pixels.

Code Example

// DigitalCardData used inside MaskedCard
const digitalCardData = {
  artUrl: "https://cdn.paze.example/cards/orchid-bonanza.png", // URL (required)
  artHeight: 256, // number (required) — px
  artWidth: 414, // number (required) — px
};

Dynamic Data

Used in complete().

The following structure details the Dynamic Data object.

dynamicDataValue string required
The dynamic data value (structure dependent on Card Network).

Min: 0 characters | Max: 20 characters

dynamicDataType string required
Valid values:

  • PURCHASE
  • CARD_ON_FILE

Note: CARD_ON_FILE is not supported for Discover.

dynamicDataExpiration string optional
Indicates validity period for the dynamic data. Value conforms to UTC time in Unix epoch format.

Code Example

// DynamicData object used in Payload
const dynamicData = {
  dynamicDataValue: "ABCD1234EFGH5678", // string (required)
  dynamicDataType: "PURCHASE", // enum (required) — PURCHASE | CARD_ON_FILE
  dynamicDataExpiration: "1751328000", // string (optional) — Unix epoch seconds
};

Ecom Data

Used in complete().

The following structure represents optional electronic commerce-related parameters within the Enhanced Transaction Data object.

cartContainsGiftCard boolean optional
Whether the current transaction includes a gift card purchase.

orderForPickup boolean optional
Whether a consumer order will be picked up rather than shipped.

orderQuantity string optional
Number of items ordered.

Min: 0 characters | Max: 10 characters

orderHighestCost string optional
Dollar value of most expensive item ordered.

Min: 0 characters | Max: 10 characters

finalShippingAddress Object(Address) optional
Destination of items ordered. Recommended for use if the Merchant does not intend to use Paze for shipping address collection. See Shipping Address Data Elements for more information.

Code Example

// EcomData used inside EnhancedTransactionData
const 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)
  },
};

Enhanced Transaction Data

Used in complete().

ecomData Object (EcomData) optional
Details pertaining to electronic commerce purchases. See EcomData elements for more information.

travelData Object (TravelData) optional
Details pertaining to travel bookings. See TravelData data elements for more information.

Code Example

// EnhancedTransactionData used in Complete
const 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)
    },
  },
  travelData: undefined, // TravelData (optional)
};

Masked Card Data

Used in checkout().

The following structure details the non-sensitive masked token details.

digitalCardId string required
Unique Identifier of the card (UUID).

Min: 0 characters | Max: 36 characters

panLastFour string required
Last 4 digits of the card.

Min: 4 characters | Max: 4 characters

paymentAccountReference string required
Payment Account Reference (PAR) - a value assigned to the underlying cardholder account that uniquely identifies the underlying account.

panExpirationMonth string conditional
2-digit PAN expiration month.

Condition: required if card supports expiry.
Min: 2 characters | Max: 2 characters

panExpirationYear string conditional
4-digit PAN expiration year.

Condition: required if card supports expiry.
Min: 4 characters | Max: 4 characters

paymentCardDescriptor string required
A free-form string (maximum 32 characters) used for card/program recognition.

Example: “Travel Rewards”.
Min: 0 characters | Max: 32 characters

digitalCardData Object(DigitalCardData) required
Digital Card Art. See Digital Card Data Elements for more information.

billingAddress Object(Address) conditional
Billing address for display purposes. See Address Data Elements for more information.

Condition: billingPreference is not NONE.

paymentCardType enum required
Valid values:

  • CREDIT
  • DEBIT

paymentCardBrand enum required
Valid values:

  • VISA
  • MASTERCARD
  • DISCOVER

paymentCardNetwork enum required
Valid values:

  • VISA
  • MASTERCARD
  • DISCOVER

Code Example

// MaskedCard data returned in Checkout
const maskedCard = {
  digitalCardId: "6d9fd6da-1234-4c8d-9b2c-abcdef123456", // string (required) — UUID
  panLastFour: "4242", // string (required)
  paymentAccountReference: "b8a4e4f2c3d9a7b6c5d4e3f2a1b0c9d", // string (required)
  panExpirationMonth: "08", // string (conditional)
  panExpirationYear: "2030", // string (conditional)
  paymentCardDescriptor: "Orchid Bonanza Rewards", // string (required)
  paymentCardType: "CREDIT", // enum (required) — CREDIT | DEBIT
  paymentCardBrand: "VISA", // enum (required) — VISA | MASTERCARD | DISCOVER
  paymentCardNetwork: "VISA", // enum (required)
  digitalCardData: {
    artUrl: "https://cdn.paze.example/cards/orchid-bonanza.png", // URL (required)
    artHeight: 256, // number (required)
    artWidth: 414, // number (required)
  },
  billingAddress: {
    name: "Another Customer", // string (optional)
    line1: "1234 Main St.", // string (conditional)
    line2: "Apt. 3A", // string (optional)
    city: "Evansville", // string (conditional)
    state: "Indiana", // string (conditional)
    zip: "47705", // string (required)
    countryCode: "US", // string (required)
  }, // Address (conditional)
};

Phone Number

Used in canCheckout() and checkout().

The following structure details the Phone Number object.

countryCode string required
Phone number country code (ISD). Example: “1” for US. MUST conform to E.164 without the plus sign.

Min: 1 character | Max: 1 character

phoneNumber string required
Phone number. MUST conform to E.164 without the plus sign.

Min: 0 characters | Max: 10 characters

Code Example

// PhoneNumber object used in CanCheckout / Checkout / Shipping
const phoneNumber = {
  countryCode: "1", // string (required) — E.164 without '+'
  phoneNumber: "5125555555", // string (required) — E.164 without '+'
};

Secured Payload

Used in complete().

This section details the structure of the encrypted Payload object that is a part of the JWE claims. The Paze JWEs from Complete must have a JWS that contains a single composite JSON object payload as a claim whose JSON structure is defined below.

clientId string required
Client identifier. Generated by Paze.

Min: 0 characters | Max: 50 characters

profileId string required
Client profile used during checkout().

Min: 0 characters | Max: 50 characters

token object(Token) required
Token payload that contains token number and associated attributes.

paymentCardNetwork enum required

Valid values:

  • VISA
  • MASTERCARD
  • DISCOVER

dynamicData list(DynamicData) required
Dynamic data for consumer-initiated payment or card-on-file.

billingAddress object(Address) conditional
Billing address of the card selected, at the verbosity indicated by transactionOptions.billingPreference.

Condition: Provided when transactionOptions.billingPreference is not NONE.

consumer object(Consumer) required
Information about the consumer who completed the checkout.

eci string conditional
Electronic Commerce Indicator.

Min: 0 characters | Max: 2 characters
Condition: Provided when the Merchant submitted a transaction for PURCHASE or BOTH.

Code Example

// Payload inside the secured JWE from completeResponse.securedPayload
const payload = {
  clientId: "mOYSSfG9VQonnTRZ8Zct5h2GnAeNj38lGHQy0xIeCWsrmE1LY", // string (required)
  profileId: "orchidBonanzaMain", // string (required)
  token, // Token (required)
  paymentCardNetwork: "VISA", // enum (required)
  dynamicData: [
    {
      dynamicDataValue: "ABCD1234EFGH5678", // string (required)
      dynamicDataType: "PURCHASE", // enum (required) — PURCHASE | CARD_ON_FILE
      dynamicDataExpiration: "1751328000", // string (optional) — Unix epoch seconds
    },
  ],
  billingAddress: {
    name: "Another Customer", // string (optional)
    line1: "1234 Main St.", // string (conditional)
    line2: "Apt. 3A", // string (optional)
    city: "Evansville", // string (conditional)
    state: "Indiana", // string (conditional)
    zip: "47705", // string (required)
    countryCode: "US", // string (required)
  }, // Address (conditional)
  consumer: {
    fullName: "Another Customer", // string (required)
    emailAddress: "[email protected]", // string (optional)
    mobileNumber: {
      countryCode: "1", // string (required)
      phoneNumber: "5125555555", // string (required)
    },
    countryCode: "US", // string (optional)
    languageCode: "en_US", // string (optional)
  }, // Consumer (required)
  eci: "05", // string (conditional)
};

Shipping Address

Used in checkout().

The following structure details the Shipping Address object.

name string required
Name of the organization/entity at the address.

Min: 0 characters | Max: 100 characters

line1 string required
Address first line.

Min: 0 characters | Max: 75 characters

line2 string optional
Address second line.

Min: 0 characters | Max: 75 characters

line3 string optional
Address third line.

Min: 0 characters | Max: 75 characters

city string required
Name of the city.

Min: 0 characters | Max: 50 characters

state string required
State name.

Min: 0 characters | Max: 30 characters

zip string required
Address zip code.

Min: 0 characters | Max: 10 characters

countryCode string required
Address country code (ISO 3166-1 alpha-2).

Min: 2 characters | Max: 2 characters

deliveryContactDetails Object(DeliveryContactDetails) optional
Delivery contact details for a shipping address.

Code Example

// ShippingAddress object used in Checkout responses
const shippingAddress = {
  name: "Another Customer", // string (required)
  line1: "1234 Main St.", // string (required)
  line2: "Apt. 3A", // string (optional)
  line3: "", // string (optional)
  city: "Evansville", // string (required)
  state: "Indiana", // string (required)
  zip: "47705", // string (required)
  countryCode: "US", // string (required)
  deliveryContactDetails: {
    contactFullName: "Another Customer", // string (optional)
    contactPhoneNumber: {
      countryCode: "1", // string (required)
      phoneNumber: "5125555555", // string (required)
    },
  },
};

Token Data

Used in complete().

The following structure details the Token object.

paymentToken string required
This is the tokenized payment instrument.

tokenExpirationMonth string required
Two digit expiration month.

Min: 2 characters | Max: 2 characters

tokenExpirationYear string required
Four digit expiration year.

Min: 4 characters | Max: 4 characters

paymentAccountReference string required
PAR linked to the token's PAN.

Code Example

// Token data used in the secured payload (Complete)
const token = {
  paymentToken: "4987654321098765", // string (required)
  tokenExpirationMonth: "08", // string (required) — MM
  tokenExpirationYear: "2030", // string (required) — YYYY
  paymentAccountReference: "b8a4e4f2c3d9a7b6c5d4e3f2a1b0c9d", // string (required)
};

TransactionOptions

Used in complete().

The following represents the transaction configuration parameters that are specific to the payment transaction being requested by the Merchant.

merchantCategoryCode string optional
MCC of the Merchant, non-negative integers.

Format: Exactly 4 characters, non-negative, between 0000 and 9999, both inclusive.

billingPreference Enum optional
Verbosity of billing address required by the Merchant.
Valid values:

  • ALL (default)
  • ZIP_COUNTRY
  • NONE

payloadTypeIndicator Enum optional
The verbosity of payload requested.
Valid values are:

  • ID – Returns payloadId only (default)
  • PAYMENT – Returns payloadId, sessionId, and securedPayload

Code Example

// TransactionOptions used in Complete
const transactionOptions = {
  merchantCategoryCode: "5193", // string (optional)
  billingPreference: "ZIP_COUNTRY", // enum (optional) — ALL | ZIP_COUNTRY | NONE
  payloadTypeIndicator: "ID", // enum (optional) — ID | PAYMENT
};

TransactionValue

Used in checkout() and complete().

The TransactionValue objects, or data elements, represents the transaction value as split out into its individual components. This is used in checkout() for display purposes and in complete() to submit a transaction for tokenization. This should be included when a consumer intends to make an immediate payment.

At this time, the only supported transactionCurrencyCode is USD.

Should the merchant provide subtotal, discountAmount, taxAmount, and/or shippingAmount, the inputs will be used to customize the checkout UX with those inputs.

transactionCurrencyCode string required
The transaction currency code. For example, USD.

transactionAmount string required
The amount of the transaction.

If subtotal, discountAmount, or shippingAmount are used, the transactionAmount equals the subtotal minus the discountAmount plus tax and shippingAmount exactly, including rounding.

Format: 100.00. Must be non-negative to two decimal places.

subtotal string conditional
The total before any discounts, tax or shipping are applied.

Condition: Required if any of the following fields are provided:

  • discountAmount
  • taxAmount
  • shippingAmount

subtotal minus discountAmount, plus tax, shippingAmount must equal transactionAmount exactly including rounding.

discountAmount string optional
Represents the amount in dollars of the discount being applied.

optional If present, must be accompanied by subtotal and transactionValue.

Format: 100.00. Must be non-negative to two decimal places.

taxAmount string optional
The amount of tax applied to a transaction.

Condition: EXPRESS_CHECKOUT intent only, if present, must be accompanied by subtotal and transactionValue.

Reserved for future use.

Format: 100.00. Must be non-negative to two decimal places.

shippingAmount string optional
The amount of shipping cost applied to a transaction.

Condition: EXPRESS_CHECKOUT intent only, if present, must be accompanied by subtotal and transactionValue.

If 0.00 is passed, display “FREE”.

Note: If shipping is not determined at this stage, do not pass in checkout.

Code Example

// TransactionValue used in Checkout / Complete
const transactionValue = {
  transactionCurrencyCode: "USD", // string (required)
  transactionAmount: "73.29", // string (required) — 100.00 format, non-negative
  discountAmount: "5.00", // string (optional)
  subtotal: "68.29", // string (conditional) — required if discount/tax/shipping provided
  taxAmount: "0.00", // string (optional)
  shippingAmount: "10.00", // string (optional)
};

Travel Data

Used in complete().

The following structure represents optional travel-related parameters within the Enhanced Transaction Data object.

passengerName string optional
Traveler name.

Min: 0 characters | Max: 255 characters

roundTrip boolean optional
Whether departure and return trips are being purchased in the same transaction.

departureDate string optional
Date and time of departure in ISO 8601 format.

returnDate string optional
Date and time of return in ISO 8601 format.

departureLocation Object(Address) optional
Location from which the traveler is departing. See Address Data Elements for more information.

returnLocation Object(Address) optional
Location from which the traveler is returning. See Address Data Elements for more information.

Code Example

// TravelData used inside EnhancedTransactionData
const travelData = {
  passengerName: "Another Customer", // string (optional)
  roundTrip: true, // boolean (optional)
  departureDate: "2025-06-01T10:00:00Z", // string (optional) — ISO 8601
  returnDate: "2025-06-10T18:30:00Z", // string (optional) — ISO 8601
  departureLocation: {
    name: "Orchid Airport", // string (optional)
    line1: "1 Airport Way", // string (conditional)
    city: "Orchid City", // string (conditional)
    state: "Indiana", // string (conditional)
    zip: "47701", // string (required)
    countryCode: "US", // string (required)
  },
  returnLocation: {
    name: "Orchid Airport", // string (optional)
    line1: "1 Airport Way", // string (conditional)
    city: "Orchid City", // string (conditional)
    state: "Indiana", // string (conditional)
    zip: "47701", // string (required)
    countryCode: "US", // string (required)
  },
};

Updated about 1 month ago