Objects

Address Object

The following structure details the Address object.

name string Optional

Name of the organization/entity at the address. Maximum length 100 characters.

line1 string Conditional

Line 1 of the address.Maximum length 75 characters.

Condition: Returned if billingPreference is ALL.

line 2 string Optional Line 2 of the address. Maximum length 75 characters.

line3 string Optional

Line 3 of the address. Maximum length 75 characters.

city string Conditional

Name of the city. Maximum length 50 characters.

Condition: Returned if billingPreference is ALL.

state string Conditional

Name of the state. Maximum length 30 characters.

Condition: Returned if billingPreference is ALL

zip string Required Postal code for this address.Maximum length 10 characters.

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

Address Object Code Example

dictionary Address { 
     optional String name;
     conditional String line1;  
     optional String line2;  
     optional String line3; 
     conditional String city;  
     conditional String state; 
     required String zip; 
     required String countryCode;
} 

Transaction Object Options

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 are:

• 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

Transaction Object Code Example

dictionary TransactionOptions {
      optional String merchantCategoryCode;
      optional Enum billingPreference;
      optional Enum payloadTypeIndicator;
}

Transaction Value Objects

The Transaction Value 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 example: “100.00”. Must be non-negative to two decimal places.

subtotal string Conditional

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

Conditions: Required if any of the following fields are provided, and must be different from transactionVallue:

• 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 example: “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. Merchants may integrate to these fields before they are available without adverse impact to functionality. The IInput is used in the a future checkout user experience. 

Format example: “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.      

Reserved for future use. Merchants may integrate to these fields before they are available without adverse impact to functionality. The Input is used in a future checkout user experience.

Transaction Value Data Elements

dictionary TransactionValue {
   required String transactionCurrencyCode; 
   required String transactionAmount;  
   optional String discountAmount;  
   conditional String subtotal; 
   optional String taxAmount; 
   optional String shippingAmount; 

}

Cobrand Elements

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. Maximum length 25 characters.

benefitsOffered boolean. Optional

Default value is FALSE.

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

Cobrand Elements Code Example

dictionary Cobrand { 
     required String cobrandName;
     optional Boolean benefitsOffered;
} 

Enhanced Transaction Data Objects

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.

Enhanced Transaction Data Code Example

dictionary EnhancedTransactionData {
      optional EcomData ecomData;
      optional TravelData travelData;
}

Ecom Data Objects

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. Maximum length 10 characters.

orderHighestCost string Optional

Dollar value of most expensive item ordered. Maximum length 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.

Ecom Data Code Example

dictionary EcomData {
      optional Boolean cartContainsGiftCard;
      optional Boolean orderForPickup;
      optional String orderQuantity;
      optional String orderHighestCost;
      optional Address finalShippingAddress;
}

Travel Data Elements

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

passengerName string Optional

Traveler name. Maximum length 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 departure 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.

Travel Data Code Example

dictionary TravelData {
      optional String passengerName;
      optional Boolean roundTrip;
      optional String departureDate;
      optional String returnDate;
      optional Address departureLocation;
      optional Address returnLocation;
}

Merchant Client Data Elements

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.Maximum length 50 characters.

name string Optional

Alphanumeric display name associated with the Client to be used for presentation purposes within the user experience.Maximum length 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.Maximum length 50 characters.

externalSubMerchantId string Optional

Merchant identifier within the merchant’s system. Maximum length 50 characters.

externalSubMerchantId string Optional

Represents the client profile used during checkout.

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

Maximum length 50 characters.

merchantCategoryCode string Optional

MCC for the merchantFormat: 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. Maximum length 50 characters.

statementDescriptor string Optional

Known by some as (soft descriptor, dynamic descriptor). This field captures how the transaction would appear on the buyers statement. Maximum length 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.

Maximum length 2083 characters.

Client Data Elements Example Code

dictionary Client{
	required String id;
	optional String name;
	optional String profileId;
	optional String externalSubMerchantId;
	optional String merchantCategoryCode;
	optional String brandName;
	optional String statementDescriptor;
	optional String url;
}

Sample Code

Initialize

//Request:
 initialize(; client: {
         id: "mOYSSfG9VQonnTRZ8Zct5h2GnAeNj381GHQy0xIeCWsrmE1LY",
         name: "Orchid Bonanza",
         externalMerchantID: "TRZ8Zet5h2GnÄeNj381GHQy0xIeCW",
         merchantCategoryCode: "303"
         brandName: "Orchid west",
         statementDescriptor: "PAZE*ORCHID*0303 $13.00
         url::"https://www.example.com/myapp
        }
})
//Response: 
{}

Masked Card Data Elements

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

digitalCardId string Required

Unique Identifier of the card (UUID). Maximum length 36 characters.

