Introduction

The Paze service offers Merchants a simple and convenient way for their consumers to easily provide them withcheckout information. A Consumer’s Paze wallet contains their credit and debit card information from participating Issuers as well as contact information and address information that can be used for shipping.

The Paze Merchant Business to Business (B2B) APIs Technical Requirements provides information about application programming interfaces (APIs) intended to retrieve a payload that had not been retrieved during the original Paze processing using the Merchant JavaScript SDK. This API may be used by the Merchant or an entity acting on their behalf, such as a payment service provider.

OAuth Authentication

Paze uses OAuth Authentication to secure the link between businesses and Early Warning. This is a standard enterpriseservice for B2B communications. Details, including relevant URLs, are available in the guide referenced below.

The Paze server URL is b2b.wallet.earlywarning.com. For details, refer to the Paze Platform API OAuth Access User Guide**[JR1]** available on Venue.

Detail Tables – Column Definitions

The following sections contain tables of fields with one or more of the columns described below.

Table 1. Detail Table Column Definitions

Column Name	Column Description
Seq. #	Position of the field in the code
Field Name	Name of field
Field Type	Field data type
Field Usage	How the field is used:• Required – Must be provided• Optional – Can be provided when available and/or applicable• Conditional – Must be provided if other fields are populated
Description	Field description

Authentication Endpoints

Paze authentication certificates are hosted at the following URLs.

Table 2. Authentication Endpoints

Environment	URL
Testing/Sandbox	https://auth.wallet.cat.earlywarning.io/jwks
Production	https://auth.wallet.earlywarning.com/jwks

Retrieve Public Keys API

This API retrieves cryptographic public keys from a well-known URL hosted by Paze. The keys retrieved are used by Participants for:

JWS signature verification in checkoutResponse
Encrypted payment card and Consumer details presented during enrollment

Retrieve Public Keys Request

Endpoint/Method

Path	/jwks
Method	GET

Query Parameter

Table 3. Retrieve Public Keys Request Parameter

FieldName	FieldType	FieldUsage	Description/Expected Values
id	String	Required	Identifier generated by Paze and shared with Merchant during onboardingFormat: Universally Unique Identifier (UUID)

Request Headers

Table 4. Retrieve Public Keys Request Headers

Field Name	Description
Authorization	(Required) Base64 encoded username and password.
Content-Type	application/json
Accept	application/json

Request Body

None

Retrieve Public Keys Response

Response Body

Table 5. Retrieve Public Keys Response Body

FieldName	FieldType	Description
keys	String	Public key certificatesFormat: Array of JsonWebKey structures

JsonWebKey Structures

The JsonWebKey structure provides additional information when returned:

Table 6. JsonWebKeys Fields

Seq. #	Field Name	Field Type	Description
1	kty	String	Key Type Parameter Format:Alphanumeric
2	use	String	Key usage Valid values:• sig• enc
3	keyOps	String	Key operation Valid values:• verify• encrypt
4	kid	String	Key ID (kid) parameter is used to match a specific key Format:Alphanumeric
5	alg	String	Algorithm to use with the key Format:Alphanumeric
6	x5c	String	X.509 certificate chain (x5c) parameter contains a chain of one or more PKIX certificates [RFC5280]. The certificate chain is represented as a JSON array ofcertificate value strings. Each string in the array is a base64-encoded (Section 4 of [RFC4648], not base64url-encoded) DER [ITU.X690.1994] PKIX certificate value. The PKIX certificate containing the key value MUST be the first certificate.Format: Alphanumeric

Retrieve Public Keys Response Codes

Table 7. Retrieve Public Keys Response Codes

HTTP Status Code	Description
200	Success
403	Access is forbidden
500	Internal server error, failed to build response; see error object for details.

Retrieve Public Keys Examples

Request

GET {host}/jwks

Response

{

"keys": [{

"typ": "string",

"use": "sig",

"alg": "string",

"kid": "string",

"x5c": "string"

}]

}

Get Payload API

This API enables the Merchant to retrieve payload data from Paze. Call this API to retrieve information required to process the Payment Transaction.

Get Payload Request

Endpoint/Method

Path	/getPayload
Method	GET

Query Parameters

Table 8. Get Payload Request Query Parameters

Seq.#	Field Name	FieldType	FieldUsage	Description
1	id	String	Requir ed	Identifier generated by Paze and shared with the Merchant during onboarding
2	payloadId	String	Requir ed	Unique identifier generated by Paze to track and link transaction-specific messagesThis identifier was provided in the Completeresponse of the Merchant JavaScript SDKFormat: String; 64 bytes
3	processingNetwo rk	Enum	Option al	Payment Network selected to process the transactionIf not provided, will default to card network on front of card.

Request Headers

Table 9. Get Payload Request Headers

Field	Description
Authorization	Bearer access_token
Content-Type	application/json
Accept	application/json

Request Body

None

| |

| --- |
| | |

Get Payload Response

Response Body

Table 10. Get Payload Response Body

Seq. #	Field Name	Field Type	Field Usage	Description
1	payloadId	String	Required	Unique identifier generated by Paze to track and link transaction-specific messagesThis identifier was provided in the Complete response of the Merchant JavaScript SDK
2	sessionId	String	Conditional	Merchant-specific field that, if passed in as a query parameter, will be returned in the responseCondition: Returned if sessionId was passed in by the Merchant with the request to transact (Merchant JavaScript SDK Complete API).
4	securedPayl oad	JWE<JWS>	Required	Information necessary to process Payment TransactionSee Secured Payload for a list of encrypted signed payload data elements.

Get Payload Response Codes

Table 11. Get Payload Response Codes

