Request formats for payment processing using SDK for mobile applications

Overview

3‑D Secure 2 authentication is supported by all versions of SDK for mobile applications (SDK for Android and SDK for iOS), but starting with SDK for Android 1.5 and SDK for iOS 1.5.1 there is also an option to use additional parameters in order to make selection of the frictionless flow authentication more likely. This section provides information about these additional parameters.

Request format for payment processing using SDK for Android

Starting with SDK for Android 1.5, it is recommended to specify the threeDSecureInfo object, as well as the embedded objects and parameters, in requests for opening the payment form. Since the objects embedded into threeDSecureInfo and their corresponding parameters are optional, the objects to be included in the request can be selected by the merchant. The following objects can be embedded into threeDSecureInfo:
  • threeDSecurePaymentInfo—object with information about the purchase details and indication of the preferable authentication flow; this object also includes the threeDSecureGiftCardInfo object with information about payment with prepaid card or gift card.
  • threeDSecureCustomerInfo—object with information about the customer. It also contains the following objects:
    • threeDSecureAccountInfo—object with information about customer account details on record with the web service.
    • threeDSecureShippingInfo—object with shipping details.
    • threeDSecureMpiResultInfo—object with information about previous customer authentication.
Table 1. Parameters
PARAMETER TYPE DESCRIPTION
threeDSecureInfo—object of the ECMPThreeDSecureInfo class containing additional objects and parameters used during the 3‑D Secure 2 authentication
threeDSecurePaymentInfo—object of the ECMPThreeDSecurePaymentInfo class with information about the purchase details and indication of the preferable authentication flow
challengeIndicator string

This parameter indicates whether challenge flow is requested for this payment.

Possible values:
  • 01—no preferences
  • 02—it is preferable not to use challenge flow
  • 03—challenge flow preferred
  • 04—always use challenge flow
challengeWindow string

The dimensions of a window in which authentication page opens.

Possible values:
  • 01—250 x 400 px
  • 02—390 x 400 px
  • 03—500 x 600 px
  • 04—600 x 400 px
  • 05—full screen
preorderDate string

The date the preordered merchandise will be available.

Format: dd-mm-yyyy.

preorderPurchase string

This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date.

Possible values:
  • 01—merchandise available in stock
  • 02—future merchandise availability
reorder string

This parameter indicates whether the cardholder is reordering previously purchased merchandise.

Possible values:
  • 01—first time order
  • 02—reorder
threeDSecureGiftCardInfo—object of the ECMPThreeDSecureGiftCardInfo class with information about payment with prepaid card or gift card.
amount integer Amount of payment with prepaid or gift card denominated in minor currency units.
currency string Currency of payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example GBP.
count integer Total number of individual prepaid or gift cards/codes used in purchase.
threeDSecureCustomerInfo—object of the ECMPThreeDSecureCustomerInfo class with information about the customer.
addressMatch string

The parameter indicates whether the customer billing address matches the address specified in the threeDSecureShippingInfo object.

Possible values:
  • Y—Shipping Address matches Billing Address
  • N—Shipping Address does not match Billing Address
billingRegionCode string State, province, or region code in the ISO 3166-2 format. Example: SPE for Saint Petersburg, Russia.
homePhone string

Customer home phone number.

Numeric, from 4 to 24 characters. Example: 44991234567.

workPhone string

Customer work phone number.

Numeric, from 4 to 24 characters. Example 44997654321.

threeDSecureAccountInfo—object of the ECMPThreeDSecureAccountInfo class with information about customer account details on record with the web service
additional string

Additional customer account information, for instance arbitrary customer ID.

Maximum 64 characters.

activityDay integer Number of card payment attempts in the last 24 hours.

Maximum 3 characters (999).

activityYear integer Number of card payment attempts in the last 365 days.

Maximum 3 characters (999).

ageIndicator string

Number of days since the customer account was created.