panLastFour string Required

Last 4 digits of the card.

paymentAccountReference* string Required

Payment Account Reference (PAR) - A value assigned to the underlying cardholder account that uniquely identifies the underlying account to which a Payment Card is associated.

panExpirationMonth string Conditional

2-digit Primary Account Number (PAN) expiration month. Condition: Required if card supports expiry

panExpirationYear string Conditional

2-digit Primary Account Number (PAN) expiration year.

Condition: Required if card supports expiry

paymentCardDescriptor string Required.

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

Example: ‘Travel Rewards', ‘Cashback Rewards' etc

digitalCardData Object(DigitalCardData) Required

Digital Card Art. See Digital Card Data Elements for more information

billingAddress Object(Address) Conditional

The 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

Brand of payment instrument. Valid values:

• VISA
• MASTERCARD
• DISCOVER

paymentCardNetwork enum Required

Valid values:

• VISA
• MASTERCARD
• DISCOVER

Note: Debit credentials from Paze allow for processing on alternative networks as indicated by applicable BIN tables.

dictionary MaskedCard {
       required String digitalCardId;
       required String panLastFour;
       required String paymentAccountReference;
       conditional String panExpirationMonth;
       conditional String panExpirationYear;
       required String paymentCardDescriptor;
       required Enum paymentCardType;
       required Enum paymentCardBrand;
       required Enum paymentCardNetwork;
       required DigitalCardData digitalCardData;
       conditional Address billingAddress;
}

Digital Card Data Elements

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 cardArt. Can be card or issuer specific value.Example: ‘https://www.staticv.me/lg_non-visa_card.png’

artHeight number Required

Height of the card art image in pixels.

artWidth number Required

Width of the card art image in pixels.

Digital Card Data Elements Code Example

dictionary DigitalCardData { 
     required URL artUri;
     required Number artHeight;
     required Number artWidth;
}

Token Data Elements

The following structure details the Token object.

paymentToken string Required

This is the tokenized payment instrument.

tokenExpirationMonth string Required

Two digit expiration month.

tokenExpirationYear string Required

Four digit expiration year.

paymentAccountReference. string Required

PAR linked to the token's PAN.

Token Data Elements Code Example

dictionary Token { 
	required String paymentToken; 
	required String tokenExpirationMonth; 
	required String tokenExpirationYear; 
required String paymentAccountReference;
}

Checkout Response Objects

The following structure details the Checkout Response object.

sessionId string Conditional

Session reference identifier generated by the Merchant. It is recommended that the session reference identifier be identical across the Checkout request and the Complete request. Maximum length 255 characters.

Condition: Returned when sessionId is present in the Checkout request.

consumer object(Consumer) Required

Details associated with the authenticated consumer.

maskedCard object(MaskedCard) Required

Masked card details of the selected card. See Masked Card Data Elements for more information.

shippingAddress object(ShippingAddress) Conditional

The selected shipping address. See the Shipping Address Data Elements for more information.

Condition: Returned only when shippingPreference is not NONE.

Checkout Response Data Elements Code Example

dictionary CheckoutResponse {
     conditional String sessionId;
     required Consumer consumer;
     required MaskedCard maskedCard;
     conditional ShippingAddress shippingAddress;
}

Complete Response Data Elements

The following structure details the Complete Response object.

payloadId string Required

This is the unique identifier generated by Paze to track and link wallet transaction-specific messages. This will be used as the wallet transaction identifier assigned by the Paze system for this particular transaction.

Maximum length 50 characters.

sessionId string Required

Session reference identifier generated by the Merchant. Maximum length 255 characters.

Condition: Returned if sessionId was provided by the Merchant (echoed from Complete request).

securePayload Object(SecuredPayload) Conditional

Information necessary to process payment. See Secured Payload Data Elements for more information.

Condition: Returned when transactionOptions.payloadTypeIndicator is PAYMENT.

Complete Response Data Elements Code Example

dictionary completeResponse {
     required String payloadId;
     conditional String sessionId;
     conditional JWE<JWS<Payload>> securedPayload;    
}

Secured Payload Data Elements

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. The JWEs must have their signatures validated before being decrypted.

The following structure details the Encrypted Signed Payload object.

clientId string Required

Client identifier. This is generated by Paze and shared with the Merchant during onboarding.

Maximum length 50 characters.

profileId string Required

The Client profile that was used during checkout. Maximum length 50 characters.

token object(Token) Required

A token payload that contains the token number and associated attributes.

paymentCardNetwork. enum Required

Valid values:

• VISA
• MASTERCARD
• DISCOVER

dynamicData list(DynamicData) Required

Dynamic data applicable for a consumer-initiated payment or request to keep a card on file. For more information, see Dynamic Data Elements.

billingAddress object(Address) Conditional

