The Paze℠ API offers Merchants an easy, simple, and convenient way for their consumers to easily provide them with checkout information. A customers Paze wallet contains their credit and debit card information from participating Issuers as well as address information that can be used for shipping.

This document provides the information needed to integrate Paze checkout within a native mobile application.

Prerequisites

To use these APIs, Merchants must establish a relationship with an approved Paze Distributor who will sponsor and onboard the Merchant. Upon onboarding, Merchants will be assigned entity identifiers (such as API keys and profile IDs) and exchange required cryptographic material.

Mobile Integration APIs

/checkout/session/create

This is the API that creates a checkout session for the native mobile application the consumer interacts with when the UI/UX is launched. A successful creation returns a 200 Created message.

This is the API to create a checkout session for the native mobile application to interact with when the UI/UX is launched. A successful creation will return a 200 Created. Refer to the notes on the launching of the UI/UX for the actionCode / Intent mapping.

Security Note: 2-legged OAuth for Authentication. Merchant asserts identity using the access token obtained earlier.

Transaction Input Request Parameters

clientContextString Optional (Max Size 64)

The Merchant-defined transaction identifier, reflected in the response. Referred to as a sessionId in web integration.

The session reference identifier generated by the Merchant. If it is present here, it will be returned in the Checkout response. This is recommended to be identical across the Checkout request and the /checkout/session/complete request.

data Object Required

The container for the request data.

data.client Object Required

Client refers to the Merchant that is integration with Paze.

data.client.id String Required (Max Size 50)

Client identifier. This is generated by Paze and share with the client during onboarding.

data.client.name String Optional (Max Size 50)

Display name associated with the Client to be used for presentation purposes within the user experience.

data.client.profileId String Optional (Max Size 50)

Represents a Client profile to be used during checkout. The client default profile is used when profileId is not provided during this call.

data.sessionId String Required (Max Size 255)

Session reference identifier generated by the Merchant. This must be reused across all the Paze APIs involved during a checkout session.

data.callbackURLScheme String Required (Max Size 20)

This is Merchant application ID.

For iOS it is the bundle identifier
For Android it is the application Id. This is the callback URL to use that returns the consumer to the Merchant mobile app. The Paze UX running in WebView uses this to return the consumer back to the Merchant native mobile app after the consumer exits the Paze UX, either by finishing all of the steps or cancelling out before the last step. On redirect to this schema, the Paze Service appends a query string parameter of status with one of the following values:
- success - the consumer successfully completed the Paze checkout steps, and the Merchant can utilize the other Paze APIs to get data to display or to get the secure payload
- cancelled - the consumer cancelled out of the Paze UX before the last step
- failed - there was some error encountered during the Paze UX flow

data.checkout.Url String Conditional (Max Size 1024)

Session URL for launching the UI/UX from the native mobile application in a webview within the App.

data.emailAddress String Optional (Max Size 128)

Email address as a consumer address. The underlying email address must conform to the RFC 5322 address syntax simplified to all lowercase characters.

data.phoneNumber String Optional (Max Size 10)

Phone number as a consumer identify, such as 15015551212. If neither the phoneNumber or emailAddress is present in the request, the Paze flow prompts the consumer for a lookup key.

data.intentEnum Optional (Max Size 64)

Value values for data.intent are:

REVIEW_AND_PAY (default)
EXPRESS_CHECKOUT
ADD_CARD

Consider the primary intent of the API call when setting this value. For example, a consumer may simultaneously check out and ask to retain the same card on file. In that case, intent should be set to REVIEW_AND_PAY.It is the Merchant’s responsibility to send in the appropriate combinations of intent and other front-end configurations to ensure that the flow is correct for their consumers. Refer to the Paze Merchant Integration Guide for screenshots of each intent.

data.transactionType Enum Optional (Max Size 128)

The type of transaction. Valid values are:

PURCHASE
CARD_ON_FILE
BOTH

data.transactionValue Object Conditional

Currency code and the amount of the transaction.

Note: It is recommended for consumer reference in the case of an immediate intent to pay.

Recommended for consumer reference in the case of an immediate intent to pay. No cart value will be displayed in the Paze UI if this is excluded from the request. Not needed if the consumer is selecting a card to keep on file with Merchant.

Condition: Required if intent is EXPRESS_CHECKOUT. The request is invalid when transactionValue is provided if intent is ADD_CARD.

data.transactionValue.transactionCurrency String Required

Currency code of the transaction in ISO 4217 format. Example: USD

data.transactionValue.transactionAmount String Required

The amount of the transaction. This must include the dollar and cents value in proper format. Digits before and after the decimal point (.) are required including the trailing zeros. Example: 99.95

datashippingPreference Enum Optional (Max Size 32)

Whether Merchant wants to have shipping address collected. Valid values:

ALL (default)
NONE

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

data.billingPreferenace Enum (Max Size 32)

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

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

data.cobrand Array (Max Size 10)

Details for cobranded cards offered by the Merchant.

This field is used to highlight an existing consumer cobrand cards within thePazeUX, if available. If the Merchant has multiple cobranded cards, the list should be ordered from highest to lowest display priority.

