Merchant JavaScript SDK
Introduction
The Paze Merchant JavaScript Software Development Kit Technical Requirements provides details about the Application Programming Interfaces (APIs) used to return tokenized payment information as well as related checkout details. This document also describes how to use the SDK in a Merchant’s front-end web implementation.
For mobile native application (iOS/Android) implementation, refer to the Paze Merchant Mobile Application API Technical Requirements specification.
There are four available APIs discussed in this document:
- Initialize: Passes in the assigned Merchant identifier (issued during onboarding) and initiates fraud systems for a secure checkout.CanCheckout: Checks whether a specified consumer identity (email address or mobile phone number) has an eligible wallet with Paze .
- CanCheckout: CanCheckout allows emails to be passed, as does the checkout call. Lookup keys can now also look up the mobile number. This API checks whether a specified consumer lookup key (email address or mobile number) is known to Paze. If both are passed, the Mobile Number will be used instead of the Email Address CanCheckout can be used to facilitate a dynamic presentation of the Paze button or user interface only to consumers who are eligible
- Checkout: Runs the complete digital wallet consumer-facing flow (including lookup, authentication of consumer, and consumer information selection) and returns a summary of the consumer’s card and address selection.
- Complete: Closes the Merchant and consumer sessions and provides payment details required to successfully process the Payment Transaction, whether the consumer intends to make a payment immediately, indicates a card to be put on file with the Merchant, or both.
Sensitive payment data can also be accessed via the Merchant Business to Business (B2B) API. This can be used when the Merchant’s payment processor aids in decryption or where sentative information is preferred to be obtained outside of the JavaScript SDK. For additional information, reference the Paze Merchant Business to Business API Technical Requirements document in Venue.
Note: Complete must still be called to close the session even if the B2B API is being used.
The JavaScript APIs will use Promise objects that represent the eventual completion (or failure) of an asynchronous operation, and its resulting value.
Prerequisites
To use these APIs, Merchants must establish a relationship with a Paze Distributor, an entity who is approved to make the Paze Service available to Merchants and will sponsor and onboard the Merchant. Upon onboarding, Merchants will be assigned environment specific client identifiers and exchange required cryptographic material.
Detail Tables – Column Definitions
The following sections contain tables of fields with one or more of the columns described below.
Detail Table Column Definitions
| Column Name | Column Description |
|---|---|
| Seq. # | Position of the field in the code |
| Field/Element Name | Name of field or element |
| Field/Element Type | Field or element data type |
| Field/Element Usage | How the field or element is used:Required – Must be providedOptional – Can be provided when available and/or applicableConditional – Conditionally provided based on data in other fields. For example, if a phone number is not present, the email field must be used. |
| Description | Field description |
Web Client SDK Setup
The JavaScript endpoints below are available for use during testing and production.
JavaScript SDK Endpoints
| Environment | JavaScript SDK Endpoint |
|---|---|
| Sandbox | https://checkout.wallet.cat.earlywarning.io/web/resources/js/digitalwallet-sdk.js |
| Production | https://checkout.paze.com/web/resources/js/digitalwallet-sdk.js |
Before calling Initialize, Merchants must load the Paze SDK. The SDK creates a popup that is used to host the user interface (UI) for the SDK.
The following example shows how to load the SDK and create an adapter:
<head>
</head>
<body>
<script src=”https://checkout.wallet.cat.earlywarning.io/web/resources/js/digitalwallet-sdk.js” type=”text/javascript”>
</script>
<script>
let digitalWalletAdaptor = window.DIGITAL_WALLET_SDK;
</script>
</body>
When presenting any Paze checkout user experience, the SDK will drive the window as an overlay to the Merchant site.
Encryption Certificate and Key Alias
Paze checkout response (securePayload field in completeResponse) is encrypted, and it is the responsibility of Merchant or the decrypting entity to decrypt the response. The Merchant or decrypting entity will provide a public certificate in PEM format with a keyAlias, 2048 or 4096 bits, self-signed, x509, SHA256, RSA key, when onboarding with Paze.
Signature Validation
Paze checkout response (securePayload field in completeResponse) is signed with a Paze signature key. The Merchant or decrypting entity can retrieve the signature key from the well-known URL and validate the signature before decrypting the response. The well-known URL endpoint can be found in the table below.
Signature Endpoints
| Environment | URL |
|---|---|
| Testing | https://auth.wallet.cat.earlywarning.io/jwks |
| Production | https://auth.wallet.earlywarning.com/jwks |
Web Client SDK
Initialize, Checkout, and Complete must be used for all payment actions. CanCheckout can be used to facilitate a dynamic presentation of the Paze button or user interface by checking consumer eligibility, however, it is not explicitly required.
All JavaScript (JS) SDK APIs use JS Promises instead of events or callbacks. The Paze SDK will always respond back with a Promise.
Initialize
Initialize Paze with common state, starting the Merchant session. This is required before calling any other methods and is recommended to start with page load, since it will begin running fraud checks against the consumer’s device. Multiple Merchant sessions may run in parallel.
Initialize Request Parameters
Initialize Request Parameters
| Field Name | Field Type | Field Usage | Description |
|---|---|---|---|
| client | Object(Client) | Required | Details the Client InformationSee Client Data Elements for more information. |
Initialize Promise – Resolve and Reject
| function | Description |
|---|---|
| resolve() | This is the JS Promise (fulfilled) call when the request is successfully processed by the Paze SDK. |
| Reject() | This is the JS Promise call when there is an error. The object passed in is an error object as defined in “Errors” section in this document. |
Initialize Business Errors
| Reason Code | Description |
|---|---|
| CLIENT_ID_MISSING | The identifier for the Client is missing. |
| INVALID_CLIENT_ID | The identifier for the Client is invalid. |
| INVALID_PROFILE_ID | The identifier for the profile is invalid. |
Standard errors are enumerated in their own section and are therefore excluded from API-specific tables.
Initialize Code Examples
initialize ({
required Client client;
})
// Response – empty
CanCheckout
CanCheckout allows emails to be passed, as does the checkout call. Lookup keys can now also look up the mobile number.
This API checks whether a specified consumer lookup key (email address or mobile number) is known to Paze. If both are passed, the Mobile Number will be used instead of the Email Address. CanCheckout can be used to facilitate a dynamic presentation of the Paze button or user interface only to consumers who are eligible.
The SDK hashes the consumer lookup key before transmitting it.
CanCheckout Request Parameters
| Field Name | Field Type | Field Usage | Description |
|---|---|---|---|
| emailAddress | String | Conditional | Email address as consumer identity.The underlying email address value MUST conform to the RFC 5322 address-spec syntax simplified to all lowercase characters. Maximum length 128 characters.Condition: Required if a phoneNumber is not provided. Conditionally invalid if phoneNumber is provided. |
| mobileNumber | String | Conditional | Mobile number as consumer identitySee Phone Number Data Elements for more information.Supports only US based phone numbers. Formatting can include or not include hyphens and country code such as: 1) 51255555552) 512-555-55553) 151255555554) 1-512-555-5555The underlying phone number value MUST conform to the E.164 format without the plus sign. Maximum length 15 characters.Condition: mobileNumber is required if emailAddress is not provided. |
CanCheckout Response Attributes
| Field Name | Field Type | Field Usage | Description |
|---|---|---|---|
| consumerPresent | Boolean | Required | Flag indicating whether a wallet is associated with the provided email address or mobile number and has at least one card.Email addresses or mobile numbers associated with suspended wallets will still return TRUE. |
CanCheckout Promise – Resolve and Reject
| function | Description |
|---|---|
| resolve() | This is the JS Promise (fulfilled) call when the request is successfully processed by the Paze SDK. |
| 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 in this document. |
CanCheckout Code Examples
checkout({
conditional String emailAddress;
conditional String mobileNumber;
})
// Response
dictionary {
required Boolean consumerPresent;
}
Checkout
Invoking Checkout launches the Paze user interface (UI) via a popup. The flow can be customized using the actionCode field depending on the intended action of the customer.
- Selecting a card
- Changing their shipping address, or
- Selecting a different card
If actionCode is START_FLOW
- If CanCheckout has not returned TRUE (including instances where CanCheckout has not been called) and the consumer’s lookup key (email address or mobile number) is not provided in the request, the consumer will be prompted to submit it within the SDK’s UI.
- Lookup is performed using the email address or mobile number.
- If the consumer is not found or is ineligible, the SDK will display an in-line error screen so the consumer knows to return to the Merchant’s site.
- If the consumer is found and is eligible, the SDK will proceed normally.
- If CanCheckout has returned TRUE and the consumer’s lookup key was not provided in Checkout, then the SDK’s UI will launch using the lookup key that was provided in CanCheckout.
- Regardless of the response to CanCheckout, if the consumer’s lookup key (email address or mobile number) is provided in Checkout, then the SDK will perform a lookup using the lookup key provided in Checkout 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 will return an error so the Merchant can route them to an alternative payment method.
- If the consumer is found and is eligible to check out, the SDK will proceed normally.
- The SDK will render the following screens:
- consumer 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 respective screens to select the card or shipping address.
- The Merchant must start a new checkout/user session (START_FLOW) when:
- Excessive time has elapsed.
- The consumer will see a warning screen six (6) minutes after their last activity in the Paze UI. The SDK will end the consumer’s session and present a timeout screen 8 minutes after the consumer’s last activity (2 minutes after they are shown the inactivity warning).
- 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 API request.
Checkout Request Parameters
| Seq. # | Field Name | Field Type | Field Usage | Description |
|---|---|---|---|---|
| 1 | emailAddress | String | Optional | Email address as consumer identity.The underlying email address value MUST conform to the RFC 5322 address-spec syntax simplified to all lowercase characters. The maximum length 128 characters.If the emailAddress or mobileNumber are not present in the request, then Paze will use the lookup key submitted in the Merchant session’s most recent CanCheckout request (if applicable) or prompt the consumer for a lookup key. |
| 2 | mobileNumber | String | Optional | Mobile number as consumer identitySee Phone Number Data Elements for more information.Condition: Required if emailAddress not provided.Supports only US based phone numbers. Formatting can include or not include hyphens and country code such as:1) 51255555552) 512-555-55553) 151255555554) 1-512-555-5555The underlying phone number value MUST confirm to the E.164 format without the plus sign. Maximum length 154 characters.If neither the mobileNumber or emailAddress is present in the request, then Paze uses the lookup key submitted in the Merchant session’s most recent CanCheckout request (if applicable) or will prompt the consumer for a lookup key. |
| 3 | sessionId | String | Optional | 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 Complete request.Maximum length 255 characters.NOTE: This field is required if the Merchant is enrolled in Paze’s Fraud Liability Shift Program to maintain eligibility. |
| 4 | actionCode | Enum | Optional | Valid values:START_FLOW (default)CHANGE_CARDCHANGE_SHIPPING_ADDRESS |
| 5 | intent | Enum | Optional | Valid values:REVIEW_AND_PAY (default)EXPRESS_CHECKOUTADD_CARDConsider the primary intent of the API call when setting this value. For example, for a consumer who should be returned to a Merchant order review page, intent should be set to REVIEW_AND_PAY.It is the Merchant’s responsibility to ensure that the flow is correct for their consumers and aligns to the correct use of intent. .Refer to the Paze Merchant Integration Guide for screenshots of each intent. |
| 6 | transactionValue | Object (Transaction Value) | Conditional | Currency code, amount of transaction, discount, tax and shipping inputs.See Transaction Value Data Elements for more information.Note: No cart value will be displayed in the Paze UI if this is excluded from the request. It is not needed if consumer is selecting a card to keep on file with Merchant.Merchants are recommended, but not explicitly required, to provide discount, tax and shipping inputs.Condition: Required if intent is EXPRESS_CHECKOUT. Request will be invalid when transactionValue is provided if intent is ADD_CARD. |
| 7 | confirmLaunch | Boolean | Optional | Determines whether a consumer needs to confirm their intention to launch Paze.If a consumer was directed to Paze by the merchant (via automatic initiation), setting this value to TRUE will provide additional information about Paze and allow the consumer to launch the Paze UX after confirming on the intermediate screen.For an automatic initiation experience, this should be set to true.If a consumer has already clicked a Paze button rendered on the merchant site, setting this value to FALSE will bypass the intermediate screen and automatically launch the Paze UX.The default value is FALSE. |
| 8 | shipping Preference | Enum | Conditional | Whether Merchant wants to have shipping address collected.Valid values:ALL (default)NONENote: NONE suppresses address selection/management screens. Condition: shippingPreference must be set to NONE if intent is ADD_CARD. |
| 9 | billingPreference | Enum | Optional | Verbosity of billing address required by the Merchant.Valid values:ALL (default)ZIP_COUNTRY (scoped for future release)NONE |
| 10 | cobrand | List(Cobrand) | Optional | Details for cobranded cards offered by the Merchant.This field will be used to highlight consumers’ 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. |
| 11 | accepted ShippingCountries | List | Optional | Array of country codes in ISO 3166-1 alpha-2 format as Shipping restrictions.Shipping region country codes that limit the selection of eligible shipping addressesAn empty list or the absence of this data element means that all countries are acceptedOnly US is currently supported |
| 12 | acceptedPayment CardNetworks | List | Conditional | An array of payment card networksValid values are:VISAMASTERCARDDISCOVERAn 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 Paze onboards other card networks.Condition: This field should be included if the Merchant does not support a given card network so that Paze displays accepted cards. |
Checkout Response Attributes
| Seq. # | Field Name | Field Type | Field Status | Description |
|---|---|---|---|---|
| 1 | result | Enum | Required | Valid values are:“COMPLETE”: Checkout processing completed normally. “INCOMPLETE”: Consumer exited Paze, failed the authentication check, or did not complete Checkout or their user session expired. |
| 2 | checkoutResponse | Object(CheckoutResponse) | Conditional | This is the JWS of the checkout response.See Checkout Response Data Elements for more information.Condition: Applicable when checkout result is COMPLETE. |
Checkout Promise – Resolve and Reject
| function | Description |
|---|---|
| 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 in the table. |
| Reject() | This is the JS Promise call when there is an error. The object passed in is an error object as defined in “Errors” section in this document. |
Checkout Business Errors
| Reason Code | Description |
|---|---|
| ACCT_INACCESSIBLE | The wallet exists but is not currently accessible (e.g., is suspended) |
| CLIENT_DATA_INVALID | Invalid client data.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. |
Checkout Code Examples
checkout({
optional String emailAddress;
conditionalString mobileNumber;
optional String sessionId;
optional Enum actionCode;
optional Enum intent;
conditional TransactionValue transactionValue;
conditional Enum shippingPreference;
optional Enum billingPreference;
optional List<Cobrand> cobrand;
optional List<String> acceptedShippingCountries;
optional List<String> acceptedPaymentCardNetworks;
})
// Response
dictionary {
required String result;
conditional JWS<CheckoutResponse> checkoutResponse;
}
Complete
This API closes the Merchant and consumer sessions (where applicable) and provides a payment identifier and, if requested, the card details required to successfully process the Payment Transaction.
If both the Merchant and consumer sessions have timed out without receiving a valid input, Complete should not be invoked. If it is invoked, Merchants will receive an INCOMPLETE_CHECKOUT error.
The Merchant must incorporate a card-on-file consent check into their own digital property if they intend to use that functionality in Complete.
Card networks handle card-on-file functionality in different ways. Refer to individual card networks’ documentation for clarification and the most up-to-date guidance.
- Visa allows Merchants or their payment service providers to perform a token-for-token swap with a previous payment token. This means that, if the transaction type is BOTH, the dynamic data for CARD_ON_FILE will be identical to the dynamic data for PURCHASE.
- Mastercard has separate tokenization protocols for purchases and cards-on-file. This means that, if the transaction type is BOTH, the dynamic data will vary and need to be handled differently between PURCHASE and CARD_ON_FILE use cases.
- Discover does not support card-on-file functionality. Only PURCHASE is supported for Discover cards.
Complete Request Parameters
| Seq. # | Field Name | Field Type | Field Usage | Description |
|---|---|---|---|---|
| 1 | sessionId | String | Optional | Session reference identifier generated by the Merchant. If present here, it will be returned and can be used to tie the Merchant-specific session or transaction information to the payloadId because both of the fields, sessionId and payloadId, will be passed back in the signed completeResponse as well as the B2B API getPayload response. This is recommended to be identical across the Checkout request and the Complete request. Maximum length 255 characters.Note: This field is required if transactionType is PURCHASE or BOTH and if the Merchant is enrolled in Paze’s Fraud Liability Shift Program to maintain eligibility. |
| 2 | transactionType | Enum | Required | Type of transactionValid values:PURCHASECARD_ON_FILEBOTHNOTE: 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. |
| 3 | transactionOptions | Object (Transaction Options) | Conditional | Client configuration data related to the transaction.See Transaction Options Data Elements for more information.Note: This is required if the transactionType is PURCHASE or BOTH. |
| 4 | transactionValue | Object (TransactionValue) | Conditional | Currency code and amount of transaction.See Transaction Value Data Elements for more information.Note: Required if transactionType is PURCHASE or BOTH. |
| 5 | enhanced TransactionData | Object (Enhanced TransactionData) | Optional | Merchant-provided parameters that may impact fraud decisioning.See Enhanced Transaction Data Elements for more information. |
Complete Response Attributes
| Field Name | Field Type | Field Usage | Description |
|---|---|---|---|
| completeResponse | Object(CompleteResponse) | Required | This is the JWS of the complete response.See Complete Response Data Elements for more information. |
Complete Promise – Resolve and Reject
| function | Description |
|---|---|
| resolve() | This is the JS Promise (fulfilled) call when the request is successfully processed by the Paze SDK.A JSON object will be passed in the response with the JWS(completeResponse) value. |
| Reject() | This is the JS Promise call when there is an error. The object passed in is an error object as defined in “Errors” section in this document. |
Complete Business Errors
| Reason Code | Description |
|---|---|
| ACCT_INACCESSIBLE | The wallet account exists but is not currently accessible (e.g., is suspended). |
| INCOMPLETE_CHECKOUT | Complete API is called before checkout API has finished successfully |
Complete Code Examples
complete ({
optional String sessionId;
required Enum transactionType
optional TransactionOptions transactionOptions;
conditional TransactionValue transactionValue;
optional EnhancedTransactionData enhancedTransactionData;
optional Enum processingNetwork;
})
// Response
dictionary {
required JWS<completeResponse> completeResponse;
}
SDK Backward Compatibility Considerations
The following changes are considered backward-compatible.
- Adding a new API resource or method.
- Adding a new optional request parameter to an existing API method.
- Adding a new Enum value. The value can be added either in the request or the response.
- Relaxing some of the constraints on an existing request parameter. For example, making it optional.
- Adding a new response parameter to the API response.
- Changing the format of opaque string identifiers.
In simple terms, all these rules mean:
- Ignore any unknown fields or Enum values received as part of API responses.
- Do not make any assumptions except length about opaque string identifiers.
- The Service Operator may add new optional parameters to existing APIs and relax constraints on existing request parameters at any time.
Element Types
Address Data Elements
The following structure details the Address object.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | name | String | Optional | Name of the organization/entity at the address.Maximum length 100 characters. |
| 2 | line1 | String | Conditional | Line 1 of the address.Maximum length 75 characters.Condition: Returned if billingPreference is ALL. |
| 3 | line2 | String | Optional | Line 2 of the address.Maximum length 75 characters. |
| 4 | line3 | String | Optional | Line 3 of the address.Maximum length 75 characters. |
| 5 | city | String | Conditional | Name of the city.Maximum length 50 characters.Condition: Returned if billingPreference is ALL. |
| 6 | state | String | Conditional | Name of the state.Maximum length 30 characters.Condition: Returned if billingPreference is ALL. |
| 7 | zip | String | Required | Postal code for this address.Maximum length 10 characters. |
| 8 | countryCode | String | Required | Country code for this address.Underlying countryCode value MUST conform to the ISO 3166-1 alpha-2 country code. |
Address Elements 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 Options Data Elements
The following structure represents the transaction configuration parameters that are specific to the payment transaction being requested by the Merchant.
Transaction Options Data Elements:
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | merchantCategoryCode | String | Optional | MCC of the Merchant, non-negative integers.Format: exactly 4 characters, non-negative, between 0000 and 9999, both includsive |
| 2 | billingPreference | Enum | Optional | Verbosity of billing address required by the Merchant.Valid values:ALL (default)ZIP_COUNTRYNONE |
| 3 | payloadTypeIndicator | Enum | Optional | The verbosity of payload requested.Valid values:ID – Returns payloadId only (default)PAYMENT – Returns payloadId, sessionId (if applicable), and securedPayload |
Transaction Options Data Elements Code Example
dictionary TransactionOptions {
optional String merchantCategoryCode;
optional Enum billingPreference;
optional Enum payloadTypeIndicator;
}
Transaction Value Data Elements
The Transaction Value 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 transactionCurrencyCode supported is ‘USD’.
Should the merchant provide subtotal, discountAmount, taxAmount, and or shipping amount, the inputs will be used to customize the checkout UX with those inputs.
dictionary TransactionValue {
required String transactionCurrencyCode;
required String transactionAmount;
}
Cobrand Elements
The following structure details the Cobrand object.
Cobrand Data Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | cobrandName | String | Required | Product name of the cobrand card. Must match exactly with the card name received from the network. Maximum length 50 characters. |
| 2 | benefitsOffered | Boolean | Optional | Default value is FALSENote: 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 Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | eComData | Object(EcomData) | Optional | Details pertaining to electronic commerce purchases.See eComData elements for more information. |
| 2 | 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 Elements
The following structure represents optional electronic commerce-related parameters within the Enhanced Transaction Data object.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | cartContainsGiftCard | Boolean | Optional | Whether current transaction includes a gift card purchase. |
| 2 | orderForPickup | Boolean | Optional | Whether consumer order will be picked up rather than shipped. |
| 3 | orderQuantity | String | Optional | Number of items ordered.Maximum length 10 characters. |
| 4 | orderHighestCost | String | Optional | Dollar value of most expensive item ordered. Maximum length 10 characters. |
| 5 | finalShippingAddress | Object(Address) | Optional | Destination of items ordered. Recommended for use if the Merchant does not intend to use PazeSM 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.
Travel Data Data Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | passengerName | String | Optional | Traveler name.Maximum length 255 characters. |
| 2 | roundTrip | Boolean | Optional | Whether departure and return trips are being purchased in the same transaction. |
| 3 | departureDate | String | Optional | Date and time of departure in ISO 8601 format. |
| 4 | returnDate | String | Optional | Date and time of return in ISO 8601 format. |
| 5 | departureLocation | Object(Address) | Optional | Location from which the traveler is departing.See Address Data Elements for more information. |
| 6 | 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.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | id | String | Required | Client identifier. This is generated by Paze and shared with client during onboarding.Maximum length 50 characters. |
| 2 | name | String | Optional | Alphanumeric display name associated with the Client to be used for presentation purposes within the user experience.Maximum length 50 characters. |
| 3 | 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. |
| 4 | externalSubMerchantId | String | Optional | Merchant identifier within the merchant’s system.Maximum length 50 characters. |
| 5 | merchantCategoryCode | String | Optional | MCC for the merchantFormat: String; exactly 4 chars ( between 0000 and 9999 both inclusive) |
| 6 | 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. |
| 7 | 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. |
| 8 | 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.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | digitalCardId | String | Required | Unique Identifier of the card (UUID). Maximum length 36 characters. |
| 2 | panLastFour | String | Required | Last 4 digits of the card. |
| 3 | 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. |
| 4 | panExpirationMonth | String | Conditional | 2-digit Primary Account Number (PAN) expiration month. Condition: Required if card supports expiry |
| 5 | panExpirationYear | String | Conditional | 4-digit PAN expiration year.Condition: Required if card supports expiry |
| 6 | paymentCardDescriptor | String | Required | A free-form string (max of 32 characters) used for card/program recognition. Example ‘Travel Rewards', ‘Cashback Rewards' etc. |
| 7 | digitalCardData | Object(DigitalCardData) | Required | Digital Card Art.See Digital Card Data Elements for more information. |
| 8 | billingAddress | Object(Address) | Conditional | Billing address for display purposes.See Address Data Elements for more information. Condition: billingPreference is not NONE. |
| 9 | paymentCardType | Enum | Required | Valid values: · CREDIT · DEBIT |
| 10 | paymentCardBrand | Enum | Required | Brand of payment instrument.Valid values: · VISA · MASTERCARD · DISCOVER |
| 11 | 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.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | artUri | 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’ |
| 2 | artHeight | Number | Required | Height of the card art image in pixels. |
| 3 | 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.
Token Data Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | paymentToken | String | Required | This is the tokenized payment instrument. |
| 2 | tokenExpirationMonth | String | Required | Two-digit expiration month. |
| 3 | tokenExpirationYear | String | Required | Four-digit expiration year. |
| 4 | 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 Data Elements
The following structure details the Checkout Response object.
Checkout Response Data Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | sessionId | String | Conditional | Session reference identifier generated by the Merchant. This is recommended to be identical across the Checkout request and the Complete request.Maximum length 255 characters.Condition: Returned when sessionId is present in the Checkout request. |
| 2 | consumer | Object(Consumer) | Required | Details associated with the authenticated consumer. |
| 3 | maskedCard | Object(MaskedCard) | Required | Masked card details of the selected card.See Masked Card Data Elements for more information. |
| 4 | shippingAddress | Object(ShippingAddess) | Conditional | The selected shipping address.See 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.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | 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 Pazesystem for this particular transaction.Maximum length 50 characters. |
| 2 | sessionId | String | Conditional | Session reference identifier generated by the Merchant.Maximum length 255 characters.Condition: Returned if sessionId was provided by the Merchant (echoed from Complete request). |
| 3 | securedPayload | 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.
Encrypted Signed Payload Data Elements
| Seq. # | Element Name | Element Type | Element Status | Description |
|---|---|---|---|---|
| 1 | clientId | String | Required | Client identifier. This is generated by Paze and shared with the Merchant during onboarding. Maximum length 50 characters. |
| 2 | profileId | String | Required | The Client profile that was used during checkout. Maximum length 50 characters. |
| 3 | token | Object(Token) | Required | A token payload that contains the token number and associated attributes |
| 4 | paymentCardNetwork | Enum | Required | Valid values: - VISA - MASTERCARD - DISCOVER |
| 5 | dynamicData | List(DynamicData) | Required | Dynamic data applicable for a consumer-initiated payment or request to keep a card on file. See Dynamic Data Elements for more information. |
| 6 | 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. |
| 7 | consumer | Object(Consumer) | Required | Information about the consumer who completed the checkout |
| 8 | 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.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | dynamicDataValue | String | Required | The dynamic data value (structure dependent on Card Network). Maximum length 20 characters. |
| 2 | dynamicDataType | Enum | Required | Valid values: - PURCHASE - CARD_ON_FILE Note: CARD_ON_FILE is not supported for Discover. |
| 3 | dynamicDataExpiration | String | Optional | Indicates validity period for the dynamic data. Underlying dynamicDataExpiration value conform UTC time in Unix epoch format. |
Dynamic Data Elements Code Example
dictionary DynamicData {
required String dynamicData;
required Enum dynamicDataType;
optional String dynamicDataExpiration;
}
Consumer Data Elements
The following structure details the Consumer object
| Seq.# | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | firstName | String | Optional | First name of the consumer.Maximum length 100 characters. |
| 2 | lastName | String | Optional | Last name of the consumer.Maximum length 100 characters. |
| 3 | fullName | String | Required | Full name of the consumer.Maximum length 100 characters. |
| 4 | emailAddress | String | Required | Email address of the consumer.Underlying email address value MUST conform to the RFC 5322 address-spec syntax simplified to all lowercase characters. Maximum length 128 characters. |
| 5 | mobileNumber | Object(PhoneNumber) | Optional | Mobile number of the consumerSee Phone Number Data Elements for more information. |
| 6 | countryCode | String | Optional | Consumer provided CountryCode Underlying phone number value countryCode confirm to ISO 3166-1 alpha-2 format, e.g., "US" |
| 7 | 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 Elements
The following structure details the Phone Number object.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | countryCode | String | Required | Phone number’s country code. International Subscriber Dialing (ISD) Codes. For example, “1” for the US.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. |
| 2 | phoneNumber | String | Required | Phone number.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.
Shipping Address Data Elements
| Seq.# | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | name | String | Required | The name of the organization/entity at the address.Maximum length 100 characters. |
| 2 | line1 | String | Required | Line 1 of the address.Maximum length 75 characters. |
| 3 | line2 | String | Optional | Line 2 of the address.Maximum length 75 characters. |
| 4 | line3 | String | Optional | Line 3 of the address.Maximum length 75 characters. |
| 5 | city | String | Required | Name of the city. Maximum length 50 characters. |
| 6 | state | String | Required | Name of the state. Maximum length 30 characters. |
| 7 | zip | String | Required | Zip code for this address. Maximum length 10 characters. |
| 8 | countryCode | String | Required | Country code for this address.ISO 3166-1 alpha-2 country code. |
| 9 | deliveryContactDetails | Object(DeliveryContactDetails) | Optional | Delivery contact details for a shipping addressSee Delivery Contact Details Data Elements for more information. |
Shipping Address 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;
}
Delivery Contact Details Data Elements
The following structure details the DeliveryContactDetails object.
Delivery Contact Details Data Elements
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | contactFullName | String | Optional | Consumer-provided name of the contact person. Maximum length 100 characters. |
| 2 | contactPhoneNumber | Object(Phone Number) | Optional | Consumer-provided phone number of 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;
}
Responses
Where outlined, Paze returns either successful responses or error responses. These responses should be read from the client’s browser and logged to aid in appropriate workflows, error messaging or invetigations during development.
Successful Responses
A successful response means that the Promise is fulfilled. The action relating to the Promise has succeeded.
Error Responses
An error response means that the Promise is rejected. The action relating to the Promise has failed. API errors can be Business Errors or Standard Errors. An error object is passed for every error. The structure of the error is described in the following section.
Standard errors can be returned by any API and should be handled in a common way. Business errors are returned by some APIs only and are described in the Errors section for each API.
Error Structure
This is the Standard Response Structure, which will be returned in case of an error. Use error.reason field to drive error handling logic. Errors are also provided with a human readable error description in the error.message field. This field should be used only to understand the problem.
Error Structure Data Elements
The following structure details the Error Structure object.
| Seq. # | Element Name | Element Type | Element Usage | Description |
|---|---|---|---|---|
| 1 | message | String | Optional | Every error should have a human-readable message describing the error. The message can vary even for the same reason, thus providing additional insights about the problem. This approach should be used along with Merchant bugs to avoid introducing new reasons and still provide enough information to fix the bug. Paze is free to change the message at any time. Merchants should not use this field to drive their business logic or to expose it directly to consumers via UI or other means. |
| 2 | reason | String | Required | Merchants should use this field to drive their error handling business logic. |
| 3 | details | Object | Optional | Array of fields - Data validation errors will use this field to specify which fields failed the validation using location field. |
| 4 | details.location | String | Required | The value of this field is using XPATH expression to point to the field that failed validation. |
| 5 | details.message | String | Optional | The specific error for this field. |
Error Structure Data Elements Code Example
dictionary error {
"message": "Input parameters validation failed.",
"reason": "invalidParameter",
"details":
[/ Optional structure, used with input data validation error
{// Types to specify the fields with errors
"location": "creditCard",
"message": "Should be a numeric value"
}
]
}
Standard Error Reason Codes
These errors can be returned by any API and should be handled consistently in a unified way. Standard Errors are not documented as part of each individual API description.
This table is arranged in a processing order hierarchy. When testing, code that fails will only generate the first error encountered before the entire request is canceled.
Standard Error Reason Codes
| Reason Code | Description and What to Do |
|---|---|
| UNABLE_TO_CONNECT | Unable to connect to APIs. Retry the connection. If retrying fails, present users with a non-Paze checkout. |
| SERVER_ERROR | General server error. Resubmit the request. If retrying fails, present users with a non-Paze checkout. |
| SERVICE_ERROR | An error occurred with an internal Paze service.The APIs will automatically retry. If this error is received, present users with a non-Paze checkout option. |
| AUTH_ERROR | The server cannot authenticate. |
| NOT_FOUND | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. |
| RATE_LIMIT_EXCEEDED | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes.Wait before sending the next request and decrease the rate of sending API requests. Consider implementing Exponential Backoff. In this algorithm, the delay before re-try is defined as: - retryDelay = (2 ^ N) * 1000 + randomDelayMs - retryDelay Retry delay in milliseconds. - N retry count (0, 1, 2, 3, …) - randomDelayMs = random delay in milliseconds (0 .. 1000) |
| INVALID_REQUEST | The submitted request does not exist. |
| MISSING_PARAMETER | A required field is missing. |
| INVALID_PARAMETER | The value provided for one or more request parameters is considered invalid. |
| REQUEST_TIMEOUT | Request timeout |
| UNKNOWN_ERROR | Unknown error |
Error Handling
This section provides a set of guidelines on how to handle API errors for the purpose of simplifying error handling logic and achieving backward compatibility with the newer versions of the APIs. It is assumed that the Merchant follows these guidelines.
- Drive error handling logic based on the value of error.reason field.
- Field error.message is for informational purposes only.
- Paze is free to change this message at any point of time.
- Do not parse this field to drive error handling logic.
- Do not expose this field to the Consumer
- It is assumed that there is a default "catch-all" type of error handling logic. Any errors with codes “INVALID_REQUEST” or “MISSING_PARAMETER” status codes are considered integration errors. Merchants can choose to show a message or simply fail to process this operation.
Support
For support inquiries, contact [email protected].
Sample Code
This sample code is provided solely for reference and is not intended to represent any real consumers or businesses.
Initialize
// Request
({
client: {
id: "mOYSSfG9VQonnTRZ8Zct5h2GnAeNj38lGHQy0xIeCWsrmE1LY",
name: "Orchid Bonanza",
profileId: "orchidBonanzaMain",
externalSubMerchantId: “019718e7 - dbc1 - 74 b5 - 9019 - 032260 d9f074”,
merchantCategoryCode: “0303”,
brandName: “Orchid West”,
statementDescriptor: “PAZE ORCHID 0303 $13 .00”,
url: “ < https: //www.example.com/myapp”}})
//Response>:
{}
CanCheckout
// Request
canCheckout ({
emailAddress: "[email protected]"
})
// Response:
{
"consumerPresent": true
}
Checkout
//Request:
checkout({
emailAddress: "[email protected]",
sessionId: "YSr6zUH6gsAs3riQMhTL",
actionCode: "START_FLOW",
intent: "REVIEW_AND_PAY",
transactionValue: {
transactionCurrencyCode: "USD",
transactionAmount: "73.29"
},
shippingPreference: "ALL",
billingPreference: "ZIP_COUNTRY",
cobrand: {
[
cobrandName: "Orchid Bonanza Optimum",
benefitsOffered: true,
]
},
acceptedShippingCountries: [
"US",
"CA",
"MX"
],
acceptedPaymentCardNetworks: [
"VISA",
"MASTERCARD", “DISCOVER”
],
enhancedTransactionData: {
ecomData: {
cartContainsGiftCard: true,
orderForPickup: true,
orderQuantity: "3",
orderHighestCost: "54.17",
finalShippingAddress: {
name: "George Thompson",
line1: "1234 Main St.",
line2: "Apt. 3A",
city: "Evansville",
state: "Indiana",
zip: "47705",
countryCode: "US"
}
}
})
// Response:
{
"result": "COMPLETE",
"checkoutResponse": "eyJhdWQiOiJmaWxlOlwvXC8iLCJraWQiOi……..sAxxsSgJtrteqa3QadRQ"
}
Complete
//Request:
complete({
sessionId: "YSr6zUH6gsAs3riQMhTL",
transactionType: "BOTH",
transactionOptions: {
merchantCategoryCode: "5193",
billingPreference: "ZIP_COUNTRY",
payloadTypeIndicator: "ID",
},
transactionValue: {
transactionCurrencyCode: "USD",
transactionAmount: "73.29"
},
enhancedTransactionData: {
ecomData: {
cartContainsGiftCard: true,
orderForPickup: true,
orderQuantity: "3",
orderHighestCost: "54.17",
finalShippingAddress: {
name: "George Thompson",
line1: "1234 Main St.",
line2: "Apt. 3A",
city: "Evansville",
state: "Indiana",
zip: "47705",
countryCode: "US"
}
},
processingNetwork: [
"VISA"
]
})
//Response:
{
"completeResponse": "eyJhdWQiOiJmaWxlOlwvXC…..yzt9iIGnde__dSiw4iTvYAJtMqzq8DggFD_URzvdPA"
}
Updated 4 days ago