3D Secure 2

The EMVCo have devised a new standard authentication method for payment card transactions: 3D Secure 2 (3DS2).

This new protocol fulfills the Strong Customer Authentication (SCA) requirements set by the EU’s Second Payment Service Directive for online payments within the European Economic Area (EEA).

3D Secure 2 is now available and set to become the prime authentication method for online card payments, thanks to a number of updates that improve not only the security, but also the consumer experience of 3D Secure 1 (3DS).

What is PSD 2?

The Second Payment Service Directive (PSD2) in a Nutshell
  • New Regulation: EU’s Second Payment Service Directive (PSD2) for online payments within the European Economic Area (EEA)

  • Requires: Strong Customer Authentication (SCA)

  • What it is: A measure to combat fraud in card-not-present transactions

  • Who is affected: Issuers, acquirers, and merchants in the EEA

The EU’s Second Payment Service Directive (PSD2) aims to reduce fraud in the European e-commerce sector. Since the largest percentage of all card fraud in Europe happens in card-not-present transactions, the PSD2 makes Strong Customer Authentication (SCA) mandatory for consumer-initiated online payments within the European Economic Area (EEA).

While the regulations defined in PSD2 apply to acquirers and issuers, the effects will also concern EEA merchants and consumers.

To get you ready for SCA, the EMVCo have developed 3D Secure 2, a new authentication protocol for payment card transactions.

What is Strong Customer Authentication (SCA)?

Strong Customer Authentication is a security measure that relies on two-factor authentication to verify the identity of the consumer in a payment transaction. As a result, these factors are strictly consumer-based. SCA can combine two of the following three factors, which must be strictly independent of each other:

  • Knowledge
    This factor relies on the consumer’s unique knowledge of a password or a PIN. Knowledge must not be easily accessible by unauthorized parties. The European Banking Authority (EBA) has determined that credit card number, CVV and expiry date are not valid knowledge, as these are printed on the credit card.

  • Possession
    This factor relies on the consumer’s possession to verify a payment. For example, hardware, such as smartphones and tablets registered to the consumer, can be used as a second verification instance.

  • Inherence
    This factor uses biometrics to verify the consumer’s identity, for example, a fingerprint or a facial scan.

For all payments authenticated with Strong Customer Authentication, as well as those exempted from SCA, the payment service provider must ensure that the fraud rates for online payments are the same as, or lower than the EU reference fraud rate set out in the PSD2.

Exemptions to Strong Customer Authentication

Certain types of transactions may be exempted from Strong Customer Authentication. It is up to your bank/acquirer to request these exemptions for you.

Low Value Transactions
  • SCA does NOT apply to transactions below 30 EUR.

  • SCA does NOT apply when the cumulative amount of previous transactions since the last Strong Customer Authentication does not exceed 100 EUR.

  • SCA does NOT apply when five or less consecutive individual online transactions have been made (remember that in this case, none of those two-to-five payments have been over 30 EUR, and their total does not exceed 100 EUR).

  • The fraud rates for low value transactions must be the same as, or below the EU reference fraud rate for remote electronic card-based payments.

Recurring Transactions
  • SCA needs to apply when the consumer initiates the first in a series of recurring transactions with the same amount and the same merchant.

  • SCA does NOT apply to all subsequent recurring transactions.

  • The fraud rates for recurring transactions must be the same as, or below the EU reference fraud rate for remote electronic card-based payments.

Low-risk transactions
  • SCA does NOT apply to low-risk transactions.

  • To determine whether an online transaction is low-risk, acquirers and issuers may perform real-time risk analysis, to identify, for example, abnormal spending patterns, known fraud scenarios, and abnormal location of the consumer.

  • Low risk transactions can only be exempted if the fraud rates for these transactions are the same as, or below the EU reference fraud rate for remote electronic card-based payments.

White-Listing
  • SCA does NOT apply to online payments from a consumer to a white-listed merchant.

  • Consumers can white-list 'trusted beneficiaries' - merchants of their choice to be included on a list maintained by the consumer’s bank. SCA is only required for the first online transaction.

  • White-listed transactions can only be exempted if the fraud rates for these transactions are the same as, or below the EU reference fraud rate for remote electronic card-based payments.

Secure Corporate Transactions
  • SCA does NOT apply to secure B2B payments via dedicated payment processes and protocols which are not available to consumers.

  • Secure corporate transactions can only be exempted if the fraud rates for these transactions are the same as, or below the EU reference fraud rate for remote electronic card-based payments.

Calculation of Fraud Rates
EU reference fraud rate for remote electronic card-based payments
Exemption Threshold Value (ETV) Fraud Rate

EUR 500

0.01 %

EUR 250

0.06 %

EUR 100

0.13 %

Why Adopt 3D Secure 2?

When 3D Secure 1 was first introduced in 2001, it provided a state-of-the-art fraud prevention system. But the face of e-commerce has changed drastically in the past years. Mobile and in-app payment is booming, a seamless shopping experience more important than ever, and the demands on security growing. The 3D Secure 2 protocol has been designed for this brave new world and offers the flexibility needed to adapt to an ever-changing e-commerce landscape.

3D Secure 2 - The Advantages

  • No more static passwords: The days of rummaging through your drawers to find your 3DS password are over. Consumers will no longer have to look for their passwords and are more likely to complete their purchases.

  • Two-factor authentication: 3DS2 implements two-factor authentication. To make the experience more convenient for consumers, authentication can be completed, for example, with a token and a simple thumbprint.

  • Fewer false declines: The new protocol provides ten times more information to the issuers, which helps drastically reduce the number of false declines. Consumers will retain their trust in 3DS2-secured transactions.

  • Mobile-enabled security: Consumers will no longer be redirected to potentially non-mobile-ready authorization pages.

  • Less cart abandonment: Overall greater convenience, a faster checkout process, and a seamless shopping experience will reduce shopping cart abandonment by 70%.

  • Merchant opt-out: As a merchant, if you decide for 3DS2, you regain the freedom to choose which transactions you send through the protocol and which ones you don’t. However, please keep in mind that issuers may have to decline the transaction because SCA is required on their side.

As with 3DS1, 3D Secure 2 also protects the merchant from liability in cases of fraud.

Supported Card Brands

3D Secure 2 has been developed, and is supported, by Mastercard, VISA, American Express, UPI, Diners Club, Discover, and JCB.

We Help You Transition

Workflow

The 3D Secure 2 workflow remains identical to the 3D Secure 1 workflow.

Payment Processing

3D Secure 1 and 3D Secure 2 include an additional transaction type in the transaction process: check-enrollment.
Check-enrollment is the first step in a 3D Secure transaction. Its purpose is to authenticate the consumer’s identity and confirm the consumer’s willingness to pay the amount specified in the payment transaction. With 3D Secure 2, the amount of data collected with check-enrollment is significantly higher than with 3D Secure 1. This allows a more comprehensive risk analysis.
A successful check-enrollment will return a parent-transaction-id. Include this parent-transaction-id in the next step of the payment process.

For example, you would like to continue to authorize the payment amount:

  1. Send a request with check-enrollment.

  2. The check-enrollment response returns a parent-transaction-id.

  3. Send an authorization request including the parent-transaction-id.

More use cases and common business scenarios are available below. For more details on 3D Secure 2 fields, go to our 3D Secure 2 field table. Need more information on transaction types? Check out Transaction Types for Credit Card.

Check-Enrollment Amount Handling & Policies