data.codbrand[].name Array (Max Size 100)

The product name of the cobrand card. The name of the cobrand card must match exactly with the card name received from the applicable network.

data.acceptedShippingCountries Array of Strings Optional (Array: 10String: 128)

An array of country codes in ISO 3166-1 alpha-2 format as Shipping restrictions. Shipping region country codes limit the selection of eligible shipping addresses. An empty list or the absence of this data element means that all countries are accepted.

data.acceptedPaymentCardNetworks Array of Enum (Array: 2)

An array of payment card networks Valid values are:

VISA
MASTERCARD
DISCOVER

An empty list or the absence of this data element means that all card networks are accepted. This field may be updated with additional enums as the Paze Service onboards other card networks.

ewSID String Required (Max Size 36)

A globally unique identifier generated by the Service Operator.Returned in the response message in response to the initial request. This identifier ties all information about the session together and should be easily accessible by the Merchant staff submitting support requests to theService Operator. The character set is a-f, 0-9, -.

timestampISO8601 String Required (Max Size 64)

The timestamp of the message in ISO 8601 extended combined format. For example: 2015-12-31T17:18Z

This is the time stamp when the response is sent by the Service Operator.

Hidden Source - Remove

Field	Type	Max Size	Description	Field Status
`clientContext`	String	64	Merchant-defined transaction identifier, reflected in response.Referred toas “sessionId” in web integration. Session reference identifier generated by the Merchant. If present here, it will be returned in the Checkout response. This is recommended to be identical across the Checkout request and the /checkout/session/complete request.	O
`data`	Object		Container for the request data	R
`data.client`	Object		Client refers to the Merchant that is integrating with PazeSM	R
`data.client.id`	String	50	Client identifier. This is generated byPazeand shared with client during onboarding.	R
`data.client.name`	String	50	Display name associated with the Client to be used for presentation purposes within the user experience.	O
`data.client.profileId`	String	50	Represents a Client’s profile to be used during checkout.The client’s default profile will be used when profileId is not provided during this call.	O
`data.sessionId`	String	255	Session reference identifier generated by the Merchant. This must bereused across all thePazeAPIs involved during a checkout session.	R
`data.callbackURLScheme`	String	20	This is Merchant application ID. For iOS it is the bundle identifier For Android it is the application Id.It is the callback URL scheme to use to return to the Merchant’s mobile app.This is used by the Paze UX running in the WebView to return the consumer back to the Merchant’s native mobile app after the consumer exits the Paze UX, either after finishing all the steps or canceling out before the last step.On redirect to this schema, the Paze Service will append a query string parameter of "status" with one of the following values: `success` - the consumer successfully completed the Paze checkout steps, and the Merchant can utilize the other Paze APIs to get data to display or to get the secure payload `cancelled` - the consumer cancelled out of the Paze UX before the last step `failed` - there was some error encountered during the Paze UX flow	R
`data.emailAddress`	String	128	Email address as consumer identity. Underlying email address value MUST conform to the RFC 5322 address- spec syntax simplified to all lowercase characters. If emailAddress or phoneNumber are not present in the request, then Paze will prompt the consumer for a lookup key	O
`data.phoneNumbe`r	String	10	Phone Number as consumer identity. Example: ‘17735550100’ If phoneNumber or emailAddress are not present in the request, then thePazeflow will prompt the consumer for a lookup key.	O
`data.intent`	Enum	64	Valid values: REVIEW_AND_PAY (default) EXPRESS_CHECKOUT ADD_CARDConsider the primary intent of the API call when setting this value. For example, a consumer may simultaneously check out and ask to retain the same card on file. In that case, intent should be set to REVIEW_AND_PAY.It is the Merchant’s responsibility to send in the appropriate combinations of intent and other front-end configurations to ensure that the flow is correct for their consumers.Refer to the Paze Merchant Integration Guide for screenshots of each intent.	O
`data.transactionType`	Enum	128	Type of transaction Valid values: PURCHASE CARD_ON_FILE BOTH	O
`data.transactionValue`	Object		Currency code and amount of transaction. Note: Recommended for consumer reference in the case of an immediate intent to pay. No cart value will be displayed in the Paze UI if this is excluded from the request. Not needed if the consumer is selecting a card to keep on file with Merchant. Condition: Required if intent is `EXPRESS_CHECKOUT`. Request will be invalid when transactionValue is provided if intent is `ADD_CARD`.	C
'data.transactionValue. transactionCurrency'	String		Currency code of the transaction ISO 4217 currency code. Example: `USD`	R
`data.transactionValue. transactionAmount`	String		The amount of the transaction. This must include the dollar and cents value in proper format. Digits before and after the decimal point “.” Are required, including trailing zeros. Example: “99.95”	R
`data.shippingPreference`	Enum	32	Whether Merchant wants to have shipping address collected. Valid values: ALL (default) NONE Note: NONE suppresses the address selection/management screens. `shippingPreference`must be set to NONE if intent is `ADD_CARD`.	O
`data.billingPreference`	Enum	32	Verbosity of billing address required by the Merchant. Valid values: ALL (default) ZIP_COUNTRY (scoped for future release) NONE
data.cobrand	Array	10	Details for cobranded cards offered by the Merchant. This field will be used to highlight consumers’ existing cobrand cards within thePazeUX, if available. If the Merchant has multiple cobranded cards, the list should be ordered from highest to lowest display priority.
data.cobrand[].name	String	100	The product name of the cobrand card. This must match exactly with the card name received from the applicable network.
`data.acceptedShippingCountries`	Array of Strings	Array: 10String: 128	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 addresses. An empty list or the absence of this data element means that allcountries are accepted.	O
`data.acceptedPaymentCar dNetworks`	Array of Enum	Array: 2	An array of payment card networks Valid values are: VISA MASTERCARD DISCOVER An empty list or the absence of this data element meansthat all card networks are accepted. This field may beupdated with additional enums as thePazeService onboardsother card networks.

