On This Page

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 jwtcaptureContext
	optional DpaTransactionOptions});
});

Request Parameters

Your

initialize()

request can include these parameters:

Request Parameters

Name	Required?	Description
dpaTransactionOptions Type : DpaTransactionOptions	Optional	These options can override default transaction options configured during DPA Registration.
N/A Type : String<JWT>	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.

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" } }

Handle 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

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 Response Fields
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.

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 Codes
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.