Billing address of the card selected, at the verbosity indicated by transactionOptions.billingPreference.

If transactionOptions.billingPreference is ZIP_COUNTRY, other Address data elements will not be returned. See Address Data Elements for more information.

Condition: Provided when transactionOptions.billingPreference is NOT set to NONE.

consumer object(Consumer) Required

Information about the consumer who completed the checkout

eci string Conditional

Electronic Commerce Indicator. Code indicating a transaction’s level of adherence to 3D Secure (3DS) authentication standards. Maximum length 2 characters.

Condition: Provided when the Merchant submitted a transaction for PURCHASE or BOTH.

Secured Payload Data Elements Code Example

dictionary Payload {
      required String clientId;
      required String profileId;
      required Token token;
      required Enum paymentCardNetwork;
      required List<DynamicData> dynamicData;
      conditional Address billingAddress;
      required Consumer consumer;
      conditional String eci;
}

Dynamic Data Elements

The following structure details the Dynamic Data object. This data is used for cryptographic verification of the Payment Transaction during authorization.

dynamicDataValue string Required

The dynamic data value (structure dependent on Card Network). Maximum length 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. The underlying dynamicDataExpiration value conforms to UTC time in Unix epoch format.

Dynamic Data Elements Code Example

dictionary DynamicData {
      required String dynamicData;
      required Enum dynamicDataType;
      optional String dynamicDataExpiration;
}

Consumer Data Object

The following structure details the Consumer object:

firstName string Optional

Consumer first name.

Maximum length 100 characters.

lastName string. Optional

Consumer last name.

Maximum length 100 characters.

fullName. string Required

Consumer full name. Maximum length 100 characters.

emailAddress string Optional

Consumer email address. The underlying email address value MUST conform to the RFC 5322 address-spec syntax simplified to all lowercase characters.

Maximum length 128 characters.

mobileNumber object(phoneNumber) Optional

Consumer mobile phone number. See the Phone Number Data Elements for more information.

countryCode string Optional

Consumer provided CountryCode

The underlying phone number value for countryCode conforms to ISO 3166-1 alpha-2 format, e.g., "US"

languageCode string Optional

Consumer’s preferred languageBased on ISO format for language (ISO 639-1) and alpha-2 country code (ISO 3166-1 alpha-2). separated using a “_”. For example, "en_US".

Consumer Data Elements Code Example

dictionary Consumer {
      optional String firstName;
      optional String lastName;
      required String fullName;
      required String emailAddress;
      optional PhoneNumber mobileNumber;
      optional String countryCode;
      optional String languageCode;
}

Phone Number Data Objects

The following structure details the Phone Number object.

countryCode string Required

The phone number country code; International Subscriber Dialing (ISD) Codes. For example, “1” for the US. The underlying phone number value MUST confirm to the E.164 format without the plus sign.Maximum length 1 characters as Paze is in US only.

phoneNumber string Required

The phone number. The underlying phone number value MUST confirm to the E.164 format without the plus sign. Maximum length 10 characters as Paze is in US only.

Phone Number Data Elements Code Example

dictionary PhoneNumber {
      required String countryCode;
      required String phoneNumber;
}

Shipping Address Data Elements

The following structure details the Shipping Address object.

name string Required

The name of the organization/entity at the address.

Maximum length 100 characters.

line1 string Required

Address first line. Maximum length 75 characters.

line2 string Optional

Address second line. Maximum length 75 characters.

line3 string Optional

Address third line. Maximum length 75 characters.

city string Required

The name of the city. Maximum length 50 characters.

state string Required

State name. Maximum length: 30 characters.

zip string Required

Address zip code. Maximum length 10 characters.

countryCode string Required

Address country code following the ISO 3166-1 alpha-2 country code format.

deliveryContactDetails string Optional

Delivery contact details for a shipping address. See the Delivery Contact Details Data Objects for more information.

Shipping Address Data Objects Code Example

dictionary ShippingAddress {  
     required String name;
     required String line1;  
     optional String line2; 
     optional String line3; 
     required String city;  
     required String state; 
     required String zip; 
     required String countryCode; 
    optional DeliveryContactDetails deliveryContactDetails; 
} 

Delivery Contact Details Data Object

The following structure details the DeliveryContactDetails object.

contactFullName string Optional

Consumer-provided name of the contact person. Maximum length 100 characters.

contactPhoneNumber object(phoneNumber) Optional

Consumer-provided phone number for the contact person.

Delivery Contact Details Data Elements Code Example

dictionary ShippingAddress {  
     required String name;
     required String line1;  
     optional String line2; 
     optional String line3; 
     required String city;  
     required String state; 
     required String zip; 
     required String countryCode; 
    optional DeliveryContactDetails deliveryContactDetails; 
}