HTTP Status Code	Description
200	Success
403	Access is forbidden
500	Internal server error, failed to build response

4. Types

Address Data Elements

The following structure details the Address object.

Table 12. Address Data Elements

Field Name	Field Type	Field Usage	Description
name	String	Optional	Name of the Consumer at the address
line1	String	Optional	Line 1 of the address
line2	String	Optional	Line 2 of the address
line3	String	Optional	Line 3 of the address
City	String	Optional	Name of the city
State	String	Optional	Name of the state
Zip	String	Required	Postal code for this address
Country Code	String	Required	Country code for this address ISO3166-1 alpha-2 country code

Token Data Elements

The following structure details the Token object.

Table 13. Token Data Elements

Field Name	FieldType	FieldStatus	Description
paymentToken	String	Required	Tokenized payment instrument
tokenExpirationMonth	String	Required	Two-digit expiration month
tokenExpirationYear	String	Required	Four-digit expiration year

paymentAccountRefere nce	String	Required	PAR linked to the token’s PAN

Secured Payload Data Elements

This section details the structure of the encrypted Payload object that is a part of the JWE claim. JWE must have a JWS as claim that contains a single composite JSON object, “payload” as a claim whose JSON structure is defined below.

The following structure details the Encrypted Signed Payload object.

Table 14. Encrypted Signed Payload Data Elements

Field Name	FieldType	FieldUsage	Description
id	String	Required	Client identifier. This is generated by Paze and shared with client during onboarding
profileId	String	Required	The Client profile that was used during checkout
token	Object(T oken)	Required	A token payload that contains the token number and associated attributes
paymentCardNetw ork	Enum	Required	Payment Network Valid values:• VISA• MASTERCARD• DISCOVER
dynamicData	List(Dyn amicDa ta)	Required	Dynamic data applicable for a consumer- initiated payment or request to keep a card on file.See Dynamic Data Elements for more information.
billingAddress	Object( Address)	Conditiona l	Billing address of the card selected, at the verbosity indicated by transactionOptions.billingpreferenceCondition: Provided when the Merchant required a billing address.
consumer	Object( Consum er)	Required	Identifying information about the Consumer who completed the checkout including name andcontact information
eci	String	Conditiona l	ECommerce Indicator. Code indicating a transaction’s level of adherence to 3D Secure (3DS) authentication standardsCondition: Provided when the Merchant submitted a payment transaction.

Dynamic Data Elements

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

Table 15. Dynamic Data Elements

Field Name	FieldType	FieldUsage	Description
dynamicData	String	Required	Dynamic data value. (20 bytes or 3-4 digits)
dynamicDataT ype	Enum	Required	Valid values:• PURCHASE• CARD_ON_FILENote: CARD_ON_FILE not supported for Discover.
dynamicDataE xpiration	String	Optional	Indicates validity period for the dynamic data

Consumer Data Elements

The following structure details the Consumer object.

Table 16. Consumer Data Elements

Field Name	FieldType	FieldUsage	Description
firstName	String	Optional	First name of the Consumer

lastName	String	Optional	Last name of the Consumer
fullName	String	Required	Full name of the Consumer
emailAddress	String	Required	Email address of the Consumer
mobileNumber	Object(P honeNu mber)	Optional	Mobile number of the Consumer
countryCode	String	Optional	Consumer provided CountryCodeCountry in ISO 3166-1 alpha-2 format, e.g., "US"
languageCode	String	Optional	Consumer’s LocaleBased on ISO format for language (ISO 639-1) and alpha-2 country code (ISO 3166-1 alpha-2). separated using a “_“.For example, "en_US".

PhoneNumber Data Elements

The following structure details the PhoneNumber object.

Table 17. PhoneNumber Data Elements

Field Name	FieldType	FieldUsage	Description
countryCode	String	Required	Phone number Country code
phoneNumber	String	Required	Phone number

5. API Error Handling

An error response notifies the caller that the action relating to the promise has failed. Use the errorDetail.reasonfield to drive your error handling logic.

Error Structure and Usage

Error reasons and messages appear in a standard structure, which is returned when the API request could not be handled.For programmatic actions, you should only rely on the value in the reason field. Errors are provided with a humanreadable error description in message field; however, this field should be used only to understand the problem. You may prefer to provide your own description based on the value in the reason field. In some cases, the errorDetailstructure provides additional information.

Error Response Fields

Table 18. Error Response Fields

Seq.#	Field Name	FieldType	Description
1	message	String	Internal error message, which should not be displayed or used in the logic of your code; it is provided as a convenienceFormat: Maximum 255 characters
2	status	Integer	HTTP status codeFormat: From 100 to 600, inclusive
3	reason	String	Mnemonic identifying the kind of error associated with the status; use thisfield to trigger error handling logic in your codeFormat: Maximum 32 characters
4	errorDetail	String	One or more details associated error Format: Anarray of ErrorDetail structures

errorDetail Array Structure[JR2]

The errorDetail structure provides additional information when returned:

Table 19. errorDetail Fields

Seq.#	Field Name	Field Type	Description
1	reason	String	Mnemonic identifying the kind of error associated with the status; use this field to trigger error handling logic in your codeFormat: Maximum 32 characters
2	message	String	Specific error associated with the field Format: Maximum 255 characters
3	sourceType	String	Kind of sourceFormat: Maximum 255 characters

Example

{

"status": 100, "reason":"string", "message":"string","errorDetail": [

{

"reason": "string",

"source": "string",

"message": "string", "sourceType":"string"

}

]

6. Support

For support inquiries, contact [email protected].

[JR1]Confirm name, I think it now called Paze API Oauth

[JR2]Fix formating