Check-enrollment has two functions:

  1. Authenticate the consumer’s identity.

  2. Confirm the consumer’s willingness to pay the amount specified in the payment transaction.

Therefore, a check-enrollment request contains a requested-amount. As a general rule, the amount provided in consecutive payment requests, e.g. during an authorization, should not exceed the amount provided in the referenced check-enrollment by more than what a consumer could reasonably expect. The margin of what is considered reasonable varies from card scheme to card scheme and ranges from 15-20%. As a merchant, you are always on the safe side when the originally requested-amount is not exceeded by 15%.

If you exceed the original requested-amount, the transaction may be declined. However, not all transactions that exceed the original requested-amount will fail. In those cases, chargeback liability protection will not apply to the same extent as for fully authenticated amounts.

Updated Integration Guides

Check out our updated integration guides for WPP v2:

New fields (NVP) have also been added to our Payment Page documentation:

New 3D Secure 2 Fields

We provide a full field reference table for 3D Secure 2.

We recommend sending optional fields, such as account-holder phone numbers and shipping.address. If you submit this information, it is more likely that the Issuer authenticates the consumer without requesting Strong Customer Authentication.
XML Request Datatype Size Description

card.merchant-tokenization-flag

M

Boolean

Indicator whether or not a card token is stored on merchant side.

card.account-type

O

String

2

The type of account, e.g. for a multi-account card product.
Possible values: 01, 02, 03
01 = Not Applicable.
02 = Credit.
03= Debit.
Include this field:

  • If you want consumers to select the account type they are using before completing their purchase.

  • For certain markets, e.g. Brazil.

Otherwise, the field is optional.

account-holder.account-info.authentication-method

O

String

2

Type of consumer login in the merchant’s shop.
Possible values: 01, 02, 03, 04, 05, 06
01 = Guest checkout (i.e. the consumer is not logged in).
02 = Login to the consumer’s account in merchant’s shop with shop-own authentication credentials.
03 = Login with Federated ID.
04 = Login with card issuer credentials.
05 = Login with third-party authentication.
06 = Login with FIDO authenticator.

account-holder.account-info.authentication-timestamp

O

DateTime

20

Date and time (UTC) of the consumer login in the merchant’s shop. Accepted format: YYYY-MM-DDThh:mm:ssZ. For guest checkout, the DateTime is now.

account-holder.account-info.challenge-indicator

O

String

2

Indicates whether a challenge is requested for this transaction.
Possible values: 01, 02, 03, 04
01 = No preference.
02 = No challenge requested.
03 = Challenge requested: Merchant Preference.
04 = Challenge requested: Mandate. Must be sent in a first transaction that stores a token (e.g. for one-click checkout, first recurring payment, installments, UCOF).

If the element is not provided, the ACS will interpret this as 01 = No preference.

account-holder.account-info.creation-date

O

Date

10

Registration date (UTC) of the consumer’s account in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

account-holder.account-info.update-date

O

Date

10

Date that the consumer last made changes to their account in the merchant’s shop. For example, changes to billing and shipping address, new payment account, new email address. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

account-holder.account-info.password-change-date

O

Date

10

Date that the consumer last changed/reset their password in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

account-holder.account-info.shipping-address-first-use

O

Date

10

Date that the consumer first used this shipping address in the merchant’s shop. Accepted format: YYYY-MM-DD. For guest checkout, do not send this field.

account-holder.account-info.transactions-last-day

O

Numeric

9

Number of transactions (successful, failed, and canceled) that the consumer has attempted in the past 24 hours. Does not include merchant-initiated transactions.

account-holder.account-info.transactions-last-year

O

Numeric

9

Number of transactions (successful, failed, and canceled) that the consumer has attempted within the past year. Does not include merchant-initiated transactions.

account-holder.account-info.card-transactions-last-day

O

Numeric

9

Number of cards the consumer has attempted to add to their account in the merchant’s shop for card-on-file payments (one-click checkout) in the past 24 hours.

account-holder.account-info.purchases-last-six-months

O

Numeric

9

Number of successful orders by the consumer in the merchant’s shop within the past six months.

account-holder.account-info.suspicious-activity

O

Boolean

Indicates if the merchant knows of suspicious activities by the consumer (e.g. previous fraud).

account-holder.account-info.card-creation-date

O

Date

10

Date that the consumer’s card was added to their account in the merchant’s shop for card-on-file payments (one-click checkout). Accepted format: YYYY-MM-DD.
For all other types of checkout (e.g. guest checkout, regular checkout, the first transaction with one-click checkout), the date is now.

account-holder.merchant-crm-id

O

String

64

Consumer identifier in the merchant’s shop. Requests that contain payment information from the same consumer in the same shop must contain the same string.

account-holder.address.city

M

String

50

City of the consumer’s billing address.

account-holder.address.country

M

String

2

Country of the consumer’s billing address. Format: ISO 3166-1 alpha-2 country code.

account-holder.address.street1

M

String

50

Line 1 of the street address of the consumer’s billing address.

account-holder.address.street2

O

String

50

Line 2 of the street address of the consumer’s billing address.

account-holder.address.street3

O

String

50

Line 3 of the street address of the consumer’s billing address.

account-holder.address.postal-code

M

String

16

ZIP/postal code of the consumer’s billing address.

account-holder.address.state

O

String

3

State/province of the consumer’s billing address. Accepted format: numeric ISO 3166-2 standard.

account-holder.email

M

String

256

The consumer’s email address as given in the merchant’s shop.

account-holder.phone

O

String

18

Home phone number provided by the consumer.

account-holder.mobile-phone

O

String

18

Mobile phone number provided by the consumer.

account-holder.work-phone

O

String

18

Work phone number provided by the consumer.

account-holder.first-name

M

String

32

The last name provided by the consumer as part of the credit card details.

account-holder.last-name

M

String

32

The last name provided by the consumer as part of the credit card details.

shipping.address.city

O

String

50

City of the consumer’s shipping address. Please provide this field even if billing city is identical.

shipping.address.country

O

String

2

Country of the consumer’s shipping address. Please provide this field even if billing country is identical. Format: ISO 3166-1 alpha-2 country code.

shipping.address.street1

O

String

50

Line 1 of the street address of the consumer’s shipping address. Please provide this field even if billing address is identical.

shipping.address.street2

O

String

50

Line 2 of the street address of the consumer’s shipping address. Please provide this field even if billing address is identical.

shipping.address.street3

O

String

50

Line 3 of the street address of the consumer’s shipping address. Please provide this field even if billing address is identical.

shipping.address.postal-code

O

String

16

ZIP/postal code of the consumer’s shipping address. Please provide this field even if billing address is identical.

shipping.address.state

O

String

3

State/province of the consumer’s shipping address. Accepted format: numeric ISO 3166-2 standard. Please provide this field even if billing address is identical.

shipping.shipping-method

O

String

restriction-based enumeration value

The shipping method chosen by the consumer. Merchants must use the shipping indicator value that applies most accurately to the shipping method. If the consumer checks out two or more items, use the shipping indicator value for physical goods. If all are digital goods, use the shipping indicator value that matches the most expensive item.+ Accepted values are:

  • home_delivery: Ship to consumer’s billing address.

  • verified_address_delivery: Ship to another address known to and verified by the merchant.

  • other_address_delivery: Ship to an address that differs from the consumer’s billing address.

  • store_pick_up: "Ship to Store" / Pick-up at local store (store address in shipping address fields).

  • digital_goods: Digital goods (includes online services, electronic gift cards, and redemption codes).

  • digital_tickets: Travel and event tickets, not shipped.

  • other_verified: Other (e.g. gaming, digital services, e-media subscriptions)