Possible values:
  • 01—guest check-out
  • 02—customer account was created in this transaction
  • 03—customer account was created less than 30 days ago
  • 04—customer account was created 30 to 60 days ago
  • 05—customer account was created over 60 days ago
authData string

Any additional log in information in free text.

Maximum 255 characters.

authMethod string

Authentication type the customer used to log on to the account when placing the order.

Possible values:
  • 01—no authentication
  • 02—log on by using authentication data on file with merchant
  • 03—log on by using federated ID (for example, Google Account or Facebook)
  • 04—log on by using a FIDO authenticator (Fast IDentity Online)
authTime string

Account log on date and time.

Format: dd-mm-yyyyhh:mm.

date string

Account creation date.

Format: dd-mm-yyyy.

changeDate string

Last account change date except for password change or password reset.

Format: dd-mm-yyyy.

changeIndicator string

Number of days since last customer account update, not including password change or reset.

Possible values:
  • 01—updated in this transaction
  • 02—updated less than 30 days ago
  • 03—updated 30−60 days ago
  • 04—updated over 60 days ago
passChangeDate string

Last password change or password reset date.

Format: dd-mm-yyyy.

passChangeIndicator string

Number of days since the last password change or reset.

Possible values:
  • 01—password never changed
  • 02—changed in this transaction
  • 03—changed less than 30 days ago
  • 04—changed 30−60 days ago
  • 05—changed over 60 days ago
paymentAge string

Card record creation date.

Format: dd-mm-yyyy.

paymentAgeIndicator string

Number of days since the payment card details were saved in a customer account.

Possible values:
  • 01—current payment uses no customer account (guest checkout)
  • 02—card details were saved today
  • 03—card details were saved less than 30 days ago
  • 04—card details were saved 30 to 60 days ago
  • 05—card details were saved more than 60 days ago
provisionAttempts integer Number of attempts to add card details in customer account in the last 24 hours.

Maximum 3 characters (999).

purchaseNumber integer Number of purchases with this cardholder account in the previous six months.

Maximum 4 characters (9999).

suspiciousActivity string

Suspicious activity detection result.

Possible values:
  • 01—no suspicious activity detected
  • 02—suspicious activity detected
threeDSecureShippingInfo—object of the ECMPThreeDSecureShippingInfo class with shipping details.
address string

Shipping address.

Maximum 150 characters.

addressUsage string First shipping address usage date.

Format: dd-mm-yyyy.

addressUsageIndicator string

Number of days since the first time usage of the shipping address.

Possible values:
  • 01—this transaction
  • 02—less than 30 days ago
  • 03—30−60 days ago
  • 04—more than 60 days ago
city string

Shipping city.

Maximum 50 characters.

country string Shipping country in the ISO 3166-1 alpha-2 format, for example GB.
deliveryEmail string

The email for the digital content delivery.

Maximum 255 characters.

deliveryTime string

Shipment terms.

Possible values:
  • 01—digital delivery
  • 02—same-day delivery
  • 03—overnight delivery
  • 04—longer than overnight delivery
nameIndicator string

Shipment recipient flag.

Possible values:
  • 01—customer and shipment recipient are the same person
  • 02—customer and shipment recipient are different persons
postal string

Shipping postbox number.

Maximum 16 characters.

regionCode string

State, province, or region code in the ISO 3166-2 format. Example: SPE for Saint Petersburg, Russia.

If you specify this parameter, you need also to specify and populate the country parameter in the threeDSecureShippingInfo object.

type string

Shipment indicator.

Possible values:
  • 01—ship to cardholder billing address
  • 02—ship to another verified address on file with merchant
  • 03—ship to address that is different from the cardholder billing address or any verified address on file with merchant
  • 04—ship to local store
  • 05—digital goods shipment
  • 06—no shipment, for instance for travel or event tickets
  • 07—other, for example gaming or subscriptions
