Merchant Mobile Application API Technical Requirements
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 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 utilized for the API endpoints described below. The details for this API are documented in thePaze 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. Merchant should not attempt to reuse a Paze OAuth token across multiplecheckout sessions; doing so 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 includeany 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 appropriateUX 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 flow, or there was some other error, 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’scard and shipping address selection for display on confirmation screen, if one is presentedto the consumer.
[Optional] Re-Launch thePazecheckout UX to allow user to change card or shipping address: If the Merchant provides options to the user to change their selectedcard and/or shipping address, and consumer taps one of those options, the Merchant needs to launch the Paze UX again, but this time utilizing the appropriate URL returned in a prior response payload, in the 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/review API to retrieve the updatedinformation or to
/checkout/session/complete API to close the checkout session.
Call /checkout/session/complete API**: Closes the Merchant and consumer sessions andprovides payment details required to successfully process the Payment Transaction, includingwhether the consumer intends to make a payment immediately, put a card on file with theMerchant, 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 thePazeMerchant 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 notbe 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 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 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}ZExample: 2015-12-31T17:18Z 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. For example: - Missing required field. - The value exceeds the length specified for this field. - Field formatting does not match the expected format.The "details.location” field of the error response may provide a list of fields which failed data validation constraints. |
| 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: - Base64URL decoding failed. - The field is not in a particular format.The message field may provide additional clarification of what part/field of the request is considered incorrect.Refer to the API specification for the structure, format and constraints of the API request. |
| 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: 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.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.phoneNumber | 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 | ||||
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| data.callbackURLScheme | String | 20 | This is Merchant app’s ID; for iOS it’s bundle identifier and Android it’sapplication Id. | R |
| It is the callback URL scheme to use to return to the Merchant’s mobileapp.This is used by the Paze UX running in the WebView to return theconsumer back to the Merchant’s native mobile app after theconsumer exits the Paze UX, either after finishing all the steps orcanceling 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 otherPaze 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 thePaze UX flow | ||||
|---|---|---|---|---|
| data.emailAddress | String | 128 | Email address as consumer identity.Underlying email address value MUST conform to the RFC 5322address- 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.phoneNumber | 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 |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| 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 maysimultaneously check out and ask to retain the same cardon file. In that case, intent should be set toREVIEW_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 bedisplayed in the Paze UI if this is excluded from therequest. Not needed if the consumer is selecting a card tokeep on file with Merchant.Condition: Required if intent is EXPRESS_CHECKOUT. Request will be invalid when transactionValue is provided ifintent is ADD_CARD. | C | |
| data.transactionValue. transactionCurrency | String | Currency code of the transaction. ISO 4217 currencycode.Example: ‘USD’ | R |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| data.transactionValue. transactionAmount | String | The amount of the transaction. Must include dollar and cents valueinproper format. Digits before and after the decimal point “.” Are required,including trailing zeros | R |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| Example: “99.95” | ||||
| data.shippingPreference | Enum | 32 | Whether Merchant wants to have shipping address collected. Valid values:• ALL (default)• NONENote: NONE suppresses 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 | O |
| 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. | O |
| data.cobrand[].name | String | 100 | Product name of the cobrand card.Must match exactly with the card name received from theapplicable network. | R |
| data.cobrand[].benefitsOffered | Boolean | Default value is false. | O | |
| 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 |
| Field | Type | Max Size | Description | Field Status |
|---|
| 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. | O |
|---|
4.1.2 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: {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. |
4.1.3 Service Request / Response Example
POST 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"
}
}
4.2 /checkout/session/review
API to retrieve the data related to the card selected by the consumer in thePazecheckout 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.
4.2.1 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 |
4.2.2 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}ZExample: 2015-12-31T17:18ZTime stamp when 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 |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| 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 |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| ata | ||||
| 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 | R |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| • DISCOVER | ||||
| 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/…"} | R |
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. |
4.2.3 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":"", "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":,"change_shipping_address":
}
}
}
}
4.3 /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.
4.3.1 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 theMerchant must provide “PURCHASE” or “BOTH” only asDiscover does not support "CARD_ON_FILE”.When “BOTH” is provided, only a dynamicDataType equal toPURCHASE will be returned. | R |
| data.transactionOptions | Object | Client configuration data that can override any configuration that wascreated 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) | O |
| Field | Type | Max Size | Description | Field Statu s |
|---|---|---|---|---|
| • PAYMENT – Returns payloadId and securedPayload | ||||
| 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 |
| Field | Type | Max Size | Description | Field Statu s |
|---|---|---|---|---|
| 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.finalShippingAddress.deliveryContactDetails | Object | Delivery contact details for a shipping address | O | |
| data.enhancedTransactionData. ecomData.finalShippingAddress.deliveryContactDetails.conta ctFullName | String | 100 | Consumer-provided name of the contact person | O |
| data.enhancedTransactionData. ecomData.finalShippingAddress.deliveryContactDetails.conta ctPhoneNumber | Object | Consumer-provided phone number of the contact person | O | |
| data.enhancedTransactionData. ecomData.finalShippingAddress.deliveryContactDetails.conta ctPhoneNumber.countryCode | String | 4 | International Subscriber Dialing (ISD) Codes. | R |
| data.enhancedTransactionData. ecomData.finalShippingAddress.deliveryContactDetails.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 |
| Field | Type | Max Size | Description | Field Statu s |
|---|---|---|---|---|
| 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 |
| Field | Type | Max Size | Description | Field Statu s |
|---|---|---|---|---|
| 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 |
4.3.2 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 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.ci | String | 128 | Shipping city | R |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| ty | ||||
| data.shippingAddress.st ate | String | 2 | Shipping State/Region | R |
| data.shippingAddress.zi p | String | 10 | Postal Code (5 digit or ZIP+4 format) | R |
| data.shippingAddress.co untryCode | String | 2 | ISO-3166-1 alpha-2 standard code. | R |
| data.shippingAddress.de liveryContactDetails | Object | Delivery contact details for a shipping address | O | |
| data.shippingAddress.de liveryContactDetails.co ntactFullName | String | 100 | Consumer-provided name of the contact person | O |
| data.shippingAddress.de liveryContactDetails.co ntactPhoneNumber | Object | Consumer-provided phone number of the contact person | O | |
| data.shippingAddress.de liveryContactDetails.co ntactPhoneNumber.countr yCode | String | 4 | International Subscriber Dialing (ISD) Codes. | R |
| data.shippingAddress.de liveryContactDetails.co ntactPhoneNumber.phoneN umber | String | 10 | Phone number | R |
| data.securePayload | String | Information necessary to process payment. This field will hold 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 |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| 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.billingPreferenceIf 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 |
| Field | Type | Max Size | Description | Field Status |
|---|---|---|---|---|
| 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. |
4.3.3 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":"Dylan", "lastName":"McKay", "fullName":"Dylan McKay",
"emailAddress":"[email protected]", "mobileNumber":{
"countryCode":"1", "phoneNumber":"7735550100"
}
"countryCode":"US", "landuageCode":"en_US"
},
"eci":"electronic-commerce-indicator-3ds-std"
}
}
}
5. 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 will 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.
1. "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
2. “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:• VISA• MASTERCARD• DISCOVER | R | |
| maskedCard.paymentCardType | Enum | Valid values:• CREDIT• DEBIT | R | |
| maskedCard.paymentCardBrand | Enum | Brand of payment instrument. Valid values:• VISA• MASTERCARD• DISCOVER | 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":"", "paymentCardDescriptor":"", "paymentCardNetwork":"", "paymentCardType":"", "paymentCardBrand":"","digitalCardData": {
"artUri":"",
"artHeight":, "artWidth":
},
"changeCardUrl":""
},
"authorization": { "intentId": ""
}
}
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==”
5.1 Implementation Examples
5.1.1 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.
1. import the `AuthenticationServices` framework in the project file.
- import AuthenticationServices
2. 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).
3. ASWebAuthenticationSession takes two parameters –
a. url
b. 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
}
letqueryItems=URLComponents(string:successCallbackURL.absoluteString)?.queryIt
ems
// Extract 'status' and 'response' from queryItems and proceed accordingly
}
session.presentationContextProvider = selfsession.start()
}
func presentationAnchor(for session:ASWebAuthenticationSession)-> ASPresentationAnchor
{
return self.view.window!
}
}
5.1.2 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).
1. Add Dependencies in `build.gradle` file.
- implementation 'androidx.browser:browser:'
2. 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
<data android:scheme="<com.domain.app_name>"; android:host=”callback” />
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();
}
}
6. 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, all 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.
7. Support
For support inquiries, contact [email protected].
8. 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
8.1 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 |
8.2 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