risk-info.delivery-timeframe

O

String

2

The approximate delivery time.
Accepted values are: 01, 02, 03, 04
01 = Electronic delivery
02 = Same-day delivery
03 = Overnight delivery
04 = Two-day or more delivery

risk-info.delivery-mail

O

String

254

The consumer’s email address used for electronic delivery of digital goods.

risk-info.reorder-items

O

String

2

The consumer has previously ordered the same item. Accepted values are: 01, 02
01 = First-time order
02 = Reorder

risk-info.availability

O

String

2

The consumer is placing an order for merchandise that is not yet available and will be released in the future. Accepted values are: 01, 02
01 = Currently available
02 = Future availability

risk-info.preorder-date

O

Date

10

Expected shipping date for pre-ordered goods. Accepted format: YYYY-MM-DD.

risk-info.gift-cards.gift-card@id

O

Numeric

2

For prepaid and gift card purchase only. Identifies individual gift cards. Information about up to 10 gift cards can be sent in one request. Accepted values range from 1 to 10.

risk-info.gift-cards.gift-card.amount

O

Decimal

18,2

For prepaid and gift card purchase only. The amount paid with a specific gift card. The field allows decimal values (e.g. 10.50).

risk-info.gift-cards.gift-card.amount@currency

O

String

3

For prepaid and gift card purchase only. The ISO 4217 three-digit currency code of the gift card.

periodic.recurring-expire-date

O

Date

10

For recurring payments. Required only for authentication of the first transaction. Date after which further recurring payments with this card are no longer allowed. Accepted format: YYYY-MM-DD.

periodic.recurring-frequency

O

Numeric

4

For recurring payments. Required only for authentication of the first transaction. Indicates the minimum number of days between individual authorizations.

periodic.number-of-installments

O

Numeric

3

For installment payments. Required only for authentication of the first transaction. Indicates the maximum number of authorizations permitted for installment payments.

iso-transaction-type

O

String

2

Identifies the transaction type. The values are derived from ISO 8583. Accepted values are: 01, 03, 10, 11, 28
01 = Goods/Service Purchase
03 = Check Acceptance
10 = Account Funding
11 = Quasi-Cash Transaction
28 = Prepaid Activation and Load

browser.accept

O

String

2048

This is the HTTP Accept Header as retrieved from the consumer’s browser in the HTTP request. If the string is longer than 2048, it must be truncated. It is strongly recommended to provide this field to prevent rejection from the ACS server.

browser.user-agent

O

String

256

This is the User Agent as retrieved from the consumer’s browser in the HTTP request. If it is longer than 256 bytes it must be truncated. It is strongly recommended to provide this field to prevent rejection from the ACS server.

browser.java-enabled

O

Boolean

Boolean that represents the ability of the cardholder browser to execute Java.
Value is returned from the navigator.javaEnabled property.

browser.language

O

String

8

Value representing the browser language as defined in IETF BCP47. The value is limited to 1-8 characters.
Value is returned from navigator.language property.

browser.color-depth

O

Numeric

2

Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from consumer browser using the screen.colorDepth property.
Accepted values are: 1, 4, 8, 15, 16, 24, 32, 48

browser.screen-resolution

O

String

12

Total height and width of the consumer’s screen in pixels. Value is returned from the screen.height and screen.width properties.

browser.challenge-window-size

O

String

2

Dimensions of the challenge window as displayed to the consumer. The ACS replies with content that is formatted to correctly render in this window to provide the best possible user experience.
Preconfigured sizes are width X height in pixels of the window displayed in the consumer’s browser window. This is used only to prepare the CReq request and it is not part of the AReq flow. If not present, it will be omitted.
Accepted values are: 01, 02, 03, 04, 05
01 = 250 x 400
02 = 390 x 400
03 = 500 x 600
04 = 600 x 400
05 = Full screen

three-d.version

O

String

5

Identifies the version of 3D Secure authentication used for the transaction. Accepted values are: 1.0, or 2.1. If the version is not entered in the request, the field defaults to 1.0.

three-d.ds-transaction-id

O

String

36

Unique transaction identifier assigned by the Directory Server to identify a single transaction. Required for external 3D Secure servers not provided by Wirecard. Format: see IETF RFC 4122.

three-d.riid

O

String

2

For 3D Secure 2.2. Indicates the type of 3RI request.
Accepted values are: 01, 02, 03, 04, 05
01 = Recurring transaction
02 = Installment transaction
03 = Add card
04 = Maintain card information
05 = Account

3D Secure Workflows

3D Secure Workflow
3D Secure 2.1 Frictionless Flow (Issuer supports 3D Secure 2)
3D Secure 2 Frictionless Workflow

1. Check-enrollment: This first step initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.
1.1 Consumer (cardholder) checkout on your payment page.

1.2 Initiate the payment session with Wirecard Payment Gateway using the check-enrollment transaction type. Provide additional fields for 3D Secure 2 transactions. 3D Secure 2 fields can be found in the 3D Secure 2 field table and are included in the REST API payment XSD.

1.3 Wirecard Payment Gateway checks the 3D Secure version supported by the issuer with the 3D Secure server.
1.4 Wirecard Payment Gateway returns the check-enrollment response. It includes the PAReq, the ACS URL, and the 3D Secure version.

2. Redirect the consumer to the ACS URL
2.1 Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.
2.2 The ACS URL points to the public endpoint of the Wirecard 3D Secure Router which decodes the <PAReq>.
2.3 The Wirecard 3D Secure Router returns an HTML with the scheme logo and a "processing" screen which is displayed in the consumer’s browser.
2.4 The Wirecard 3D Secure Router redirects the consumer to the 3DSMethodURL for device fingerprinting.
2.5 The Issuer ACS gathers the information and redirects the 3D Secure method completion information to the Wirecard 3D Secure Router URL.
2.6 The Wirecard 3D Secure Router initiates authentication with the issuer’s ACS via the scheme directory server.
2.7 The Wirecard 3D Secure Router posts the SSL-encrypted and digitally signed PARes (Payment Authentication response) to the TermURL via the consumer’s browser.

3. Check-payer-response (optional) and PARes verification: Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway. The check-payer-response provides the authentication values needed later for completion of the payment transaction. It is executed after you receive the check-enrollment response and the PARes.
3.1 Send a POST request with transaction type check-payer-response to Wirecard Payment Gateway. Provide the parent-transaction-id using the transaction-id from the check-enrollment response, and the PARes.
3.2 Wirecard Payment Gateway decodes the PARes, checks the signature and retrieves the final authentication values.
3.3 Wirecard Payment Gateway returns the final authentication values in the response of the check-payer-response transaction. These include the dsTransId, CAAV/AVV, ECI, and authenticationStatus.

4. Complete the payment transaction: Proceed with the payment transaction with the relevant transaction-type (e.g. authorization, purchase, authorization-only). Use the final authentication values received either from the check-enrollment response(e.g. PARes and parent-transaction-id), or from step 3.3 (check-payer-response response).

3D Secure 2.1 Challenge Flow (Issuer supports 3D Secure 2)
3D Secure 2 Challenge Workflow

1. Check-enrollment: This first step initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.
1.1 Consumer (cardholder) checkout on your payment page.

