pilot initialize() {#uctp-api-specs-initialize} ========================================= dpaTransactionOptions is an optional field in a initialize() request. You can include the dpaTransactionOptions field in the `initialize()` request if your system supports it. You must consider this information if you include the dpaTransactionOptions field in your request: * You must include the transaction amount and currency in the backend of the request payload that is sent to `/sessions` API. The values that are included in the request to the `/sessions` API are used and any value included in dpaTransactionOptions are ignored. * You must configure authentication fields in the `Business Center`. The values of these fields are retrieved from the merchant or partner profiles and not from the dpaTransactionOptions field. Your initialize() request must have this syntax: ``` initialize({ required object captureContext; optional DpaTransactionOptions dpaTransactionOptions; }); ``` pilot Request Parameters {#uctp-java-initialize} ========================================== Your initialize() request can include these parameters: Request Parameters {#uctp-java-initialize_OLE_LINK50} ----------------------------------------------------- | Name | Required? | Description | |--------------------------------------------------------|-----------|--------------------------------------------------------------------------------------------| | dpaTransactionOptions **Type** : DpaTransactionOptions | Optional | These options can override default transaction options configured during DPA Registration. | | header **Type**: Decoded JWT header as a String | Required | Decoded header from the `/sessions` API response. | | payload **Type**: Decoded JWT payload as a String | Required | Decoded payload from the `/sessions` API response. | | raw **Type**: String | Required | JWT from the `/sessions` API response. | DpaTransactionOptions --------------------- | Data Element | Required? | Description | |------------------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------| | dpaAcceptedBillingCountries **Type**: List\<String\> | Optional | Billing restrictions. Payments from these countries are accepted. ISO 3166‑1 alpha‑2 country codes. `["US","CA","AU"]` | | dpaBillingPreference **Type** : AddressPreference | Optional | Type of billing address required. Possible values: * `FULL` * `NONE` * `POSTAL_COUNTRY` | | dpaLocale **Type**: String | Optional | Merchant preferred locale in ISO 639‑1 and ISO 3166‑1 format. `["en_US", "fr_CA"]` | | merchantCategoryCode **Type**: String **Length**: 4 | Optional | Merchant category code. | | merchantCountryCode **Type**: String | Optional | Merchant country in ISO 3166‑1 alpha‑2 format. | | merchantName **Type**: String | Optional | Merchant name. | | merchantOrderId **Type**: String, UUID | Optional | DPA-generated order or invoice number. | | paymentOptions **Type** : List\<PaymentOptions\> | Optional | Dynamic Data requirements. | | recurringData **Type** : RecurringData | Optional | Recurring transaction data. | PaymentOptions -------------- | Data Element | Required? | Description | |-----------------------------------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | dpaDynamicDataTtlMinutes **Type**: String (Numeric) | Optional | TTL of the dynamic data in minutes. | | dynamicDataType **Type** : DynamicDataType | Optional | Type of dynamic data required. * `CARD_APPLICATION_CRYPTOGRAM_LONG_FORM` * `CARD_APPLICATION_CRYPTOGRAM_SHORT_FORM` * `CARDHOLDER_AUTHENTICATION_CRYPTOGRAM` * `DYNAMIC_CARD_SECURITY_CODE` * `NONE` | AuthenticationPreferences ------------------------- | Data Element | Required? | Description | |--------------------------------------------------------------------|-----------|-----------------------------------------| | authenticationMethods **Type**: List\<AuthenticationMethod\> | Optional | List of authentication methods. | | payloadRequested **Type** : PayloadRequested | Optional | Indicates preferred payload type. | | supressChallenge **Type**: Boolean | Optional | SRCI preference to suppress challenges. | **AuthenticationMethod** ------------------------ | Data Element | Required? | Description | |----------------------------------------------------------------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| | authenticationMethodType **Type** : AuthenticationMethodType | Required | Indicates whether C2P should perform managed authentication. Possible values: * `3DS` * `APP_AUTHENTICATION` * `CSC_VALIDATION` * `EMAIL_OTP` * `SMS_OTP` | | authenticationSubject **Type** : AuthenticationSubject | Required | Authentication subject. Possible values: * `CARD` * `CARDHOLDER` * `CONSUMER` | | uriData **Type** : UriData | Optional | URI used to launch authentication. Relevant data is returned asynchronously. | | authenticationCredentialReference **Type**: String **Maximum Length**: 255 | Optional | Reference returned by identity provider. | | methodAttributes **Type**: JSONObject | Optional | Method‑specific attributes. | The content of the methodAttributes object depends on the authenticationMethodType field value and the method that is requested. The methodAttributes object is included within the checkout response for the authentication flow or as part of the AuthenticationMethod object in the checkout authentication request flow. If authenticationMethodType is any of the these values. * `CSC_VALIDATION` * `SMS_OTP` * `EMAIL_OTP` * `APP_AUTHENTICATON` * `3DS` | authenticationMethodType | Data Element | Description | |------------------------------------|---------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `CSC_VALIDATION` | cardSecurityCode **Type**: String **Maximum Length**: 4 | Card security code. | | `SMS_OTP` | otpValue **Type**: String **Maximum Length**: 16 | OTP value. | | `EMAIL_OTP` or `APP_AUTHENTICATON` | stepUpIdentifier **Type**: String | Step-up identification. | | `3DS` | challengeIndicator **Type**: String | Challenge indicator value related to `3-D Secure` authentication. For SRC orchestrated `3-D Secure` is authentication method, SRCIs can specify the preference of challenge indicator here. Please refer to EMV `3-D Secure` specification for more details. > IMPORTANT > If no preference provided, SRC will set up the default value of ` 01 ` for ` 3-D Secure ` and 04 when followed by FIDO registration. > If value is set to ` 05 ` by the SRCI then do not override the indicator to ` 03 ` though it is a FIDO compliant device. Possible values: * `01`: No preference * `02`: No challenge requested * `03`: Challenge requested (3DS Requestor Preference) * `04`: Challenge requested (Mandate) * `05`: No challenge requested (transactional risk analysis is already performed) * `06`: No challenge requested (Data share only) * `07`: No challenge requested (strong consumer authentication is already performed) * `08`: No challenge requested (utilize trust list exemption if no challenge required) * `09` :Challenge requested (trust list prompt requested if challenge required) | UriData ------- | Data Element | Required? | Description | |-----------------------------------------------|-----------|--------------------------------------------------------| | uri **Type**: String **Maximum Length**: 2048 | Required | Specifies the URI for the given authentication method. | | uriType **Type** : UriType | Required | URI type. Possible values: * `APP_URI` * `WEB_URI` | RecurringData ------------- | Data Element | Required? | Description | |-------------------------------------------------------------------|------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | recurringAmount **Type**: String (Numeric) **Maximum Length**: 48 | Required when recurringInd.AmountInd = `01` | Recurring amount in minor units of currency with all punctuation removed. For example, when the purchase amount is USD 123.45, these values are acceptable: * `12345` * `012345` * `0012345` | | recurringCurrency **Type**: String | Required when recurringAmount is included. | Currency in which recurringAmount is expressed. Currency must be in ISO 4217 format. | | recurringDate **Type**: String (Numeric) **Length**: 8 | Required when recurringInd.frequencyInd = `01` | Effective date in YYYYMMDD format. | | recurringExpiry **Type**: String (Numeric) **Length**: 8 | Required when there is an end date. | Date after which no further authorizations occur, in YYYYMMDD format. | | recurringExponent **Type**: String (Numeric) **Length**: 1 | Required when recurringAmount is included. | Minor units of currency according to ISO 4217 (e.g., USD=2, JPY=0). | | recurringFrequency **Type**: String **Maximum Length**: 4 | Required when recurringInd.frequencyInd = `01` | Minimum number of days between authorizations (1--9999). | | recurringInd **Type**: JSONObject | Required | Indicates recurring/instalment amount and frequency type. Possible values for amountInd: * `01`: Fixed * `02`: Variable Possible values for frequencyInd: * `01`: Fixed frequency * `02`: Variable/unknown frequency Example: ``` { "recurringInd": { "amountInd": "01", "frequencyInd": "02" } } ``` | pilot Handle Errors {#uctp-initialize-errors} ======================================= An error response notifies the user that the action relating to the request has failed. Use the error.reason field to determine how to handle the error. Errors such as `INVALID_PARAMETER` or `INVALID_REQUEST` are considered integration errors. Error reasons and messages appear in a standard error structure, which is returned when the API request could nxot be handled. For programmatic actions, you should only rely on the value in the error.reason field. Errors include a description in the error.message field.You can use this field to understand the error. You can provide your own description based on the value in the error.reason field. In some cases, the error.details.message and error.details.location provide additional information. | Error Field | Type | Description | |------------------------|--------|-------------------------------------------------------------------------------------------------------------------------| | error.details.location | String | The value of this field uses an XPATH expression to point to the field that fails validation. | | error.details.message | String | The specific error associated with the field. | | error.message | String | Returned from the backend call | | error.reason | String | These options can be used to override transaction options for the DPA that were configured during the DPA Registration. | [Error Response Fields] This is an example error: ``` error { "message": "Input parameters validation failed.", "reason": "INVALID_PARAMETER", "details": [ // Optional structure, used with input data validation error { // Types to specify the fields with errors "location": "creditCard", "message": "Should be a numeric value" } ] } ``` | Error Code | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `AUTH_ERROR` | The server understands the request, but cannot authenticate. | | `INVALID_PARAMETER` | The value provided for one or more request parameters is considered invalid. This error is also generated in case of a missing required field. Typically, this is an integration error; whenever possible, should provide client-side validation to avoid a round trip to the server. For user errors, handle this error by prompting the user to change the value. | | `INVALID_REQUEST` | The server could not interpret the request. Usually, these are the cases, when a data field has to be in a particular format but is not. Examples include: * Base64 decoding failed * The field is not in a particular format. The message field may provide additional clarification of what part or field of the request is considered incorrect. Please, refer to the API specification for the structure, format, and constraints on the API request. | | `NOT_FOUND` | The requested resource/business entity does not exist. The resource might also be hidden for security reasons. | | `RATE_LIMIT_EXCEEDED` | Too many requests have been sent in a given amount of time. Intended for use with rate limiting schemes. * Decrease the rate of sending API requests; wait before sending the next request. * Consider implementing Exponential Backoff algorithm. In this algorithm, the delay before you retry is defined as: Retry delay in milliseconds = (2 \^ *n* ) \* 1000 + *randomDelayMs* , where n is your retry count, such as 0, 1, 2, 3, ..., and *random- DelayMs*is random delay in milliseconds, such as an integer between 0 and 1,000. | | `REQUEST_TIMEOUT` | Request timeout. | | `SERVER_ERROR` | General server error. | | `SERVICE_ERROR` | An error occurred on the server. Either show a generic message, or retry the same request again (it might succeed). | | `UNKNOWN_ERROR` | Unknown error. | [Error Codes]