Field	Type	Max Size	Description	Field Status
clientContext	String	64	Merchant-defined transaction identifier, reflected in response.	O
ewSID	String	36	Globally unique identifier generated by the Service Operator.Returned in the response message in response to the initial request.This identifier ties all information about the session together and shouldbe easily accessible by Merchant staff submitting support requests to theService Operatror. Character set: a-f, 0-9, -	R
timestampISO8601	String	24	Timestamp of message in ISO 8601 extended combined format.Format: {YYYY}-{MM)-{DD}T{HH}:{MM}:{SS}Z Example: 2015-12-31T17:18ZTime stamp when response is sent by the Service Operator.	R
data	Object		Container for payload	R
data.checkoutUrl	String	1024	Session URL for launching the UI/UX from the native mobile application in a webview within the App.	C

HTTP Status codes

Status	Notes
200	Successfully created checkout session.
400	Bad Request. Incorrectly formatted request, may be missing id parameter.
401	Unauthorized. Access token missing or no longer valid.

Service Request / Response Example

v1/checkout/session/create
Authorization: Bearer eyJraWQiOiI4ZDlhM2NiMy...
Timestamp: 1594043046
Date: Mon, 06 Jul 2020 13:44:06 GMT
Content-Type: application/json
Content-Length: 1633

{
  "clientContext": "string",
  "data": {
    "client":{	
      "id":"client-merchant-id",
      "name":"Bob's Burgers",
      "profileId":"default"
    },
    "sessionId":"6ef0d1c5-6a97-424a-b9a9-2c0566278aac",
    "callbackURLScheme":"MERCHANT_APP_ID",	
    "intent":"REVIEW_AND_PAY",
    "transactionType":"PURCHASE",
    "transactionValue":{
      "transactionCurrency":"USD",
      "transactionAmount":"23.39"
    },
    "shippingPreference":"ALL",
    "billingPreference":"ALL"
  }
}

200 Created
Server: pazeserver 
Date: Mon, 06 Jul 2020 13:44:07 GMT
Timestamp: 1594043046
Content-Type: application/json
Content-Length: 1633