threeDSecureMpiResultInfo—object of the ECMPThreeDSecureMpiResultInfo class with information about previous customer authentication
acsOperationId string The ID the issuer assigned to the previous customer operation. Maximum 36 characters.
authenticationFlow string

The flow the issuer used to authenticate the cardholder in the previous operation.

Possible values:
  • 01—frictionless flow
  • 02—challenge flow
authenticationTimestamp string Date and time of the previous successful customer authentication

Code samples

Figure: Kotlin

val threeDSecureInfo = ECMPThreeDSecureInfo()

val threeDSecureCustomerInfo = ECMPThreeDSecureCustomerInfo()

threeDSecureCustomerInfo.workPhone = "89998887700"
threeDSecureCustomerInfo.addressMatch = "Y"

val threeDSecurePaymentInfo = ECMPThreeDSecurePaymentInfo()

threeDSecurePaymentInfo.reorder = "01"
threeDSecurePaymentInfo.preorderPurchase = "02"


threeDSecureInfo.threeDSecurePaymentInfo = threeDSecurePaymentInfo
threeDSecureInfo.threeDSecureCustomerInfo = threeDSecureCustomerInfo

paymentInfo.setEcmpThreeDSecureInfo(threeDSecureInfo);

Figure: Java

ECMPThreeDSecureInfo threeDSecureInfo = new ECMPThreeDSecureInfo();

ECMPThreeDSecureCustomerInfo threeDSecureCustomerInfo = new ECMPThreeDSecureCustomerInfo();

threeDSecureCustomerInfo.setWorkPhone("89998887700");
threeDSecureCustomerInfo.setAddressMatch("Y");

ECMPThreeDSecurePaymentInfo threeDSecurePaymentInfo = new ECMPThreeDSecurePaymentInfo();

threeDSecurePaymentInfo.setReorder("01");
threeDSecurePaymentInfo.setPreorderPurchase("02");


threeDSecureInfo.setThreeDSecurePaymentInfo(threeDSecurePaymentInfo);
threeDSecureInfo.setThreeDSecureCustomerInfo(threeDSecureCustomerInfo);

paymentInfo.setEcmpThreeDSecureInfo(threeDSecureInfo)

Request format for payment processing using SDK for iOS

Starting with SDK for iOS 1.5.1, it is recommended to specify the threeDSecureInfo object, as well as the embedded objects and parameters, in requests for opening the payment form. Since the objects embedded into threeDSecureInfo and their corresponding parameters are optional, the objects to be included in the request can be selected by the merchant. The following objects can be embedded into threeDSecureInfo:
  • threeDSecurePaymentInfo—object with information about the purchase details and indication of the preferable authentication flow; this object also includes the threeDSecureGiftCardInfo object, which contains information about payment with prepaid card or gift card.
  • threeDSecureCustomerInfo—object with information about the customer. It also contains the following objects:
    • threeDSecureAccountInfo—object with information about customer account details on record with the web service.
    • threeDSecureShippingInfo—object with shipping details.
    • threeDSecureMpiResultInfo—object with information about previous customer authentication.
Table 2. Parameters
PARAMETER TYPE DESCRIPTION
threeDSecureInfo—object of the ThreeDSecureInfo class containing additional objects and parameters used during the 3‑D Secure 2 authentication
threeDSecurePaymentInfo—object of the ThreeDSecurePaymentInfo class with information about the purchase details and indication of the preferable authentication flow
challengeIndicator string

This parameter indicates whether challenge flow is requested for this payment.

Possible values:
  • 01—no preferences
  • 02—it is preferable not to use challenge flow
  • 03—challenge flow preferred
  • 04—always use challenge flow
challengeWindow string

The dimensions of a window in which authentication page opens.

Possible values:
  • 01—250 x 400 px
  • 02—390 x 400 px
  • 03—500 x 600 px
  • 04—600 x 400 px
  • 05—full screen
preorderDate string

The date the preordered merchandise will be available.

Format: dd-mm-yyyy.