1.2 Initiate the payment session with Wirecard Payment Gateway using the check-enrollment transaction type. Provide additional fields for 3D Secure 2 transactions. 3D Secure 2 fields can be found in the 3D Secure 2 field table and are included in the REST API payment XSD.

1.3 Wirecard Payment Gateway checks the 3D Secure version supported by the issuer with the 3D Secure server.
1.4 Wirecard Payment Gateway returns the check-enrollment response. It includes the PAReq, the ACS URL, and the 3D Secure version.

2. Redirect the consumer to the ACS URL
2.1 Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.
2.2 The ACS URL points to the public endpoint of the Wirecard 3D Secure Router which decodes the <PAReq>.
2.3 The Wirecard 3D Secure Router returns an HTML with the scheme logo and a "processing" screen which is displayed in the consumer’s browser.
2.4 The Wirecard 3D Secure Router redirects the consumer to the 3DSMethodURL for device fingerprinting.
2.5 The Issuer ACS gathers the information and redirects the 3D Secure method completion information to the Wirecard 3D Secure Router URL.
2.6 The Wirecard 3D Secure Router initiates authentication with the issuer’s ACS via the scheme directory server.
2.7 The Wirecard 3D Secure Router redirects the consumer to the ACS which displays a challenge window (either a page or an iframe).
2.8 The consumer enters their data. After successful authentication, the ACS sends the challenge response to the Wirecard 3D Secure Router.
2.9 The Wirecard 3D Secure Router posts the SSL-encrypted and digitally signed PARes (Payment Authentication response) to the TermURL via the consumer’s browser.

3. Check-payer-response (optional) and PARes verification: Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway. The check-payer-response provides the authentication values needed later for completion of the payment transaction. It is executed after you receive the check-enrollment response and the PARes.
3.1 Send a POST request with transaction type check-payer-response to Wirecard Payment Gateway. Provide the parent-transaction-id using the transaction-id from the check-enrollment response, and the PARes.
3.2 Wirecard Payment Gateway decodes the PARes, checks the signature and retrieves the final authentication values.
3.3 Wirecard Payment Gateway returns the final authentication values in the response of the check-payer-response transaction. These include the dsTransId, CAAV/AVV, ECI, and authenticationStatus.

4. Complete the payment transaction: Proceed with the payment transaction with the relevant transaction-type (e.g. authorization, purchase, authorization-only). Use the final authentication values received either from the check-enrollment response (e.g. PARes and parent-transaction-id), or from step 3.3 (check-payer-response response).

3D Secure 2.1 Flow with Fallback to 3D Secure 1 (Issuer does not support 3D Secure 2)
3D Secure 2 Fallback Workflow

1. Check-enrollment: This first step initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.
1.1 Consumer (cardholder) checkout on your payment page.

1.2 Initiate the payment session with Wirecard Payment Gateway using the check-enrollment transaction type. Provide additional fields for 3D Secure 2 transactions. 3D Secure 2 fields can be found in the 3D Secure 2 field table and are included in the REST API payment XSD.

1.3 Wirecard Payment Gateway checks the 3D Secure version supported by the issuer with the 3D Secure server. If 3D Secure 2 is not supported then the 3D Secure server initiates the fallback to version 1 via the 3D Secure MPI.
1.4 Wirecard Payment Gateway returns the check-enrollment response. It includes the PAReq, the ACS URL, and the 3D Secure version.

2. Redirect the consumer to the ACS URL
2.1 Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.
2.2 The ACS URL points to the public endpoint of the issuer ACS, which decodes the <PAReq>. The ACS displays the authentication window for the cardholder.
2.3 The consumer enters their data in the authentication window displayed by the ACS.
2.4 The issuer ACS verifies the authentication credentials and posts the SSL-encrypted and digitally signed PARes (Payment Authentication response), as well as the <MD> to the TermURL via the consumer’s browser.

3. Check-payer-response (optional) and PARes verification: Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway. The check-payer-response provides the authentication values needed later for completion of the payment transaction. It is executed after you receive the check-enrollment response and the PARes.
3.1 Send a POST request with transaction type check-payer-response to Wirecard Payment Gateway. Provide the parent-transaction-id using the transaction-id from the check-enrollment response, and the PARes.
3.2 Wirecard Payment Gateway verifies the PARes with the 3D Secure MPI and receives the final authentication values.
3.3 Wirecard Payment Gateway returns the final authentication values in the response of the check-payer-response transaction. These include the XID, CAAV/AVV, ECI, and authenticationStatus.

4. Complete the payment transaction: Proceed with the payment transaction with the relevant transaction-type (e.g. authorization, purchase, authorization-only). Use the final authentication values received either from the check-enrollment response (e.g. PARes and parent-transaction-id), or from step 3.3 (check-payer-response response).

3D Secure 2 Payment Flows

The 3D Secure 2 workflow remains identical to the 3D Secure 1 workflow.

For typical business scenarios that apply these payment flows, head to our 3D Secure 2 Use Cases page.


One-Time Payment Transaction

Authentication required: Yes
Card-on-file flagging required: No

Option 1: One-Step Payment with Authentication
API CC 3DS2 PaymentFlows OneTimePaymentTransaction OneStep
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 transactions, include the new field three-d/version and set its value to 2.1.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <three-d>
        <version>2.1</version>
    </three-d>

    transaction-type

    check-enrollment

    three-d/version

    2.1

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process will be aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

Option 2: Two-Step Payment with Authentication
API CC 3DS2 PaymentFlows OneTimePaymentTransaction TwoStep
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 transactions, include the new field three-d/version and set its value to 2.1.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <three-d>
        <version>2.1</version>
    </three-d>

    transaction-type

    check-enrollment

    three-d/version

    2.1

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the authorization. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Authorization:This step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>

    transaction-type

    authorization

    parent-transaction-id

    three-d/pares

  5. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


First Payment and Consumer-Initiated (CI) One-Click Checkout

Authentication required: Yes
Card-on-file flagging required: Yes

First Payment with Authentication
API CC 3DS2 PaymentFlows FirstPaymentCICheckout First
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    three-d/version

    2.1

    periodic/periodic-type

    ci

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

      It is not required to set the check-payer-response to ci (consumer-initiated).
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ci (consumer-initiated).
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ci

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

Option 1: Subsequent One-Step Payment with Authentication
API CC 3DS2 PaymentFlows FirstPaymentCICheckout SubsequentOptionOne
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 transactions, include the new field three-d/version and set its value to 2.1. Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    It is not required to include the parent-transaction-id or set challenge-indicator to 04.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    three-d/version

    2.1

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (Optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to ci (consumer-initiated) and recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

Option 2: Subsequent Two-Step Payment with Authentication
API CC 3DS2 PaymentFlows FirstPaymentCICheckout SubsequentOptionTwo
  1. Check-enrollment: This is the initial request and initiates the payment session. New 3D Secure 2 fields can be found in the 3D Secure 2 field table. They are also included in the REST API payment XSD.

    For 3D Secure 2 transactions, include the new field three-d/version and set its value to 2.1. Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    It is not required to include the parent-transaction-id or set challenge-indicator to 04.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    three-d/version

    2.1

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) are posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the authorization. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to ci (consumer-initiated) and recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Authorization: This step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

  5. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    It is not required to set the capture-authorization to ci (consumer-initiated) and recurring.
    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


Storing Credit Card Credentials and Subsequent Consumer-Initiated (CI) One-Click Checkout