{
  "clientContext": "string",
  "ewSID": "string-uuid",
  "timestampISO08601": "2021-08-23T21:59:57Z",
  "data": {
      "checkoutUrl": "<https://paze-checkout-session-url>"
  }

/checkout/session/review

The API to retrieve the data related to the card selected by the consumer in the Pazecheckout UX, such as the consumer name, masked card, and shipping address, to display on a confirmation screen, if the Merchant desires to do so.

Security: 2-legged OAuth for Authentication. Merchant asserts identity using the access token obtained earlier.

Transaction Input Request

Request Parameters

Field	Type	Max Size	Description	Field Status
`clientContext`	String	64	Merchant-defined transaction identifier, reflected in response.	O
`data`	Object		Container for the request data.	R
`data.sessionId`	String	255	Session reference identifier generated by the Merchant. This must bethe value sent in the /checkout/session/create call.	R
`data.code`	String	10K	An opaque first party token (“code”) issued and provided by thePazeService to the Merchant in the response from the most recentPazeUX interaction (checkout, change card, or change shipping address).	R

Transaction Output Result

Response Parameters

Field	Type	Max Size	Description	Field Status
clientContext	String	64	Merchant-defined transaction identifier, reflected in response.	O
ewSID	String	36	Globally unique identifier generated by the Service Operator.Returned in the response message in response to the initial request.This identifier ties all information about the session together and shouldbe easily accessible by Merchant staff submitting support requests to the Service Operator.Character set: a-f, 0-9, -	R
timestampISO8601	String	24	Timestamp of message in ISO 8601 extended combinedformat. Format: {YYYY}-{MM{DD}T{HH}:{MM}:{SS}Z Example: 2015-12-31T17:18Z The time stamp when the response is sent by the Service Operator	R
data	Object		Container for payload	R
data.code	String	10K	An opaque first party token (“code”) issued and provided by thePazeService to the Merchant in the response from the most recent Paze API interaction.	R
data.consumer	Object		Details associated with the authenticated consumer.	R
data.consumer.firstName	String	50	First name of the consumer	O
data.consumer.lastName	String	50	Last name of the consumer	O
data.consumer.fullName	String	100	The full name of the consumer	R
data.consumer.countryCode	String	2	ISO 3166-1 alpha-2 country code.	O
data.consumer.languageCode	String	2	Language associated with this wallet. ISO 639-1 code.	O
data.consumer.emailAddress	String	128	Email address of the consumer	R
data.consumer.mobileNumber	Object		Mobile number of the consumer	R
data.consumer.mobileNumber. countryCode	String	4	Country code as defined by the International TelecommunicationUnion (ITU)	R
data.consumer.mobileNumber. phoneNumber	String	64	Phone number string without contry code.	R
data.shippingAddress	Object		The selected shipping address.Condition: Returned only when shippingPreference is ALL.	C
data.shippingAddress.line1	String	50	Line 1 of the address	R
data.shippingAddress.line2	String	50	Line 2 of the address (if applicable)	C
data.shippingAddress.line3	String	50	Line 3 of the address (if applicable)	C
data.shippingAddress.city	String	128	Shipping city	R
data.shippingAddress.state	String	2	Shipping State/Region	R
data.shippingAddress.zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.shippingAddress.country Code	String	2	ISO-3166-1 alpha-2 standard code.	R
data.shippingAddress.deliver yContactDetails	Object		Delivery contact details for a shipping address	O
data.shippingAddress.deliver yContactDetails.contactFullN ame	String	100	Consumer-provided name of the contact person	O
data.shippingAddress.deliver yContactDetails.contactPhone Number	Object		Consumer-provided phone number of the contact person	O
data.shippingAddress.deliver yContactDetails.contactPhone Number.countryCode	String	4	International Subscriber Dialing (ISD) Codes.	R
data.shippingAddress.deliver yContactDetails.contactPhone Number.phoneNumber	String	10	Phone number	R
data.maskedCard	Object		Masked card details of the selected card.	R
data.maskedCard.panLastFour	String	4	Last four digits of PAN from card	R
data.maskedCard.paymentAccou ntReference	String	29	Payment Account Reference (PAR). A non-financial referenceassigned to each unique PAN and used to link a payment accountrepresented by that PAN to affiliated Payment Tokens	R
data.maskedCard.panExpiratio nMonth	String	2	2-digit Primary Account Number (PAN) expiration month. Condition: Required if card supports expiry	C
data.maskedCard.panExpiratio nYear	String	4	4-digit PAN expiration year.Condition: Required if card supports expiry	C
data.maskedCard.paymentCardD escriptor	String	32	A free-form string (max of 32 characters used for card/programrecognition. Example ‘Travel Rewards’, ‘Cashback Rewards’ etc.	R
data.maskedCard.digitalCardD	Object		Digital Card Art.	R
data.maskedCard.digitalCardD ata.artUri	String	1024	URI that hosts the Card Art image to be used for presentationpurposes.	R
data.maskedCard.digitalCardD ata.artHeight	Integer		Height of art card image, in pixels.	R
data.maskedCard.digitalCardD ata.artWidth	Integer		Width of art card image, in pixels.	R
data.maskedCard.billingAddre ss	Object		Object of billing address objects for this wallet. Condition: Returned if billingPreference is ALL	R
data.maskedCard.billingAddre ss.name	String	100	Name of the organization/entity at the address	O
data.maskedCard.billingAddre ss.line1	String	50	Line 1 of the address	R
data.maskedCard.billingAddre ss.line2	String	50	Second line of street address (if applicable)	O
data.maskedCard.billingAddre ss.line3	String	50	Third line of street address (if applicable)	O
data.maskedCard.billingAddre ss.city	String	128	Name of the city	R
data.maskedCard.billingAddre ss.state	String	2	Name of the state	R
data.maskedCard.billingAddre ss.zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.maskedCard.billingAddre ss.countryCode	String	2	ISO-3166-1 alpha-2 standard code.	R
data.maskedCard.paymentCardT ype	Enum	32	Valid values : CREDIT DEBIT	R
data.maskedCard.paymentCardB rand	Enum	32	Valid values : - VISA - MASTERCARD DISCOVER	R
data.maskedCard.paymentCardN etwork	Enum	32	Valid values : VISA MASTERCARD DISCOVER	R
data.links	Map<Stri ng, String>		This field contains follow-up links for changing the address and card ifthe Merchant provides those functions to their user.Valid Map Keys are : CHANGE_CARD CHANGE_SHIPPING_ADDRESSExample :links : {"CHANGE_CARD" : "https://checkout.paze.com/…","CHANGE_SHIPPING_ADDRESS" : "https://checkout.paze.com/…"}

HTTP Status codes

Status	Notes
200	Successfully located at least one wallet for the provided wallet ID.
400	Bad Request. Incorrectly formatted request, may be missing id parameter.
401	Unauthorized. Access token missing or no longer valid.
404	Not Found. Supplied wallet ID does not have a wallet registered with the Service Operator.

Service Request / Response Example

POST v1/checkout/session/review
Authorization: Bearer eyJraWQiOiI4ZDlhM2NiMy...
Timestamp: 1594043046
Date: Mon, 06 Jul 2020 13:44:06 GMT
Content-Type: application/json
Content-Length: 1633

{
  "clientContext": "string",
  "data": {
    "sessionId":"<merch-generated>",
    "code":"<...>"
  }
}


200 OK
Server: pazeserver 
Date: Mon, 06 Jul 2020 13:44:07 GMT
Timestamp: 1594043046
Content-Type: application/json
Content-Length: 1633

{
  "clientContext": "string",
  "ewSID":"session-id-generated-by-paze",
  "timestampISO08601": "2021-08-23T21:59:57Z",
  "consumer": {
    "firstName":"Dylan",
    "lastName":"McKay",
    "fullName":"Dylan McKay",
    "emailAddress":"dylan.mckay@example.com",
    "mobileNumber": {
      "countryCode":"1",
      "phoneNumber":"7735550100"
    }
    "countryCode":"US",
    "landuageCode":"en_US"
  },
  "maskedCard": {
    "panLastFour":"1234",
    "paymentAccountReference":"unique-str-across-tokens-for-card",
    "tokenExpirationMonth":"01",
    "tokenExpirationDay":"01",
    "paymentCardDescriptor":"Cash Rewards",
    "paymentCardType":"CREDIT",
    "paymentCardBrand":"VISA",
    "paymentCardNetwork":"VISA"
  },
  "shippingAddress": {
    "name":"Dylan McKay",
    "line1":"",
    "line2":"",
    "line3":"",
    "city":"Beverly Hills",
    "state":"CA",
    "zip":"90210",
    "countryCode":"US",
    "deliveryContactDetails": {
      "contactFullName":"Brenda ",
      "contactPhoneNumber":{
        "countryCode":"1",
        "phoneNumber":"7735552300"	
      },
  "links":{
      "change_card":<url>,
        "change_shipping_address": <url>
      }
    }
  }
}

/checkout/session/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 Merchant and consumer sessions have timed out without receiving a valid input, Complete should not be invoked. If it is invoked, Merchants will receive a 404 Not Found 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 will need to behandled differently between PURCHASE and CARD_ON_FILE use cases.
Discover does not support card-on-file functionality. Only PURCHASE is supported forDiscover cards.

Security: 2-legged OAuth for Authentication. Merchant asserts identity using the access token obtained earlier.

Transaction Input Request

Request Parameters

Field	Type	Max Size	Description	Field Statu s
clientContext	String	64	Merchant-defined transaction identifier, reflected in response. Should be the same value as presented in the /checkout/session/create	O
data	Object		Container for the request data	R
data.sessionId	String	255	Session reference identifier generated by the Merchant. This mustbe the value sent in the /checkout/session/create call.	R
data.code	String	10K	An opaque first party token (“code”) issued and provided by thePazeService to the Merchant in the response from the most recentPazeAPI OR UX interaction (checkout, change card orchange shipping address).	R
data.transactionType	Enum	128	Type of transaction Valid values: PURCHASE CARD_ON_FILE BOTHNOTE: When a Discover card is selected in the checkoutflow 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.	R
data.transactionOptions	Object		Client configuration data that can override any configuration that was created during Merchant onboarding or in the Checkout request	O
data.transactionOptions. merchantCategoryCode	String		Merchant Category Code (MCC) of the Merchant	O
data.transactionOptions. billingPreference	String	32	Verbosity of billing address required by the Merchant. Valid values: ALL (default) ZIP_COUNTRY (scoped for future release) NONE	O
data.transactionOptions. payloadTypeIndicator	Enum		The verbosity of payload requested. Valid values: ID – Returns payloadId only (default) PAYMENT – Returns payloadId and securedPayload	O
data.transactionValue	Object		Currency code and amount of transaction. Condition: Required if transactionType is PURCHASE or BOTH.	C
data.transactionValue. transactionCurrency	String		Currency code of the transaction.Example: ‘USD’	R
data.transactionValue. transactionAmount	String		The amount of the transaction. Must include dollar and cents value inproper format. Digits before and after the decimal point “.” Are required, including trailing zerosExample: “99.95”	R
data.enhancedTransactionData. ecomData	Object		Details pertaining to electronic commerce purchases	O
data.enhancedTransactionData. ecomData.cartContainsGiftCard	Boolean		Whether current transaction includes a gift card purchase.	O
data.enhancedTransactionData. ecomData.orderForPickup	Boolean		Whether consumer order will be picked up rather than shipped.	O
data.enhancedTransactionData. ecomData.orderQuantity	String	32	Number of items ordered.	O
data.enhancedTransactionData. ecomData.orderHighestCost	String	32	Dollar value of most expensive item ordered.	O
data.enhancedTransactionData. ecomData.finalShippingAddress	Object		Destination of items ordered. Recommended for use if the Merchant does not intend to usePazefor shipping address collection.	O
data.enhancedTransactionData. ecomData.finalShippingAddress.name	String	100	Name of the organization/entity at the address	R
data.enhancedTransactionData. ecomData.finalShippingAddress.line1	String	50	Line 1 of the address	R
data.enhancedTransactionData. ecomData.finalShippingAddress.line2	String	50	Line 2 of the address	O
data.enhancedTransactionData. ecomData.finalShippingAddress.line3	String	50	Line 3 of the address	O
data.enhancedTransactionData. ecomData.finalShippingAddress.city	String	128	Shipping city	R
data.enhancedTransactionData. ecomData.finalShippingAddress.state	String	2	Shipping State/Region	R
data.enhancedTransactionData. ecomData.finalShippingAddress.zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.enhancedTransactionData. ecomData.finalShippingAddress. countryCode	String	2	ISO-3166-1 alpha-2 standard code.	R
data.enhancedTransactionData. ecomData.final ShippingAddress.deliveryContactDetails	Object		Delivery contact details for a shipping address	O
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery ContactDetails.conta ctFullName	String	100	Consumer-provided name of the contact person	O
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery ContactDetails.conta ctPhoneNumber	Object		Consumer-provided phone number of the contact person	O
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery ContactDetails.conta ct PhoneNumber.countryCode	String	4	International Subscriber Dialing (ISD) Codes.	R
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery ContactDetails. contactPhoneNumber.phoneNumber	String	10	Phone number	R
data.enhancedTransactionData. travelData	Object		Details pertaining to travel bookings.	O
data.enhancedTransactionData. travelData.passengerName	String	100	Traveler name.	O
data.enhancedTransactionData. travelData.roundTrip	Boolean		Whether departure and return trips are being purchased in the same transaction.	O
data.enhancedTransactionData. travelData.departureDate	String	20	Date and time of departure in ISO 8601 format.	O
data.enhancedTransactionData. travelData.returnDate	String	20	Date and time of return in ISO 8601 format.	O
data.enhancedTransactionData. travelData.departureLocation	Object		Location from which the traveler is departing.	O
data.enhancedTransactionData. travelData.departureLocation. name	String	100	Name of the organization/entity at the address	O
data.enhancedTransactionData. travelData.departureLocation. line1	String	50	Line 1 of the address	R
data.enhancedTransactionData. travelData.departureLocation. line2	String	50	Line 2 of the address	O
data.enhancedTransactionData. travelData.departureLocation. line3	String	50	Line 3 of the address	O
data.enhancedTransactionData. travelData.departureLocation. city	String	128	Shipping city	R
data.enhancedTransactionData. travelData.departureLocation. state	String	2	Shipping State/Region	R
data.enhancedTransactionData. travelData.departureLocation. zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.enhancedTransactionData. travelData.departureLocation. countryCode	String	2	ISO-3166-1 alpha-2 standard code.	R
data.enhancedTransactionData. travelData.returnLocation	Object		Location from which the traveler is returning.	O
data.enhancedTransactionData. travelData.returnLocation.nam e	String	100	Name of the organization/entity at the address	O
data.enhancedTransactionData. travelData.returnLocation.lin e1	String	50	Line 1 of the address	R
data.enhancedTransactionData. travelData.returnLocation.lin e2	String	50	Line 2 of the address	O
data.enhancedTransactionData. travelData.returnLocation.lin e3	String	50	Line 3 of the address	O
data.enhancedTransactionData. travelData.returnLocation.cit y	String	128	Shipping city	R
data.enhancedTransactionData. travelData.returnLocation.sta te	String	2	Shipping State/Region	R
data.enhancedTransactionData. travelData.returnLocation.zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.enhancedTransactionData. travelData.returnLocation.cou ntryCode	String	2	ISO-3166-1 alpha-2 standard code.	R
data.processingNetwork	Enum		If not provided, will default to card network on front of card.	O

Transaction Output Result

Response Parameters

Field	Type	Max Size	Description	Field Status
clientContext	String	64	Merchant-defined transaction identifier, reflected in response.	O
ewSID	String	36	Globally unique identifier generated by the Service Operator.Returned in the response message in response to the initialrequest. This identifier ties all information about the sessiontogether and should be easily accessible by Merchant staff submitting support requests to the Service Operator.Character set: a-f, 0-9, -	R
timestampISO8601	String	24	Timestamp of message in ISO 8601 extended combined format.Format: {YYYY}-{MM){DD}T{HH}:{MM}:{SS}Z Example: 2015-12- 31T17:18ZTime stamp when response is sent by the Service Operator	R
data	Object		Container for payload	R
data.payloadId	String	50	This is the unique identifier generated by thePazeService. This will be used as the wallet transaction identifier assigned by the Pazesystem for this particular transaction.Maximum length 50 characters	R
data.shippingAddress	Object		The selected shipping address. Condition: Returned only when the shippingPreference is ALL.	C
data.shippingAddress.li ne1	String	50	Line 1 of the address	R
data.shippingAddress.li ne2	String	50	Line 2 of the address (if applicable)	C
data.shippingAddress.li ne3	String	50	Line 3 of the address (if applicable)	C
data.shippingAddress.city	String	128	Shipping city	R
data.shippingAddress.state	String	2	Shipping State/Region	R
data.shippingAddress.zip	String	10	Postal Code (5 digit or ZIP+4 format)	R
data.shippingAddress.countryCode	String	2	ISO-3166-1 alpha-2 standard code.	R
data.shippingAddress.delivery ContactDetails	Object		Delivery contact details for a shipping address	O
data.shippingAddress.delivery ContactDetails.contactFullName	String	100	Consumer-provided name of the contact person	O
data.shippingAddress.delivery ContactDetails.contactPhoneNumber	Object		Consumer-provided phone number of the contact person	O
data.shippingAddress.deliveryContactDetails. contactPhoneNumber.countryCode	String	4	International Subscriber Dialing (ISD) Codes.	R
data.shippingAddress.deliveryContactDetails. contactPhoneNumber.phoneNumber	String	10	Phone number	R
data.securePayload	String		Information necessary to process the payment. This field holds the signed and encrypted payload, which once decrypted will contain the structure that follows. Condition: Returned when transactionOptions.payloadTypeIndicator is PAYMENT	C

Secure Payload Data Elements

This section details the structure of the secure payload that is returned in the complete response.

Field	Type	Max Size	Description	Field Status
clientId	String		Client identifier. This is generated by thePazeService and shared with the Merchant during onboarding	R
profileId	String		The Client profile that was used during checkout	R
token	Object		A token payload that contains the token number and associated attributes	R
token.paymentToken	String		This is the payment instrument.	R
token.paymentAccountRef erence	String	29	Payment Account Reference (PAR). A non-financial referenceassigned to each unique PAN and used to link a payment accountrepresented by that PAN to affiliated Payment Tokens	R
token.tokenExpirationMo nth	String	2	MM	R
token.tokenExpirationYe ar	String	4	YYYY	R
paymentCardNetwork	Enum	32	Valid values: VISA MASTERCARD - DISCOVER	R
dynamicData	Array		Dynamic data applicable for a consumer-initiated payment or request to keep a card on file.	R
dynamicData.dynamicData Value	String		The dynamic data value (structure dependent on Card Network)	R
dynamicData.dynamicData Type	Enum		Valid values PURCHASE CARD_ON_FILE	R
dynamicData.dynamicData Expiration	String		Indicates validity period for the dynamic Data	O
billingAddress	Object		Billing address of the card selected, at the verbosity indicated by transactionOptions.billingPreference. If transactionOptions.billingPreference is ZIP_COUNTRY, otherAddress data elements will not be returned. Condition: Provided when transactionOptions.billingPreference is not set to NONE.	C
billingAddress.line1	String	50	Street address for wallet	R
billingAddress.line2	String	50	Second line of street address (if applicable)	C
billingAddress.line3	String	50	Second line of street address (if applicable)	C
billingAddress.city	String	128	Shipping city	R
billingAddress.state	String	2	Shipping State/Region	C
billingAddress.zip	String	10	Postal Code (5 digit or ZIP+4 format)	C
billingAddress.countryC ode	String	2	ISO-3166-1 alpha-2 standard code.	C
consumer	Object		Information about the consumer who completed the checkout.	R
consumer.firstName	String	50	First name of the consumer	R
consumer.lastName	String	50	Last name of the consumer	R
consumer.fullName	String	100	The full name of the cnsumer	O
consumer.countryCode	String	2	ISO 3166-1 alpha-2 country code.	R
consumer.languageCode	String	2	Language associated with this wallet. ISO 639-1 code.	O
consumer.emailAddress	String	128	Email address of the consumer	R
consumer.mobileNumber	Object		Object Phone number used in SMS OTP for this wallet. Pre-first time use: 000000XXXXPost first time use: AAANNNXXXX	R
consumer.mobileNumber.c ountryCode	String	3	Country code as defined by the International TelecommunicationUnion (ITU)	R
consumer.mobileNumber.p honeNumber	String	12	Phone number string without country code.	R
eci	String		Electronic Commerce Indicator. Code indicating a transaction’s levelofadherence to 3D Secure (3DS) authentication standardsCondition: Provided when the Merchant submitted a transactionfor PURCHASE or BOTH.	C

HTTP Status codes

Status	Notes
200	Successfully located at least one wallet for the provided wallet ID.
400	Bad Request. Incorrectly formatted request, may be missing id parameter.
401	Unauthorized. Access token missing or no longer valid.
404	Not Found. Supplied wallet ID does not have a wallet registered with the Service Operator.

Service Request / Response Example

POST v1/checkout/session/complete
Authorization: Bearer eyJraWQiOiI4ZDlhM2NiMy...
Timestamp: 1594043046
Date: Mon, 06 Jul 2020 13:44:06 GMT
Content-Type: application/json
Content-Length: 1633

{
  "clientContext": "client-context-from-create-call",
  "data": {
    "transactionType":"PURCHASE", 
    "sessionId":"string",
    "code":"<...>"
    "transactionType":"PURCHASE",
    "transactionOptions":{
      "merchantCategoryCode":"mcc-of-merchant",
      "billingPreference":"ALL",					
      "payloadTypeIndicator":"ID"
    },
    "transactionValue":{
      "transactionCurrency":"USD",
      "transactionAmount":"23.39"
    },
    "enhancedTransactionData":{
      "ecomData":{
        "cartContainsGiftCard":false,
        "orderForPickup":false,
        "orderQuantity":"1",
        "orderHighestCost":"23.39", 
        "finalShippingAddress":{}
      },
      "travelData":{
        "passengerName":"Joe Cool",
        "roundTrip":true, 
        "departureDate":"2020-07-10 15:00:00.000",
        "returnDate":"2020-07-11 15:00:00.000",
        "departureLocation":{},
        "returnLocation":{ //Address object }
      }
    }
  }
}


200 OK
Server: pazeserver 
Date: Mon, 06 Jul 2020 13:44:07 GMT
Timestamp: 1594043046
Content-Type: application/json
Content-Length: 1633

{
  "ewSID": "string",
  "clientContext":"client-context-from-initialize",
  "timestampISO08601": "2021-08-23T21:59:57Z",
  "data":{
    "payloadId":"paze-generated-uuid",
    "shippingAddress":{
      "line1":"",
      "line2":"",
      "line3":"",
      "city":"Beverly Hills",
      "state":"CA",
      "zip":"90210",
      "countryCode":"US",
      "deliveryContactDetails":{
        "contactFullName":"Brenda Walsh",
        "contactPhoneNumber":{ 
          "countryCode":"1",
          "phoneNumber":"7735552300"	
        }
      }
    },
    "securePayload":{    // structure after decryption
      "clientId":"client-merchant-id",
      "profileId":"default"
      "token":{
	"paymentToken":"tokenized-payment-instrument",
	"tokenExpirationMonth":"01",
	"tokenExpirationYear":"2024",
	"paymentAccountReference":"par-linked-to-tokens-PAN"
      },
      "paymentCardNetwork":"VISA",
      "dynamicData":[
        {
          "dynamicDataValue":"dynamic-value",
          "dynamicDataType":"PURCHASE",
          "dynamicDataExpiration":"need-format-exp-date-string"
	}
      ],
      "billingAddress":{
        "name":"Dylan McKay",
        "line1":"",
        "line2":"",
        "line3":"",
        "city":"Beverly Hills",
        "state":"CA",
	"zip":"90210",
	"countryCode":"US"
      },
      "consumer":{
        "firstName":"Robert",
        "lastName":"Dylan",
        "fullName":"Dylan McKay",
        "emailAddress":"bob.dylan@example.com",
        "mobileNumber":{
          "countryCode":"1",
          "phoneNumber":"7735550100"
        }
	"countryCode":"US",
	"landuageCode":"en_US"
      },
      "eci":"electronic-commerce-indicator-3ds-std"
    }
  }
}

Handle the Callback

public class PazeCallbackActivity extends AppCompatActivity {

    /* This is the same callbackURLScheme which is passed in   
    createCheckoutSession; generally it is app’s applicationId (like – 
    com.domain.appName )*/
    private static final String CALLBACK_SCHEME_PAZE = "com.domain.app_name";

    @Override
    protected void onCreate(Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        Uri uri = getIntent().getData();
        if (uri != null && uri.getScheme().equals(CALLBACK_SCHEME_PAZE)) {
            // Process 'status' and 'response' parameters and proceed accordingly
        }
        finish();
    }

}

API 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 value to a pre-defined list of values. 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, these rules mean:

Ignore any unknown fields received as part of API responses.
Code to deal with unknown values received as part of API responses in a graceful manner.
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.

We consider “additive” changes or changes to field values already flagged as having the potential to change, non-breaking.

“Reductive” changes; removing fields, end points, payload entries or changes to fields that were not noted as having a potential to change are all considered breaking changes.

Support

For support inquiries, contact support@paze.com.

Appendix A

Service Operator Environments and Service URLs

All Merchants must comply with the following rules when using the environments:

• Perform a DNS lookup before each request to thePazeService

• Observe time-to-live (TTL) values

• Donotcachelookups

• Do not statically map domains to IP addresses

• DonotcacheSSLconnections

CAT Environment

The Service Operator uses the Consumer Acceptance Testing (CAT) environment to perform system testing, end-user acceptance testing, and regression testing. The Service Operator certifies applications here before deployment to production. TheMerchant must make application, system, and SSL certificate changes to use thisenvironment.

CAT URL Type	CAT URL
Session Request URL	`<https://auth.wallet.cat.earlywarning.io>`
Mutually Authenticated Session Request URL	`<https://mtls.auth.wallet.cat.earlywarning.io>`
Resource URL	`<https://mobile.wallet.cat.earlywarning.io>`

Production Environment

The Service Operator uses the production environment for live Consumer traffic and employs multiple service centers to manage global traffic at the DNS lookup level. Since the lookup result for the session request URL returns dynamic IP addresses, do not code forstatic IP addresses as these are subject to change without notice and could cause unintended service interruptions.

Prod URL Type	Prod URL
Session Request URL	`<https://auth.paze.com>`
Mutually Authenticated Session Request URL	`<https://mtls.auth.paze.com>`
Resource URL	`<https://api.paze.com>`