preorderPurchase string

This parameter indicates whether cardholder is placing an order for merchandise with a future availability or release date.

Possible values:
  • 01—merchandise available in stock
  • 02—future merchandise availability
reorder string

This parameter indicates whether the cardholder is reordering previously purchased merchandise.

Possible values:
  • 01—first time order
  • 02—reorder
threeDSecureGiftCardInfo—object of the ThreeDSecureGiftCardInfo class with information about payment with prepaid card or gift card.
amount integer Amount of payment with prepaid or gift card denominated in minor currency units.
currency string Currency of payment with prepaid or gift card in the ISO 4217 alpha-3 format, for example GBP.
count integer Total number of individual prepaid or gift cards/codes used in purchase.
threeDSecureCustomerInfo—object of the ThreeDSecureCustomerInfo class with information about the customer.
addressMatch string

The parameter indicates whether the customer billing address matches the address specified in the threeDSecureShippingInfo object.

Possible values:
  • Y—Shipping Address matches Billing Address
  • N—Shipping Address does not match Billing Address
billingRegionCode string State, province, or region code in the ISO 3166-2 format. Example: SPE for Saint Petersburg, Russia.
homePhone string

Customer home phone number.

Numeric, from 4 to 24 characters. Example: 44991234567.

workPhone string

Customer work phone number.

Numeric, from 4 to 24 characters. Example 44997654321.

threeDSecureAccountInfo—object of the ThreeDSecureAccountInfo class with information about customer account details on record with the web service
additional string

Additional customer account information, for instance arbitrary customer ID.

Maximum 64 characters.

activityDay integer Number of card payment attempts in the last 24 hours.

Maximum 3 characters (999).

activityYear integer Number of card payment attempts in the last 365 days.

Maximum 3 characters (999).

ageIndicator string

Number of days since the customer account was created.

Possible values:
  • 01—guest check-out
  • 02—customer account was created in this transaction
  • 03—customer account was created less than 30 days ago
  • 04—customer account was created 30 to 60 days ago
  • 05—customer account was created over 60 days ago
authData string

Any additional log in information in free text.

Maximum 255 characters.

authMethod string

Authentication type the customer used to log on to the account when placing the order.

Possible values:
  • 01—no authentication
  • 02—log on by using authentication data on file with merchant
  • 03—log on by using federated ID (for example, Google Account or Facebook)
  • 04—log on by using a FIDO authenticator (Fast IDentity Online)
authTime string

Account log on date and time.

Format: dd-mm-yyyyhh:mm.

date string

Account creation date.

Format: dd-mm-yyyy.

changeDate string

Last account change date except for password change or password reset.

Format: dd-mm-yyyy.

changeIndicator string

Number of days since last customer account update, not including password change or reset.

Possible values:
  • 01—updated in this transaction
  • 02—updated less than 30 days ago
  • 03—updated 30−60 days ago
  • 04—updated over 60 days ago
passChangeDate string

Last password change or password reset date.

Format: dd-mm-yyyy.

passChangeIndicator string

Number of days since the last password change or reset.

Possible values:
  • 01—password never changed
  • 02—changed in this transaction
  • 03—changed less than 30 days ago
  • 04—changed 30−60 days ago
  • 05—changed over 60 days ago
paymentAge string

Card record creation date.

Format: dd-mm-yyyy.

paymentAgeIndicator string

Number of days since the payment card details were saved in a customer account.

Possible values:
  • 01—current payment uses no customer account (guest checkout)
  • 02—card details were saved today
  • 03—card details were saved less than 30 days ago
  • 04—card details were saved 30 to 60 days ago
  • 05—card details were saved more than 60 days ago
provisionAttempts integer Number of attempts to add card details in customer account in the last 24 hours.

Maximum 3 characters (999).

purchaseNumber integer Number of purchases with this cardholder account in the previous six months.

Maximum 4 characters (9999).

suspiciousActivity string