Authentication required: Yes
Card-on-file flagging required: Yes

Storing Card Credentials (Reserve and Void Amount) with Authentication
API CC 3DS2 PaymentFlows StoringCardCredentials AuthAndVoid
  1. Check-enrollment: This is the initial request and initiates the payment session. New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    three-d/version

    2.1

    periodic/periodic-type

    ci

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the authorization. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to ci (consumer-initiated) and recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Authorization: This step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ci (consumer-initiated).
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ci

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

  5. Void-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>void-authorization</transaction-type>
    <parent-transaction-id>25fee53e-2a44-46e5-b600-0875cc732974</parent-transaction-id>

    transaction-type

    void-authorization

    parent-transaction-id

Subsequent One-Step Payment with Authentication
API CC 3DS2 PaymentFlows StoringCardCredentials Subsequent
  1. Check-enrollment: This is the initial request and initiates the payment session. New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 transactions, include the new field three-d/version and set its value to 2.1. Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    The token-id can be used instead of the account-number. It is not required to include the parent-transaction-id or set challenge-indicator to 04.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <card-token>
        <token-id>4304509873471003</token-id>
    </card-token>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    card-token/token-id

    three-d/version

    2.1

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (Optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to ci (consumer-initiated) and recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ci</periodic-type>
        <sequence-type>recurring</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ci

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true


Merchant-Initiated Transaction (MIT): First Payment and Scheduled Subscription

Authentication required: Yes; only for the initial transaction
Card-on-file flagging required: Yes

First Payment (One-Step) with Authentication - Consumer-Initiated
API CC 3DS2 PaymentFlows MIT FirstPaymentAndSubscription First
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to recurring and the sequence-type to first. Include the recurring-expire-date and recurring-frequency.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>first</sequence-type>
        <recurring-expire-date>YYYY-MM-DD</recurring-expire-date>
        <recurring-frequency>xxxx</recurring-frequency>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    three-d/version

    2.1

    periodic/periodic-type

    recurring

    periodic/sequence-type

    first

    periodic/recurring-expire-date

    YYYY-MM-DD

    periodic/recurring-frequency

    xxxx

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set the periodic-type to recurring.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    recurring

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

Subsequent Payment without Authentication

Option 1: One-Step Merchant Initiated Transaction (MIT)

  1. Purchase: This final step in the transaction flow must reference the initial recurring transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Set the sequence-type to recurring.

    Set the periodic-type to recurring.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    periodic/periodic-type

    recurring

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

Option 2: Two-Step Merchant Initiated Transaction (MIT)

API CC 3DS2 PaymentFlows RecurringMIT StoringCCAndSubscription TwoStep
  1. Authorization: The authorization in the transaction flow must reference the initial recurring transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Include sequence-type set to recurring or final.

    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    periodic/periodic-type

    recurring

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

  2. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


Recurring Merchant-Initiated Transaction (MIT): Storing Credit Card Credentials and Scheduled Subscription

Authentication required: Yes; only for the initial transaction
Card-on-file flagging required: Yes

Storing Card Credentials (Reserve and Void Amount) with Authentication
API CC 3DS2 PaymentFlows RecurringMIT StoringCCAndSubscription AuthAndVoid
  1. Check-enrollment: This is the initial request and initiates the payment session. New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to recurring and the sequence-type to first. Include the recurring-expire-date and recurring-frequency.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>first</sequence-type>
        <recurring-expire-date>YYYY-MM-DD</recurring-expire-date>
        <recurring-frequency>xxxx</recurring-frequency>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    three-d/version

    2.1

    periodic/periodic-type

    recurring

    periodic/sequence-type

    first

    periodic/recurring-expire-date

    YYYY-MM-DD

    periodic/recurring-frequency

    xxxx

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process will be aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the authorization. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to recurring.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Authorization: This step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to recurring.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    recurring

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

  5. Void-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>void-authorization</transaction-type>
    <parent-transaction-id>25fee53e-2a44-46e5-b600-0875cc732974</parent-transaction-id>

    transaction-type

    void-authorization

    parent-transaction-id

Option 1: One-Step Merchant Initiated Transaction (MIT)
  1. Purchase: This final step in the transaction flow must reference the initial recurring transaction. Include the transaction-id from the initial authorization response in the parent-transaction-id field. Set the sequence-type to recurring.

    Set the periodic-type to recurring.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    periodic/periodic-type

    recurring

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

Option 2: Two-Step Merchant Initiated Transaction (MIT)
API CC 3DS2 PaymentFlows RecurringMIT StoringCCAndSubscription TwoStep
  1. Authorization: The authorization in the transaction flow must reference the initial recurring transaction. Include the transaction-id from the initial authorization response in the parent-transaction-id field. Set sequence-type to recurring or final.

    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>recurring</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    periodic/periodic-type

    recurring

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

  2. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


Installment as Merchant-Initiated Transaction (MIT): First Payment and Scheduled Installment

Authentication required: Yes; only for the initial transaction
Card-on-file flagging required: Yes

First Payment (One-Step) with Authentication - Consumer-Initiated
Check-enrollment with installment is currently under development and will be made available with the next update release.
API CC 3DS2 PaymentFlows InstallmentMIT FirstPaymentAndInstallment FirstCI
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to installment and the sequence-type to first.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <three-d>
        <version>2.1</version>
    </three-d>
    <periodic>
        <periodic-type>installment</periodic-type>
        <sequence-type>first</sequence-type>
        <number-of-installments>xxx</number-of-installments>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    three-d/version

    2.1

    periodic/periodic-type

    installment

    periodic/sequence-type

    first

    periodic/number-of-installments

    xxx

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to set the check-payer-response to installment.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to installment.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>installment</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    installment

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

Option 1: One-Step Merchant Initiated Transaction (MIT)
  1. Purchase: This final step in the transaction flow must reference the initial installment transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Set the sequence-type to recurring or final.

    Set the periodic-type to installment.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>installment</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    periodic/periodic-type

    installment

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

Option 2: Two-Step Merchant Initiated Transaction (MIT)
API CC 3DS2 PaymentFlows InstallmentMIT SubsequentNoAuth TwoStep
  1. Authorization: The authorization in the transaction flow must reference the initial installment transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Set sequence-type to recurring or final.

    Set the periodic-type to installment.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>installment</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    periodic/periodic-type

    installment

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

  2. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


Merchant Initiated Transaction (MIT) with Unscheduled Credentials on File (UCOF): First Payment and Unscheduled Subsequent MIT

Authentication required: Yes; only for the initial transaction
Card-on-file flagging required: Yes

First Payment (One-Step) with Authentication - Consumer-Initiated
API CC 3DS2 PaymentFlows MITUCOF FirstAndUnscheduledMIT FirstPayment
  1. Check-enrollment: This is the initial request in a 3D Secure 2 payment flow. It initiates the payment session and checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to ucof and the sequence-type to first.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <three-d>
        <version>2.1</version>
    </three-d>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    periodic/periodic-type

    ucof

    periodic/sequence-type

    first

    three-d/version

    2.1

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the purchase. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Purchase: This final step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ucof and the sequence-type to first.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ucof

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

Option 1: One-Step Merchant Initiated Transaction (MIT)
  1. Purchase: This final step in the transaction flow must reference the initial ucof transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Set the sequence-type to recurring.

    Set the periodic-type to ucof.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    periodic/periodic-type

    ucof

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

Option 2: Two-Step Merchant Initiated Transaction (MIT)
API CC 3DS2 PaymentFlows MITUCOF Subsequent NoAuth TwoStepMIT
  1. Authorization: The authorization in the transaction flow must reference the initial ucof transaction. Include the transaction-id from the initial purchase response in the parent-transaction-id field. Set sequence-type to recurring or final.

    Set the periodic-type to ucof.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    periodic/periodic-type

    ucof

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

  2. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id


Merchant Initiated Transaction (MIT) with Unscheduled Credentials on File (UCOF): Storing Credit Card Credentials and Unscheduled Subsequent MIT

Authentication required: Yes; only for the initial transaction
Card-on-file flagging required: Yes

No amount due at sign-up.
Storing Card Credentials (Reserve and Void Amount) with Authentication
API CC 3DS2 PaymentFlows MITUCOF StoringCard AuthAndVoid
  1. Check-enrollment: This is the initial request and initiates the payment session. New 3D Secure 2 fields can be found in the 3D Secure 2 field table.
    They are also included in the REST API payment XSD.

    For 3D Secure 2 consumer-initiated (CI) one-click checkout, include the new field three-d/version and set its value to 2.1. Set challenge-indicator to 04. Set the periodic-type to ucof and sequence-type to first.
    XML Fields
    <transaction-type>check-enrollment</transaction-type>
    <account-holder>
        <account-info>
            <challenge-indicator>04</challenge-indicator>
        </account-info>
    </account-holder>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <three-d>
        <version>2.1</version>
    </three-d>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    check-enrollment

    account-holder/account-info/challenge-indicator

    04

    periodic/periodic-type

    ucof

    periodic/sequence-type

    first

    three-d/version

    2.1

    card/merchant-tokenization-flag

    true

    As a result of the check-enrollment, you receive the PAReq with the ACS URL.

  2. Redirect the consumer to the ACS URL: Send an HTTPS POST request including the ACS URL, the <PAReq>, the <TermUrl> and <MD>.

    • The <TermUrl> is the web address of your server to receive the PARes (Payment Authentication response).

    • The <MD> is a hidden input parameter reserved for specific merchant data. The <MD> may be useful for retrieving transaction data from the database or recalling a transaction.

      You do not need to define the <MD> value.
      This field is mandatory. If you omit the <MD> input type, an authentication error will occur and the payment process is aborted.
    Example: Auto Submission POST Request
    <html>
       <head>
          <meta HTTP-EQUIV="Content-Type" content="text/html; charset=UTF-8" />
          <meta HTTP-EQUIV="Cache-Control" CONTENT="no cache" />
          <meta HTTP-EQUIV="Pragma" CONTENT="no cache" />
          <meta HTTP-EQUIV="Expires" CONTENT="0" />
       </head>
       <body OnLoad="AutoSubmitForm();">
          <form name="downloadForm" action="AcsUrl" method="POST">
             <input type="hidden" name="PaReq" value="PaReq" />
             <input type="hidden" name="TermUrl" value="TermUrl" />
             <input type="hidden" name="MD" value="optionalValue" />
             <SCRIPT LANGUAGE="Javascript">
                <!--function AutoSubmitForm() { document.downloadForm.submit();}//-->
             </SCRIPT>
             <input type="submit" name="continue" value="Continue" />
          </form>
       </body>
    </html>

    Once the consumer has been redirected, they receive an authentication prompt. The consumer enters their data. After successful authentication, the SSL-encrypted and digitally signed PARes (Payment Authentication response) will be posted to the TermURL via the consumer’s browser.

  3. Check-payer-response (optional): Use this request to receive, analyze and store authentication values on your side or use your connection to the Wirecard Payment Gateway for the "MPI Only" option. The check-payer-response provides the authentication values needed later on in the authorization. It is executed after you receive the check-enrollment response and the PARes. The check-payer-response must contain the following fields:

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response.

    It is not required to include periodic in the check-payer-response.
    XML Fields
    <transaction-type>check-payer-response</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfvdXWDmPnr2ZRHCX8VQziKCgyCDyx....</pares>
    </three-d>

    transaction-type

    check-payer-response

    parent-transaction-id

    three-d/pares

  4. Authorization: This step in the transaction flow must reference either the previous check-enrollment, or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    1. Following check-enrollment: Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    2. Following (optional) check-payer-response: Include the transaction-id returned by the check-payer-response in the parent-transaction-id field.

    If the check-payer-response was not executed, instead use the PARes received via TermURL as part of the response to the ACS HTTP POST request.

    Set the periodic-type to ucof and to sequence-type to first.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>fa377563-e89d-420e-ab6f-d9d368e6acaa</parent-transaction-id>
    <three-d>
        <pares>eJydV1lzqsoWfv.......</pares>
    </three-d>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>first</sequence-type>
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    three-d/pares

    periodic/periodic-type

    ucof

    periodic/sequence-type

    first

    card/merchant-tokenization-flag

    true

  5. Void-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>void-authorization</transaction-type>
    <parent-transaction-id>25fee53e-2a44-46e5-b600-0875cc732974</parent-transaction-id>

    transaction-type

    void-authorization

    parent-transaction-id

Option 1: One-Step Merchant Initiated Transaction (MIT)
  1. Purchase: This final step in the transaction flow must reference the initial ucof transaction. Include the transaction-id from the initial authorization response in the parent-transaction-id field. Set the sequence-type to recurring (or final for the last recurring transaction).

    Set the periodic-type to ucof.
    XML Fields
    <transaction-type>purchase</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    purchase

    parent-transaction-id

    periodic/periodic-type

    ucof

    periodic/sequence-type

    recurring

    card/merchant-tokenization-flag

    true

Option 2: Two-Step Merchant Initiated Transaction (MIT)
API CC 3DS2 PaymentFlows MITUCOF StoringCard TwoStepMIT
  1. Authorization: The authorization in the transaction flow must reference the initial ucof transaction. Include the transaction-id from the initial authorization response in the parent-transaction-id field. Set sequence-type to recurring or final.

    Set the periodic-type to ucof.
    XML Fields
    <transaction-type>authorization</transaction-type>
    <parent-transaction-id>9bd387fd-e4ac-46d4-905a-b34382801cbb</parent-transaction-id>
    <periodic>
        <periodic-type>ucof</periodic-type>
        <sequence-type>recurring</sequence-type> (or
        <sequence-type>final</sequence-type> in case of the last recurring transaction)
    </periodic>
    <card>
        <merchant-tokenization-flag>true</merchant-tokenization-flag>
    </card>

    transaction-type

    authorization

    parent-transaction-id

    periodic/periodic-type

    ucof

    periodic/sequence-type

    recurring or final

    card/merchant-tokenization-flag

    true

  2. Capture-authorization: This step in the transaction flow must reference the transaction-id from the authorization response in the parent-transaction-id field.

    XML Fields
    <transaction-type>capture-authorization</transaction-type>
    <parent-transaction-id>df92ce59-a39c-4e2d-a5d6-c3f952826acd</parent-transaction-id>

    transaction-type

    capture-authorization

    parent-transaction-id

3D Secure 2 Use Cases

The following list covers the most typical use cases and business scenarios. Please keep in mind that other transaction workflows are possible. For standard check-enrollment request and response samples, head to our Credit Card Samples section. You can find more details on the implementation of these use cases in our 3D Secure 2 Payment Flows.

One-time Purchase

One-time purchase is one of the most common scenarios: a consumer places an order for a product or service. The merchant fulfills the order in a single shipment and before expiration of the authorization.

For a successful transaction:
  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.
    See the XML request/response samples for check-enrollment.

  2. Authorization (full amount): Send a second request with transaction type authorization. Include the transaction-id from the check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

    When ready to ship…​

  3. Capture (full amount): Send a third request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field.


Delayed Shipment

A consumer places an order for a product or service. The merchant fulfills the order in a single shipment, but with a delay. This delay may be expected or unexpected and could exceed the expiration date of the authorization.

Pre-authorization is valid longer than a regular authorization.
For a successful transaction:
Option 1: Expected delay
  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to validate the credit card data.

    When ready to ship…​

  3. Authorization (full amount): Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

  4. Capture (full amount): Send a request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field.

Option 2: Unexpected delay
  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. (Pre-)authorization (full amount): Send a second request with transaction type (pre-)authorization. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    When exceeding the expiration date of the authorization

  3. Void-authorization: Send a request with transaction type void-authorization. Include the transaction-id from the (pre-)authorization response in the parent-transaction-id field.

    When ready to ship (MIT)…​

  4. Authorization (full amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. Include the transaction-id from the (pre-)authorization response in the parent-transaction-id field.

  5. Capture (full amount): Send a request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field.


Partial/ Split Shipment

A consumer places an order for a product or service. The merchant fulfills the order in multiple shipments.

For a successful transaction:
Option 1: Without delay
  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization (full amount): Send a second request with transaction type authorization. Include the transaction-id from the check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

    Whenever a remaining part of the order is ready to ship

  3. Capture (partial amount): Send a third request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field. Capture every individual shipment.

Option 2: With (partial) delay (if shipping takes longer than authorization is valid)
  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization (full amount): Send a second request with transaction type authorization. Include the transaction-id from the check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

    Whenever a part of the order is ready to ship

  3. Capture (partial amount): Send a third request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field. Capture every individual shipment.

    When authorization expires

  4. Void-authorization (remaining amount): Void the remaining amount with a void-authorization request.

    Whenever a remaining part of the order is ready to ship

  5. Authorization (remaining amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request.

  6. Capture the remaining amount. Capture every individual shipment.


Recurring Payments - Same Amount (Merchant-Initiated Transaction)

Recurring transactions are processed at regular intervals, with the same, recurring amount. When you set up a recurring merchant-initiated transaction (MIT) agreement, the first transaction requires Strong Customer Authentication (one-time only). A common business scenario would be subscription fees for a software-as-a-service (SaaS) solution, or for video streaming services.

Consumers must be clearly informed about the terms of the agreement when setting up the recurring payment plan.
Option 1: Amount due at sign-up (no trial period)

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (amount due at sign-up): This is the initial request and initiates the payment session. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization (amount due at sign-up): Send a request with transaction type authorization. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment.

  3. Capture (amount due at sign-up): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

    Recurring payment (MIT)

  4. Authorization (recurring amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the first authorization response in the parent-transaction-id field (see step 2).

  5. Capture (recurring amount): Send a request with transaction type capture. Include the transaction-id from the second authorization response in the parent-transaction-id field.

Option 2: No amount due at sign-up (with trial period)

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (zero amount): This is the initial request and initiates the payment session. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to sign the payment agreement. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    Per recurring payment (MIT)

  3. Authorization (recurring amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>recurring</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the authorization-only response in the parent-transaction-id field (see step 2).

  4. Capture (recurring amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.


Recurring Payments - Variable Amount (MIT Unscheduled Credential on File - UCOF)

For recurring payments with a variable amount, the consumer agrees that the merchant may initiate one or more transactions in the future. These merchant-initiated UCOF (Unscheduled Credential on File) transactions use stored credentials. The transactions are unscheduled and happen in irregular intervals. The payment amount is either fixed or variable. UCOF merchant-initiated transaction agreements have to be set up with Strong Customer Authentication. Examples include automatic top-up transactions, e.g. for mobile phones and online gaming.

Consumers must be clearly informed about the terms of the unscheduled credential on file at the time of sign-up.
Option 1: Amount due at sign-up

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (amount due at sign-up): This is the initial request. It initiates the payment session and the agreement set-up. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization (amount due at sign-up): Send a request with transaction type authorization. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment.

  3. Capture (amount due at sign-up): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

    Per UCOF payment (MIT)

  4. Authorization (UCOF amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the first authorization response in the parent-transaction-id field (see step 2).

  5. Capture (UCOF amount): Send a request with transaction type capture. Include the transaction-id from the UCOF authorization response in the parent-transaction-id field.

Option 2: No amount due at sign-up

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (zero amount): This is the initial request. It initiates the payment session and the agreement set-up. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to sign the payment agreement. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    Per UCOF payment (MIT)

  3. Authorization (UCOF amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>ucof</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the authorization-only response in the parent-transaction-id field (see step 2).

  4. Capture (UCOF amount): Send a request with transaction type capture. Include the transaction-id from the UCOF authorization response in the parent-transaction-id field.


General Multi-Party Commerce

The consumer buys a product or service from a merchant. At the time of purchase, the consumer acquires an additional product or service provided by a separate merchant. This separate merchant charges for the additional product or service. For example, the consumer purchases a washing machine and a breakdown and repair insurance.

For a successful transaction:

The consumer-facing merchant (i.e. where the consumer buys the primary product or service, e.g. the washing machine) sends the following requests:

  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization (amount due with consumer-facing merchant): Send a second request with transaction type authorization. Include the transaction-id from the check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

  3. Capture (amount due with consumer-facing merchant): Send a third request with transaction type capture. Include the transaction-id from the previous authorization response in the parent-transaction-id field.

    Each merchant (when ready to ship / deliver)…​

  4. Authorization (remaining amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope for SCA; therefore, check-enrollment is not required prior to this request.

  5. Capture the remaining amount.


Agent Model

The consumer interacts with an agent that is selling another merchant’s product or service. Payments are triggered by merchants. One example for this would be an online travel agency.

Agents must clearly inform consumers that their cards will be charged by merchants, and not them.
For a successful transaction:
Option 1: You are an agent with Wirecard

The agent initiates the payment session:

  1. Check-enrollment (full amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id, and the three-d/pareq. The PAReq is the digitally signed, base64-encoded authentication request message created by Wirecard Payment Gateway. It contains the results of the 3D Secure versioning request that is used to initiate AReq as part of the HTTPS POST redirect to the ACS URL. The agent uses the PAReq for a HTTPS POST redirect to the ACS URL, which is part of a standard 3D Secure process. The HTTPS POST redirect returns the PARes as part of the response.

  2. Check-payer-response: This request serves to provide the authentication values needed later on in the authorization. The check-payer-response is executed after the check-enrollment response and the PARes have been received. The check-payer-response must contain the following fields

    • three-d/pares: This is the digitally signed, base64-encoded authentication response message containing ARes/CRes received from the issuer.

    • parent-transaction-id: Use the value returned in the transaction-id field of the check-enrollment response. The check-payer-response includes the three-d/cardholder-authentication-value.

      Provide the final authentication values for the merchant. These values include:

    • three-d/cardholder-authentication-value

    • three-d/eci

    • three-d/ds-transaction-id

    • three-d/version

    • three-d/cardholder-authentication-status

Option 2: You are a merchant with Wirecard

As a merchant you receive the following authentication values from your external 3D Secure provider (e.g. the agent):

  • three-d/cardholder-authentication-value (Mandatory)

  • three-d/eci (Mandatory)

  • three-d/ds-transaction-id (Mandatory)

  • three-d/version (Mandatory)

  • three-d/cardholder-authentication-status (Optional)

Merchant (when ready to ship / deliver)…​

  1. Authorization (full amount): Include the authentication values provided by the external 3D Secure provider.

  2. Capture (full amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.


Open Orders (with an unknown payment amount before purchase)

The consumer places an order for a certain amount. However, the amount is expected to change by the time of shipping. For example, this could apply to orders where a shipping date is booked several days or weeks in advance, but the shopping cart contents can be changed until the time of shipping.

For a successful transaction:
Option 1: Initial order amount
  1. Check-enrollment (initial order amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to validate the credit card data.

    If the shopping cart content changes and the new total amount exceeds the original amount

  3. Check-enrollment (new total amount): To authenticate the new total amount, a new check-enrollment is needed. If the request is successful, the response contains a transaction-id.

    When ready to ship…​

  4. Authorization (latest enrolled amount): Send a request with transaction type authorization. Include the transaction-id from the latest check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

  5. Capture (latest enrolled amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

This option is more expensive because more enrollment-checks are necessary.
Option 2: Estimated maximum amount
  1. Check-enrollment (estimated maximum amount): This is the initial request and initiates the payment session. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to validate the credit card data.

    When adding items (only if the total amount exceeds the estimated maximum amount)

  3. Check-enrollment (new total amount): To authenticate the new total amount, a new check-enrollment is needed. If the request is successful, the response contains a transaction-id.

    When ready to ship…​

  4. Authorization (latest enrolled amount): Send a request with transaction type authorization. Include the transaction-id from the latest check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

  5. Capture (latest enrolled amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

This option may have a higher abandonment rate. The authentication prompt asks the consumer to authenticate a higher amount than expected.

Installments (MIT)

Payment in installments occurs when a consumer purchases goods and settles the bill with multiple partial payments (plus interest) over an agreed period of time.

Consumers must be clearly informed about the terms of the agreement when setting up the installment plan.
Option 1: Installment with down-payment

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (full amount + interest): This is the initial request and initiates the payment session. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization (down-payment amount): Send a request with transaction type authorization. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field. If the request is successful, the response contains a new transaction-id.

  3. Capture (down-payment amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

    Payment per installment (MIT)

  4. Authorization (installment amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the first authorization response in the parent-transaction-id field (see step 2).

  5. Capture (installment amount): Send a request with transaction type capture. Include the transaction-id from the second authorization response in the parent-transaction-id field.

Option 2: Installment without down-payment

Setting up the agreement (consumer-initiated)

  1. Check-enrollment (full amount + interest): This is the initial request and initiates the payment session. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to sign the payment agreement. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

    Payment per installment (MIT)

  3. Authorization (installment amount) as merchant-initiated transaction (MIT): Merchant-initiated transactions are out of scope of SCA (Strong Customer Authentication); therefore, check-enrollment is not required prior to this request. The request must contain <periodic-type>installment</periodic-type> and <sequence-type>recurring</sequence-type>. Include the transaction-id from the authorization-only response in the parent-transaction-id field (see step 2).

  4. Capture (installment amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.


Special 3D Secure 2 Use Cases

Changing Terms of an Existing Payment Agreement (MIT)

Existing payment agreements may change. Such changes could be initiated by both merchants and consumers. Whenever a payment agreement changes, a check-enrollment for the new amount is recommended. Merchants may decide against a new check-enrollment in certain business scenarios.

Examples include up- and downgrades of subscription plans for video streaming services, changes to the billing cycle, as well as pausing, resuming, and canceling a subscription.

Scenario 1: Merchant-driven agreement changes

If a change is initiated by merchants, check-enrollment is not needed if the original agreement with the consumer (e.g. the terms and conditions) clearly covers the eventuality of such changes. One example could be price changes due to inflation, or video streaming services changing their subscription fees.

Scenario 2: Consumer-driven agreement changes

If a change is initiated by consumers, authentication is only required, if the agreed payment terms clearly cover the eventuality of such changes and the merchant has appropriate risk management in place. In case there are any doubts that the original agreement covers the change, treating the transaction as a new agreement by performing a check-enrollment request (for the new amount) is highly recommended. Examples include consumers up- or downgrading their software subscriptions.

Card-on-File Transactions

For card-on-file transactions, merchants store the consumer’s card data (as a token) for future transactions. Thus, when the consumer returns to the merchant’s shop, they don’t need to re-enter their data.

Before storing credentials on file, consumers must be clearly informed how the credentials will be used in the future. Obtain the consumers' consent.
To add a card on file:
Independent of purchase (standard scenario)
  1. Check-enrollment (zero amount): This is the initial request. It initiates the agreement set-up. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization-only (zero amount): Send a second request with transaction type authorization-only. This request serves to sign the agreement. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

Zero-amount processing is not supported by all acquirers. If you experience difficulties, please consult the alternative scenario below.
Independent of purchase (alternative scenario)
  1. Check-enrollment (minimal amount: e.g. 1.00 EUR): This is the initial request. It initiates the agreement set-up. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

  2. Authorization (minimal amount: e.g. 1.00 EUR): Send a second request with transaction type authorization. This request serves to sign the agreement. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

  3. Void-authorization (authorization amount): Send a third request with transaction type void-authorization. The agreement has been signed by means of the authorization transaction. Void the amount provided in the authorization request to conclude the workflow.

During purchase
  1. Check-enrollment (payment amount): This is the initial request. It initiates the agreement set-up. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. If the request is successful, the response contains a transaction-id.

    This is a transaction used to sign a card-on-file agreement. Therefore, Strong Customer Authentication is required. Exemptions do not apply.
  2. Authorization (payment amount): Send a second request with transaction type authorization. This request serves to sign the agreement. The request must contain <periodic-type>ci</periodic-type> and <sequence-type>first</sequence-type>. Include the transaction-id from the check-enrollment response in the parent-transaction-id field.

  3. Capture (payment amount): Send a request with transaction type capture. Include the transaction-id from the authorization response in the parent-transaction-id field.

For subsequent transactions that use stored card details, use <periodic-type>ci</periodic-type> and <sequence-type>recurring</sequence-type>.
Mail Order Telephone Order (MOTO) Transactions
To process MOTO transactions, your merchant account must be configured accordingly (contact merchant support).

Mail Order Telephone Order (MOTO) transactions are not considered electronic payments and, as such, are out of scope of SCA (Strong Customer Authentication). To process MOTO transactions (authorizations and purchases) without SCA, they must be marked accordingly.

How to mark a transaction as MOTO depends on your merchant account configuration:

  • MOTO-exclusive setup: In case your merchant account is set up for executing MOTO transactions only, MOTO is assigned as the default commerce type. If the payment/entry-mode field of the payment request is left empty, the respective transaction is marked as MOTO by default.

  • Mixed setup: In case your merchant account is set up for executing both MOTO transactions and e-commerce transactions, e-commerce is assigned as the default commerce type. To mark a transaction as MOTO, set the payment/entry-mode field to either mail-order or telephone-order in the payment request.

    Mixed setup: If the payment/entry-mode field of the payment request is left empty, the respective transaction is marked as e-commerce by default and thus subject to SCA.
Custom URL: