Merchant Mobile Application API Technical
Introduction
The Paze Service from Early Warning Services LLC, (the “Service Operator”), offers Merchants a simple and convenient way for their consumers to easily provide them with checkout information. A consumer’s Paze wallet contains their credit and debit card information from participating Issuers as well as address information that can be used for shipping.
This Paze Merchant Mobile Application API Technical Requirements, document provides the information needed to integrate Paze checkout within a native mobile application.
For web-based integrations, please refer to the Paze Merchant JavaScript SDK Technical Requirements.
Integration Steps
The following steps are involved in integrating Paze checkout to a native mobile application:
Call Paze /token API: Authentication endpoint to retrieve an OAuth access token that is used for the following API endpoints. The details for this API are documented in the_Paze Platform_API_OAuth_Acces_User Guide Version_1.3_.
Note: The Merchant needs to obtain a separate Paze OAuth access/bearer token per checkout session. Merchants should not attempt to reuse a Paze OAuth token across multiple checkout sessions as doing do will result in an error.
Call /checkout/session/create API: This API is used to create the Paze checkout session. Calling Create creates a checkout session and a Paze Checkout URL is returned in the response.
For checkout flow optimization, the Merchant can include any available consumer email address or mobile number in the Create call. The Paze Service will utilize that information to optimize the checkout flow when possible, such as not showing the email/phone entryscreen if a wallet has been located.
- If neither an email nor mobile number is provided or if the provided email or mobile number doesn’t match a wallet. Paze checkout will prompt the consumer for the necessary information to locate their wallet.
Launch the Paze checkout UX (user experience) for card, and possibly shipping address, selection: If the consumer taps the Paze button (or related action), the Merchant launches the Paze checkout URL from the previous step, using the appropriate UX control.
The resultant UX will run the complete Paze consumer-facing checkout flow (including lookup, authentication of consumer, consumer information selection, etc.) and will return information to indicate whether the checkout flow was successfully completed, the user did not complete the checkout flow, or there was some other error, such as a query parameter via the callback URL scheme. If the checkout flow was successfully completed, minimal masked card information and a code is also returned to the Merchant. The Merchant needs to pass that code back to the Paze Service in any subsequent API call.
[Optional] Call /checkout/session/review API: Returns a summary of the consumer's card and shipping address for display on confirmation screen, if one is presented to the consumer.
[Optional] Re-Launch the Paze checkout UX to allow user to change card or shipping address: If the Merchant provides options to the user to change their selected card and/or shipping address, and the consumer taps one of those options, the Merchant needs to launch the Paze UX again, but this time using the appropriate URL returned in a prior response payload in the appropriate UX control as appropriate UX control as specified later.
The resultant UX will run the appropriate consumer-facing change card or change shipping address flow and return information to indicate if the flow was successfully completed, or if the user did not complete the flow, or there was some other failure, as a query parameter via the callback URL scheme. If the flow was successfully completed, a code is also returned to the Merchant. The Merchant needs to pass that code back to the Paze Service in any subsequent API call, such as the /checkout/session/reviewAPI to retrieve the updated information or to /checkout/session/complete API to close the checkout session.
Call /checkout/session/complete API: Closes the Merchant and consumer sessions, and provides payment details required to successfully process the Payment Transaction, including whether the consumer to make a payment immediately, put a card on file with the Merchant, or both. The Merchant can decide to just close the checkout session but not receivethe secure payload via this call and instead retrieve the secure payload via the Get Payload API documented in thePaze_Merchant Business to Business APIs TechnicalRequirements_ guide. The secure payload includes the payment token, cryptogram, expiry date, etc., that can then be used to get a payment authorization from the card network, toswap and to put on file with the Merchant, or both.
Note: /checkout/session/complete must still be called to close the session even if the B2B API is being used to retrieve the secure payload.
Prerequisites
To use these APIs, Merchants must establish a relationship with an approved Paze Distributor that 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.
Common Definitions
Field Status
The field status column of the following tables uses letters to signify required, optional, or conditional characteristics of the parameter:
- R - Required: The request requires a value for this parameter.
- O - Optional: The request does not require a value for this parameter, but inclusion of the parameter in the request may change script behavior. See the Definition / Description column formore information.
- C - Conditional: The request requires a value for this parameter in specific circumstances. See the Definition / Description column for more information.
API Errors
API errors are reported using a standard error response structure. Logically, all errors are categorized into standard errors and business errors. Standard errors can be returned by any API and should be handled in a common way. Business errors are returned by only some APIs and are described in the errors section for each API.
Standard Error Response Structure
Unless noted elsewhere, the standard response structure (shown below) will be returned in case of an error. Use the reason field to drive your error handling logic. Errors are also provided with a human- readable description in the message field. This field should be used only to understand the problem. In rare cases, depending on the type of error, this error structure might not be returned and you should rely on the HTTP status code semantics.
| 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 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: Time stamp when response is sent by the Service Operator. | R |
error | Object | Container for the error details. | R | |
error.reason | String | 64 | Reason for the error. Use this field to drive our error handling business logic. | R |
error.message | String | 1024 | Free form text message describing the error condition. Do not show this message to the end user. Do not use this field to drive error handling logic. Use the reason field instead. The server can change this message at any point in time. | R |
error.details | Array | Array of fields, which failed validation. Populated if there are field level error details. | ||
error.details[].reason | String | 128 | Error reason | C |
error.details[].source | String | 128 | The value of this field is using XPATH expression to point to the field that failed validation. | C |
error.details[].message | String | 256 | The specific error for this field. |
//Example:
400 Bad Request
Server: pazeserver
Date: Mon, 06 Jul 2020 13: 44: 07 GMT
Timestamp: 1594043046
Content - Type: application/json
Content - Length: 1633
{
"clientContext": "clientContextString",
"ewSID": "string",
"timestampISO08601": "2021-08-23T21:59:57Z",
"error": {
"reason": "INVALID\_ARGUMENT",
"message": "Missing or invalid value specified in request.",
"details": [
{
"reason": "INVALID\_VALUE",
"source": "expirationMonth",
"message": "Should be a numeric value"
}
]
}
}Standard Errors
Standard errors can be returned by any API and should be handled consistently in a unified way. These errors may not be documented as part of each individual API description.
| HTTP StatusCode | Reason | Description |
|---|---|---|
400 | INVALID_ARGUMENT | The value provided for one or more request parameters is considered invalid.
|
400 | INVALID_REQUEST | The API server could not understand the request.This sometimes occurs when a data field is not in the appropriate/particular format. For example:
|
401 | AUTH_ERROR | Unauthorized, see error object for details, e.g., API credentials do not match, or authorization token validation failure |
403 | FORBIDDEN | Forbidden, see error object for details, e.g., invalid client identity (origin) |
422 | As provided by the TSP | The error occurred at the TSP (Token Service Provider) while processing the provisioning request. The error structure will provide the details as provided by the TSP. |
429 | TOO_MANY_REQUESTS | The requestor is exceeding the concurrent request limit. |
500 | SERVICE_ERROR | Internal server error, see error object for details |
Mobile Integration APIs
/checkout/session/create
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
Request Parameters
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| 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 |
| Object | Container for the request data | R | |
| Object | Client refers to the Merchant that is integrating with PazeSM | R | |
| String | 50 | Client identifier. This is generated byPazeand shared with client during onboarding. | R |
| String | 50 | Display name associated with the Client to be used for presentation purposes within the user experience. | O |
| 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 |
| String | 255 | Session reference identifier generated by the Merchant. This must bereused across all thePazeAPIs involved during a checkout session. | R |
| String | 20 | This is Merchant application ID.
| R |
| 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 |
| 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 |
| Enum | 64 | Valid values:
| O |
| Enum | 128 | Type of transaction Valid values:
| O |
| 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 | C | |
'data.transactionValue. | String | Currency code of the transaction ISO 4217 currency code. Example: | R | |
| 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 | |
| Enum | 32 | Whether Merchant wants to have shipping address collected. Valid values:
| O |
| Enum | 32 | Verbosity of billing address required by the Merchant.
| |
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. | |
| 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 |
| Array of Enum | Array: 2 | An array of payment card networks Valid values are:
|
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 theService Operatror. Character set: a-f, 0-9, - | R |
timestampISO8601 | String | 24 | Timestamp of message in ISO 8601 extended combined format.Format: | 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: 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 :
| R |
data.maskedCard.paymentCardB rand | Enum | 32 | Valid values :
| R |
data.maskedCard.paymentCardN etwork | Enum | 32 | Valid values :
| 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 :
| ||
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":"[email protected]",
"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
| 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. | String | 32 | Verbosity of billing address required by the Merchant. Valid values:
| O |
data.transactionOptions. payloadTypeIndicator | Enum | The verbosity of payload requested. Valid values:
| O | |
data.transactionValue | Object | Currency code and amount of transaction. | C | |
data.transactionValue. | String | Currency code of the transaction.Example: ‘USD’ | R | |
data.transactionValue. | 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. | 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. | String | 2 | ISO-3166-1 alpha-2 standard code. | R |
data.enhancedTransactionData. ecomData.final | Object | Delivery contact details for a shipping address | O | |
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery | String | 100 | Consumer-provided name of the contact person | O |
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery | Object | Consumer-provided phone number of the contact person | O | |
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery | String | 4 | International Subscriber Dialing (ISD) Codes. | R |
data.enhancedTransactionData. ecomData.finalShippingAddress.delivery | 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: 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 | Object | Delivery contact details for a shipping address | O | |
data.shippingAddress.delivery | String | 100 | Consumer-provided name of the contact person | O |
data.shippingAddress.delivery | Object | Consumer-provided phone number of the contact person | O | |
data.shippingAddress.deliveryContactDetails. | String | 4 | International Subscriber Dialing (ISD) Codes. | R |
data.shippingAddress.deliveryContactDetails. | 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:
| 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
| 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":"[email protected]",
"mobileNumber":{
"countryCode":"1",
"phoneNumber":"7735550100"
}
"countryCode":"US",
"landuageCode":"en_US"
},
"eci":"electronic-commerce-indicator-3ds-std"
}
}
}
Mobile Client UX Integration
This section describes how to launch the UI/UX from a mobile application and return to the mobile application.
Once the mobile app receives thePazecheckout URL from the /checkout/session/create API call, and the consumer taps the Paze button (or related action), the mobile app needs to open the Paze checkout URL in the specific WebView control for the given mobile operating system. The WebViews will maintain state between multiple invocations and across the main browser as well asother apps, providing the best experience to a returning consumer.
| Operating System | WebView Control to Use |
|---|---|
| iOS | ASWebAuthenticationSession |
| Andriod | Custom Chrome Tab |
When the consumer exits the Paze UX, the Paze API redirect the WebView to the callbackURLScheme that the Merchant has provided in the /checkout/session/create API call.
It is expected that this URL is provided in a native mobile format that will cause control to return to the native mobile app.
On redirect to this schema, the Paze API will append query string parameters of status and a hash(#) param response.
- "status" parameter 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
- canceled – the consumer cancelled out of the Paze UX before the last step
- failed – there was some error encountered during the Paze UX flow
- 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
- “response” parameter, includes a Base64URL encoded string with a JWS containing the minimal 'maskedCard' structure in the claim section. Once decoded the JWKS is the code for review/complete call.
The minimal “maskedCard” structure:
| Field | Type | Max Size | Definition / Description | Field Status |
|---|---|---|---|---|
maskedCard.panLastFour | String | 4 | Last 4 digits of the card. | R |
maskedCard.paymentCardDescr iptor | String | 32 | A free-form string (max of 32 characters) used for card/program recognition. Example ‘Travel Rewards', ‘Cashback Rewards' etc. | R |
maskedCard.paymentCardNetwork | Enum | Valid values:
| R | |
maskedCard.paymentCardType | Enum | Valid values:
| R | |
maskedCard.paymentCardBrand | Enum | Brand of payment instrument.
| R | |
maskedCard.digitalCardData | Object | Digital Card Art. | R | |
maskedCard.digitalCardData. artUri | String | 1024 | URI that hosts the Card Art image to be used for presentation purposes. | R |
maskedCard.digitalCardData.artHeight | Integer | Height of art card image, in pixels. | R | |
maskedCard.digitalCardData.artWidth | Integer | Width of art card image, in pixels. | R | |
maskedCard.changeCardUrl | String | 10K | URL to change card | R |
“response” parameter example:
{
"maskedCard": {
"panLastFour": "<String>",
"paymentCardDescriptor": "<String>",
"paymentCardNetwork": "<String>",
"paymentCardType": "<String>",
"paymentCardBrand": "<String>",
"digitalCardData": {
"artUri": "<URL>",
"artHeight": < Integer > ,
"artWidth": < Integer >
},
"changeCardUrl": "<URL>"
},
"authorization": {
"intentId": "<String>"
}
}
For example, if the provided callbackURLScheme was “pazeCheckoutResponse”, then on redirect after successful completion of thePazecheckout flow, the redirect URL will look like this:
“pazeCheckoutResponse://?status=success#response = Rm9ybWF0OmJhc2U2NFVSTEVuY29kZShKVM6aGVhZGVyLmNsYWltLnNpZ25hdHVyZQ==”Implementation Examples
iOS
This section will describe the iOS specific setup and code to launch the Paze checkout experience in a webview. The webview that must be used for iOS is the ASWebAuthenticationSession.
- Import the `AuthenticationServices` framework in the project file.
- import AuthenticationServices
- Configure the URL Scheme
- Open your Xcode project.
- Go to the project settings, select your target, and open the "Info" tab.
- Add a new URL Type by clicking on the plus button.
- Set the callback URL scheme (e.g., com.domain.appid).
- ASWebAuthenticationSession takes two parameters:
- url
- callbackURLScheme
Implementation
class PazeViewController: UIViewController, ASWebAuthenticationPresentationContextProviding {
// startPaze should be called when user hit PAZE checkout button
func startPaze() {
/* pazeURL will be returned in /checkout/session/create response.this is the same, callbackURLScheme which is passed in createCheckoutSession, generally it is app’s bundle identifier( like – com.domain.appName ) */
let callbackPazeScheme = "com.domain.appid"
let sessionPaze = ASWebAuthenticationSession.init(url: pazeURL, callbackURLScheme: callbackPazeScheme) {
callbackURL,
error in guard
let successCallbackURL = callbackURL,
error == nil
else {
// Handle error; checkout with Paze has not be successful.
return
}
let queryItems = URLComponents(string: successCallbackURL.absoluteString) ? .queryItems
// Extract 'status' and 'response' from queryItems and proceed accordingly
}
session.presentationContextProvider = self
session.start()
}
func presentationAnchor(
for session: ASWebAuthenticationSession) - > ASPresentationAnchor {
return self.view.window!
}
}Android
This section will describe the Android specific setup and code to launch thePazeexperience in a webview. The webview that must be used for Android is the Custom Chrome Tab (CCT).
- Add Dependencies in
build.gradlfile.
implementationandroidx.browser:browser:<version> - Configure the Custom URL Scheme
- Open your AndroidManifest.xml.
- Add an intent filter to handle the callback URL scheme (e.g., 'com.domain.app_name').
AndroidManifest.xml
<activity android:name=.PazeCallbackActivity”>
<intent-filter>
<action android:name=”android.intent.action.VIEW” />
<category android:name=”android.intent.category.DEFAULT” />
<category android:name=”android.intent.category.BROWSABLE” />
<data android:scheme="<com.domain.app_name>"; android:host=”callback” />
</intent-filter>
</activity>
Implementation
Launch the WebView
import android.content.Intent;
import android.net.Uri;
import androidx.appcompat.app.AppCompatActivity;
import androidx.browser.customtabs.CustomTabsIntent;
public class PazeActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_paze);
startPaze();
}
private void startPaze() {
// pazeURL will be returned in createCheckoutSession response
Uri uri = Uri.parse(pazeUrl);
CustomTabsIntent.Builder builder = new CustomTabsIntent.Builder();
CustomTabsIntent customTabsIntent = builder.build();
customTabsIntent.intent.setData(uri);
customTabsIntent.launchUrl(this, uri);
}
}
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 [email protected].
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 |
Updated 3 days ago