Suspicious activity detection result.

Possible values:
  • 01—no suspicious activity detected
  • 02—suspicious activity detected
threeDSecureShippingInfo—object of the ThreeDSecureShippingInfo class with shipping details.
address string

Shipping address.

Maximum 150 characters.

addressUsage string First shipping address usage date.

Format: dd-mm-yyyy.

addressUsageIndicator string

Number of days since the first time usage of the shipping address.

Possible values:
  • 01—this transaction
  • 02—less than 30 days ago
  • 03—30−60 days ago
  • 04—more than 60 days ago
city string

Shipping city.

Maximum 50 characters.

country string Shipping country in the ISO 3166-1 alpha-2 format, for example GB.
deliveryEmail string

The email for the digital content delivery.

Maximum 255 characters.

deliveryTime string

Shipment terms.

Possible values:
  • 01—digital delivery
  • 02—same-day delivery
  • 03—overnight delivery
  • 04—longer than overnight delivery
nameIndicator string

Shipment recipient flag.

Possible values:
  • 01—customer and shipment recipient are the same person
  • 02—customer and shipment recipient are different persons
postal string

Shipping postbox number.

Maximum 16 characters.

regionCode string

State, province, or region code in the ISO 3166-2 format. Example: SPE for Saint Petersburg, Russia.

If you specify this parameter, you need also to specify and populate the country parameter in the threeDSecureShippingInfo object.

type string

Shipment indicator.

Possible values:
  • 01—ship to cardholder billing address
  • 02—ship to another verified address on file with merchant
  • 03—ship to address that is different from the cardholder billing address or any verified address on file with merchant
  • 04—ship to local store
  • 05—digital goods shipment
  • 06—no shipment, for instance for travel or event tickets
  • 07—other, for example gaming or subscriptions
threeDSecureMpiResultInfo—object of the threeDSecureMpiResultInfo class with information about previous customer authentication
acsOperationId string The ID the issuer assigned to the previous customer operation. Maximum 36 characters.
authenticationFlow string

The flow the issuer used to authenticate the cardholder in the previous operation.

Possible values:
  • 01—frictionless flow
  • 02—challenge flow
authenticationTimestamp string Date and time of the previous successful customer authentication

Code samples

Figure: Objective-C

ThreeDSecureInfo *threeDSecureInfo = [[ThreeDSecureInfo alloc] init];
 
ThreeDSecurePaymentInfo *threeDSecurePaymentInfo = [[ThreeDSecurePaymentInfo alloc] init];

threeDSecurePaymentInfo.preorderPurchase = @"01";
threeDSecurePaymentInfo.reorder = @"01";

ThreeDSecureCustomerInfo *threeDSecureCustomerInfo = [[ThreeDSecureCustomerInfo alloc] init];

threeDSecureCustomerInfo.workPhone = @"73105219876";
threeDSecureCustomerInfo.addressMatch = @"Y";

threeDSecureInfo.threeDSecurePaymentInfo = threeDSecurePaymentInfo;
threeDSecureInfo.threeDSecureCustomerInfo = threeDSecureCustomerInfo;

[paymentInfo setSecureInfo: threeDSecureInfo];

Figure: Swift

let threeDSecureInfo = ThreeDSecureInfo()
 
let threeDSecurePaymentInfo = ThreeDSecurePaymentInfo()

threeDSecurePaymentInfo.preorderPurchase = "01"
threeDSecurePaymentInfo.reorder = "01"

let threeDSecureCustomerInfo = ThreeDSecureCustomerInfo()

threeDSecureCustomerInfo.addressMatch = "Y"
threeDSecureCustomerInfo.workPhone = "73105219876"

threeDSecureInfo.threeDSecurePaymentInfo = threeDSecurePaymentInfo
threeDSecureInfo.threeDSecureCustomerInfo = threeDSecureCustomerInfo

paymentInfo.setSecureInfo(secureInfo: threeDSecureInfo)