3D Secure 2

From 3D Secure 1 to 3D Secure 2

3D Secure in a Nutshell
  • Payment standard introduced in 2001 by VISA that provides secure authentication and processing of online card payments

  • Protects merchants from fraudulent losses by allowing for liability shift after successful cardholder authentication

  • Three domains: merchant (acquirer), cardholder (issuer) and card scheme

The face of e-commerce has changed drastically since 3D Secure 1 was first introduced almost two decades ago. Mobile and in-app payment is booming, a seamless shopping experience more important than ever, and the demands on security growing.

As a result, the EMVCo has devised a new standard authentication method for payment card transactions: 3D Secure 2 (3DS2).

This state-of-the-art protocol fulfills the Strong Customer Authentication (SCA) requirements set by the EU’s Second Payment Services Directive (PSD 2) for online payments within the European Economic Area (EEA).

3DS2 is not yet supported in the APAC region. Please contact your relationship manager for more information.

What is Strong Customer Authentication (SCA)?

PSD 2 in a Nutshell
  • New Regulation: EU’s Second Payment Services Directive (PSD 2) 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

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:

pin_icon
smartphone_icon
face-id_icon

Knowledge

Possession

Inherence

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.

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.

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 PSD 2.

Why Adopt 3D Secure 2?

3D Secure 2 is 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 (3DS1):

No More Static Passwords

The days of rummaging through your drawers to find your 3D Secure 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.

movie_icon

Recurring MIT and PSD 2

Grandfathering

Since 14 September 2019, the PSD 2 Regulatory Technical Standard requires SCA for 3D Secure 2 payment processes. This also applies to recurring payments (see Article 14 RTS). From that day on, every first transaction of a recurring merchant-initiated transaction (MIT) must meet the standards of PSD 2.

However, a special exemptive status applies to ongoing recurring MITs whose first transaction was processed before 14 September 2019. Recurring MITs of that kind are being "grandfathered".

If Wirecard is your acquirer, the Wirecard Payment Gateway can "grandfather" a recurring MIT if you provide the referencing transaction-id from the first authorization or purchase transaction.

Conditions to grandfather a recurring MIT

Transaction Date

<transaction-type>

<transaction-id>

<sequence-type>

<periodic-type>

<parent-transaction-id>

First Transaction

Before 14 September 2019

a) authorization or
b) purchase

e.g. 12345

first

recurring or
installment or
UCOF

none

Recurring Transactions

After 14 September 2019

a) authorization or
a) referenced-authorization or
b) purchase or
b) referenced-purchase

e.g. 56789

recurring or
final

recurring or
installment or
UCOF
must be the same as in the first transaction.

e.g. 12345

Wirecard will then identify the correct Trace ID (Mastercard) or Transaction Identifier (Visa) of this recurring MIT and send it to the issuer.

Supported Card Brands

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

General Integration Guide

Processing 3D Secure 2 transactions differs from standard payment processing.

To enable 3D Secure 2,

Switching From 3D Secure 1 to 3D Secure 2
The 3D Secure 2 workflow remains identical to the 3D Secure 1 workflow. If you already have an existing 3D Secure 1 integration and want to migrate to 3D Secure 2, simply include additional 3D-Secure-2-specific fields in the initial payment request.

As the new 3D Secure 2 protocol will shortly replace 3D Secure 1, we strongly recommend you to implement 3D Secure 2 as soon as possible.

Check-Enrollment

Checks if the consumer’s card is enrolled in the 3D Secure 2 program. Check-enrollment has two functions:

  • Authenticate the consumer’s identity.

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

Therefore, a check-enrollment request needs to contain 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 originally requested-amount, the transaction may be declined. However, not all transactions that exceed the originally requested-amount will fail. In those cases, chargeback liability protection will not apply to the same extent as for fully authenticated amounts.

With 3D Secure 2 the amount of data collected during the check-enrollment is significantly higher than with 3D Secure 1. This allows a more comprehensive risk analysis.

Check-Payer-Response (optional)

This request is used to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. These include the dsTransId, CAAV/AVV, ECI, authenticationStatus and the 3D Secure version (expected 2.1.0).

Executing the check-payer-response is optional. Use it only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. If the check-payer-response is not executed, use instead the PARes received via TermURL to access the authentication values needed in the payment transaction that follows.

3D-Secure-2-Specific Fields

To process 3D Secure 2 transactions, include 3D-Secure-2-specific fields in the initial payment request.

For 3D Secure 2, more 3D-Secure-specific fields have to be included than for 3D Secure 1. 3D-Secure-2-specific fields can be found in the 3D Secure 2 Fields section.

Check out how to implement 3D Secure 2 for different integration options:

3D Secure 2 for REST API

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

Step-by-Step Integration

How to integrate 3D Secure 2 for REST API:

  1. Check-Enrollment

  2. Redirect the Consumer to the Access Control Server (ACS) URL

  3. Check-Payer-Response (optional)

  4. Complete the Payment Transaction

  1. Check-Enrollment
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  2. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

  4. Complete the Payment Transaction
    Proceed with the respective transaction type (e.g. authorization, purchase, authorization-only).

    You must reference either the previous check-enrollment or the check-payer-response, depending on whether the check-payer-response has been executed or not.

    • Following check-enrollment: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

Make sure to distinguish between the terms authentication and authorization:

  • Authentication confirms the cardholder’s identity.

  • Authorization checks whether the cardholder’s account holds sufficient funds and reserves the respective amount for later payment.

Detailed payment flows of typical 3D Secure 2 use cases can be found here. More information on the general 3D Secure 2 worflows is given in the 3D Secure 2 Workflows section.

Payment-Processing Example

We provide a Postman collection containing ready-made JSON samples for each step of a one-time payment transaction.

The 3D Secure 2 payment-processing example is designed for the testing environment and does not use real information.

Get the 3D Secure 2 Postman collection for the one-time payment transaction:

More details on 3D Secure fields included in the sample requests can be found in the 3D Secure 2 Fields section. They are also included in the REST API payment XSD.

Test Credentials

The Postman collection is preconfigured with the following test credentials:

URL (Endpoint)

https://api-test.wirecard.com/engine/rest/payments/

Merchant Account ID (MAID)

33f6d473-3036-4ca5-acb5-8c64dac862d1

Username

70000-APILUHN-CARD

Password

8mhwavKVb91T

Test Card

Card Number

5413330300201192

Expiration Date

01/2023

CVV

192

You can find further test credentials and test card types in our 3D Secure 2 Testing section.

Run the Collection

Import and run the collection with Postman.

To import the collection in Postman,

  1. Download the collection.

  2. Open Postman and click Import in the header bar.

  3. Click Choose Files and select the respective collection file.

    The collection appears in the Collections tab in the sidebar.

To run the collection in Postman,

  1. Select it and click on the arrow next to the collection name.

  2. Click Run.

    Requests included in the collection run automatically in series.

A successful test setup requires the integration of an ACS simulator. It allows you to simulate the ACS communication and to obtain the PARes.

Our samples work with Webhook.site to simulate the ACS URL. The communication with Webhook.site is already set up in our collection. This allows for automatic testing without interruption.

To manually integrate Webhook.site in a test setup,

  1. Send a check-enrollment request.
    A check-enrollment response containing the PAReq, the TermUrl and MD is returned.

  2. Open Webhook.site.

  3. Click Edit in the header bar.
    A pop-up window opens.

  4. Copy/paste the HTTPS POST request in the field Response Body.

    HTTPS 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>

    Default status code = 200
    Content type = text/html
    Timeout before response = 0

  5. In the HTTPS POST request

    1. replace the value PAReq and the action AcsUrl with the values from the check-enrollment response.

    2. replace the value TermUrl with your randomly generated URL from Webhook.site.

  6. Click Save.
    The pop-up window closes.

  7. Next to your randomly generated URL, click Open in a new tab.

  8. In the new tab, click Continue.

  9. Enter the password wirecard and click Submit (if required).

  10. Return to the previous webhook tab.
    You can find the PARes in the Form Values section.

  11. Copy the PARes and return to Postman.

  12. Enter the PARes and the transaction-id of the check-enrollment response in the check-payer-response request.

  13. Send the check-payer-response request.

  14. Complete the payment transaction.

Workflows

Generally, the 3D Secure 2 workflow remains identical to the 3D Secure 1 workflow. Unlike 3D Secure 1 though, 3D Secure 2 introduces the opportunity for frictionless authentication. Thus, 3D Secure 2 transactions can follow either a frictionless or a challenge flow. Based on provided data and resultant risk analysis, the issuing bank decides which flow is triggered.

  • Frictionless Flow: The consumer is authenticated passively. No further consumer interaction is required.

  • Challenge Flow: An authentication challenge is triggered. The consumer is prompted to provide further information.

    Sending specific 3D Secure 2 fields in the initial payment request reduces the likelihood of an authentication challenge. More details on 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.

If the issuer does not support 3D Secure 2, an automatic fallback to 3D Secure 1 is initiated.

Find the schematic diagrams for Frictionless Flow, Challenge Flow and Fallback to 3D Secure 1 below.

Make sure to distinguish between the terms authentication and authorization:

  • Authentication confirms the cardholder’s identity.

  • Authorization checks whether the cardholder’s account holds sufficient funds and reserves the respective amount for later payment.

3D Secure 2.1 Frictionless Flow
3D Secure 2 Frictionless Workflow

1. Check-Enrollment: 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 Fields section. They are also 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 ACS URL, the PAReq 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, 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. The check-payer-response returns the authentication values needed in the payment transaction that follows. 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, authenticationStatus and the 3D Secure version (expected 2.1.0).

4. Complete the Payment Transaction: Proceed with the respective 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
3D Secure 2 Challenge Workflow

1. Check-Enrollment: 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 Fields section. They are also 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 ACS URL, the PAReq 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, 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. Once the consumer has been redirected, they receive an authentication prompt (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 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. The check-payer-response returns the authentication values needed in the payment transaction that follows. 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, authenticationStatus and the 3D Secure version (expected 2.1.0).

4. Complete the Payment Transaction: Proceed with the respective 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).

Fallback to 3D Secure 1

3D Secure 2.1 Flow with Fallback to 3D Secure 1 (in case the issuer does not support 3D Secure 2)

3D Secure 2 Fallback Workflow

1. Check-Enrollment: 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 Fields section. They are also 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, 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 ACS URL, the PAReq 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, 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. The check-payer-response returns the authentication values needed in the payment transaction that follows. 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, authenticationStatus and the 3D Secure version.

4. Complete the Payment Transaction: Proceed with the respective 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).

Testing

Setup and Test Credentials
Use these test credentials to test 3D Secure transactions for both versions, 3D Secure 2 as well as 3D Secure 1.

Use the following endpoint to set up your testing tool:

URL (Endpoint)

https://api-test.wirecard.com/engine/rest/payments/

Refer to one of the following tables to complete your test credentials:

3D (Manual Card Brand Recognition) Test

Merchant Account ID (MAID)

33f6d473-3036-4ca5-acb5-8c64dac862d1

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

9e0130f6-2e1e-4185-b0d5-dc69079c75cc

Mobile SDK Applicable

Yes

3D (Automatic Card Brand Recognition) Test

Merchant Account ID (MAID)

cad16b4a-abf2-450d-bcb8-1725a4cef443

Merchant Account Name

Wirecard CC/EFT Simu3D no CVC

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

b3b131ad-ea7e-48bc-9e71-78d0c6ea579d

Mobile SDK Applicable

Yes

3D Non-Gambling Original Credit Transaction (OCT) Test

Merchant Account ID (MAID)

ba90c606-5d0b-45b9-9902-9b0542bba3a4

Merchant Account Name

Merchant-Test-Accounts

Username to access Test Account

70000-APILUHN-CARD

Password to access Test Account

8mhwavKVb91T

Secret Key

b30bf3cc-f365-4929-89e9-d1cbde890f84

Mobile SDK Applicable

Yes

Test Cards

We provide own test cards for each 3D Secure version, 3D Secure 2 and 3D Secure 1, as well as for a variety of card brands. These test cards allow you to trigger a certain behaviour when you send them to our endpoint.

Example

If you want to provoke the error status code 500.1072 ("Card Not Enrolled.") in combination with a Visa card for a 3D Secure 1 transaction, use Card Number 4012000300006002, Expiration Date 01/2023 and CVC 002.

3D Secure 1 Transactions

For 3D Secure transactions, both 3D Secure 2 and 3D Secure 1, WPG usually checks with the first request, whether the card is enrolled in the 3D Secure program. A card is enrolled in the 3D Secure program, if the response returns a positive enrollment check and a positive authentication result.

Enrollment and Authentication Values
3D Secure Status Description

Check-Enrollment Response

Y

Card enrolled.

N

Card not enrolled.

U

Unable to verify enrollment.

E

A system error prevented completion of check-enrollment.

Authentication Verification Result

Y

Cardholder has successfully been authenticated.

N

Consumer failed or canceled authentication.

U

Authentication could not be completed due to technical or other issue.

A

Proof of authentication attempt has been generated.

E

A system error prevented completion of authentication.

Card Numbers for Successful Transactions

With these card numbers you can provoke a successful response containing the status code 201.0000 ("The resource was successfully created.").

Card Brand

Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

Response Message

American Express

375987000000005

1005

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully.

375987000000013

1013

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully.

Diners

3800010001000103

103

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully.

3800010001000111

111

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully.

JCB

3569990001010007

007

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully.

3569990001010015

015

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully.

Maestro

6799860300001000003

003

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully

6799860300002000002

002

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully

Mastercard

5413330300001006

006

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully

5413330300002004

004

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully

UPI

6222821234560024

101

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully.

6222821234560021

119

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully.

VISA

4012000300001003

003

01/2023

Y

Y

wirecard

Testing "Authentication approved"

Approved or completed successfully

4012000300002001

001

01/2023

Y

A

 — 

No cardholder interaction

Approved or completed successfully

Card Numbers for Error Results

With these card numbers you can provoke an error response containing a variety of status codes.

American Express

Use Card Type amex

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

375987000000054

1054

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

375987000000062

1062

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

375987000000070

1070

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

375987000000021

1021

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

375987000000039

1039

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

Diners

Use Card Type diners

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

3800010001000152

152

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

3800010001000160

160

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

3800010001000178

178

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

3800010001000129

129

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

3800010001000137

137

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

JCB

Use Card Type jcb

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

3569990001010056

056

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

3569990001010064

064

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

3569990001010072

072

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

3569990001010023

023

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

3569990001010031

031

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

Maestro

Use Card Type maestro

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

6799860300006000008

008

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

6799860300007000007

007

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

6799860300008000006

006

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

6799860300003000001

001

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

6799860300004000000

999

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

Mastercard

Use Card Type mastercard

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

5413330300006005

005

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

5413330300007003

003

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

5413330300008001

001

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

5413330300003002

002

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

5413330300004000

999

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

UPI

Use Card Type upi

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

6222821234560019

150

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

6222821234560018

168

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

6222821234560020

176

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

6222821234560022

127

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

6222821234560023

135

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

VISA

Use Card Type visa

If you want to provoke…​

…​use these card data in the request…​

…​to obtain this result

Status Code

Status Name

Card Number

CVC

Expiration Date

Enrollment Result

Authentication Result

Password ACS

Personal Message ACS

500.1072

Card Not Enrolled

4012000300006002

002

01/2023

N

 — 

 — 

 — 

500.1073

Unable to Verify Enrolment

4012000300007000

999

01/2023

U

 — 

 — 

 — 

500.1074

MPI Error

4012000300008008

008

01/2023

E

 — 

 — 

 — 

500.1076

Consumer failed or Cancelled authentication.

4012000300003009

009

01/2023

Y

N

wirecard

Testing "Authentication failed"

500.1077

Authentication could not be completed due to technical or other problem.

4012000300004007

007

01/2023

Y

U

wirecard

Testing "Unable to authenticate"

3D Secure 2 Transactions
Table Key

The 3D Secure 2 test card tables deviate in a few instances from the 3D Secure 1 tables.

  • 3DS Method: This is an optional redirect URL to the ACS. It gathers additional browser information from the consumer, i.e. the device fingerprint. This happens prior to authentication to facilitate the transaction risk assessment.

  • Authentication Result: 3D Secure 2 includes an additional status R for rejected authentication.

  • Challenge: This column indicates whether the test card triggers an authentication challenge or not. Authentication challenges serve to provide more information about the consumer to reduce risk and fraud. No challenge allows testing of a frictionless payment flow. This is typically the case for low-value and low-risk transactions.

  • Enrollment Result: This is currently not present in the tables below, as the result of the check-enrollment is always expected to be Y (Card enrolled) for the test cards provided on this page.

3DS Method
Status Description

Y

The 3DS Method Completion Indicator is set to Y if the 3DS Method completes within 10 seconds.

N

The 3DS Method Completion Indicator is set to N if the 3DS Method does not complete in 10 seconds.

U

If the 3DS Method URL does not exist, the merchant will notify the 3DS server to set the 3DS Method Completion Indicator to U.

Authentication Result
Status Description

Y

The consumer has been successfully authenticated.

N

The consumer has failed or canceled authentication.

U

The authentication could not be completed due to technical or other issue on an external server (e.g. 3D Secure 2 provider). The issue is indicated in ARes or RReq.

A

Proof of an authentication attempt has been generated. The consumer has not been authenticated, but the attempt has been registered.

E

A system error prevented the completion of the authentication. Please contact merchant support.

R

The authentication has been rejected. The issuer is rejecting the authentication and requests that authorization not be attempted.

Successful 3D Secure 2 Transactions

3D Secure 2 Transactions without Challenge
Card Brand Number CVC Expiration Date 3DS Method Authentication Result Challenge ACS Password ACS Message

American Express

375987000001003

1003

01/2023

N

Y

No

N/A

No consumer interaction

375987000001052

1052

01/2023

Y

Y

No

N/A

No consumer interaction

375987000001102

1102

01/2023

U

Y

No

N/A

No consuemr interaction

Mastercard

5413330300201093

093

01/2023

N

Y

No

N/A

No consumer interaction

5413330300201184

184

01/2023

Y

Y

No

N/A

No consumer interaction

5413330300201192

192

01/2023

U

Y

No

N/A

No consumer interaction

Visa

4012000300201090

090

01/2023

N

Y

No

N/A

No consumer interaction

4012000300201181

181

01/2023

Y

Y

No

N/A

No consumer interaction

4012000300201199

199

01/2023

U

Y

No

N/A

No consumer interaction

3D Secure 2 Transactions with Challenge
Card Brand Number CVC Expiration Date 3DS Method Authentication Result Challenge ACS Password ACS Message

American Express

375987000001151

1151

01/2023

N

Y

Yes

wirecard

"Authentication approved"

375987000001201

1201

01/2023

Y

Y

Yes

wirecard

"Authentication approved"

375987000001250

1250

01/2023

U

Y

Yes

wirecard

Testing "Authentication approved"

Mastercard

5413330300201218

218

01/2023

N

Y

Yes

wirecard

"Authentication approved"

5413330300201002

002

01/2023

Y

Y

Yes

wirecard

"Authentication approved"

5413330300201291

291

01/2023

U

Y

Yes

wirecard

Testing "Authentication approved"

Visa

4012000300201207

207

01/2023

N

Y

Yes

wirecard

"Authentication approved"

4012000300201009

009

01/2023

Y

Y

Yes

wirecard

"Authentication approved"

4012000300201280

280

01/2023

U

Y

Yes

wirecard

Testing "Authentication approved"

3D Secure 2 Transactions Resulting in an Error
With the following card numbers you can provoke error responses.

3D Secure 2 Transactions without Challenge
Card Brand Number CVC Expiration Date 3DS Method Authentication Result Challenge ACS Password ACS Message

American Express

375987000001011

1011

01/2023

N

U

No

N/A

No consumer interaction

375987000001029

1029

01/2023

N

A

No

N/A

No consumer interaction

375987000001037

1037

01/2023

N

R

No

N/A

No consumer interaction

375987000001045

1045

01/2023

N

N

No

N/A

No consumer interaction

375987000001060

1060

01/2023

Y

U

No

N/A

No consumer interaction

375987000001078

1078

01/2023

Y

A

No

N/A

No consumer interaction

375987000001086

1086

01/2023

Y

R

No

N/A

No consumer interaction

375987000001094

1094

01/2023

Y

N

No

N/A

No consumer interaction

375987000001110

1110

01/2023

U

U

No

N/A

No consumer interaction

375987000001128

1128

01/2023

U

A

No

N/A

No consumer interaction

375987000001136

1136

01/2023

U

R

No

N/A

No consumer interaction

375987000001144

1144

01/2023

U

N

No

N/A

No consumer interaction

Mastercard

5413330300201036

036

01/2023

N

U

No

N/A

No consumer interaction

5413330300201101

101

01/2023

N

A

No

N/A

No consumer interaction

5413330300201168

168

01/2023

N

R

No

N/A

No consumer interaction

5413330300201176

176

01/2023

N

N

No

N/A

No consumer interaction

5413330300201036

036

01/2023

Y

U

No

N/A

No consumer interaction

5413330300201010

010

01/2023

Y

A

No

N/A

No consumer interaction

5413330300201085

085

01/2023

Y

R

No

N/A

No consumer interaction

5413330300201028

028

01/2023

Y

N

No

N/A

No consumer interaction

5413330300201150

150

01/2023

U

U

No

N/A

No consumer interaction

5413330300201127

127

01/2023

U

A

No

N/A

No consumer interaction

5413330300201085

085

01/2023

U

R

No

N/A

No consumer interaction

5413330300201143

143

01/2023

U

N

No

N/A

No consumer interaction

Visa

4012000300201033

033

01/2023

N

U

No

N/A

No consumer interaction

4012000300201108

108

01/2023

N

A

No

N/A

No consumer interaction

4012000300201165

165

01/2023

N

R

No

N/A

No consumer interaction

4012000300201173

173

01/2023

N

N

No

N/A

No consumer interaction

4012000300201033

033

01/2023

Y

U

No

N/A

No consumer interaction

4012000300201017

017

01/2023

Y

A

No

N/A

No consumer interaction

4012000300201082

082

01/2023

Y

R

No

N/A

No consumer interaction

4012000300201025

025

01/2023

Y

N

No

N/A

No consumer interaction

4012000300201157

157

01/2023

U

U

No

N/A

No consumer interaction

4012000300201124

124

01/2023

U

A

No

N/A

No consumer interaction

4012000300201082

082

01/2023

U

R

No

N/A

No consumer interaction

4012000300201140

140

01/2023

U

N

No

N/A

No consumer interaction

3D Secure 2 Transactions with Challenge
Card Brand Number CVC Expiration Date 3DS Method Authentication Result Challenge ACS Password ACS Message

American Express

375987000001169

1169

01/2023

N

U

Yes

wirecard

"Unable to authenticate"

375987000001177

1177

01/2023

N

A

Yes

wirecard

No consumer interaction

375987000001185

1185

01/2023

N

R

Yes

wirecard

"Issuer is rejecting authentication"

375987000001193

1193

01/2023

N

N

Yes

wirecard

"Authentication failed"

375987000001219

1219

01/2023

Y

U

Yes

wirecard

"Unable to authenticate"

375987000001227

1227

01/2023

Y

A

Yes

wirecard

No consumer interaction

375987000001235

1235

01/2023

Y

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

375987000001243

1243

01/2023

Y

N

Yes

wirecard

Testing "Authentication failed"

375987000001268

1268

01/2023

U

U

Yes

wirecard

Testing "Unable to authenticate"

375987000001276

1276

01/2023

U

A

Yes

wirecard

No consumer interaction

375987000001284

1284

01/2023

U

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

375987000001292

1292

01/2023

U

N

Yes

wirecard

Testing "Authentication failed"

Mastercard

5413330300201226

226

01/2023

N

U

Yes

wirecard

"Unable to authenticate"

5413330300201234

234

01/2023

N

A

Yes

wirecard

No consumer interaction

5413330300201135

135

01/2023

N

R

Yes

wirecard

"Issuer is rejecting authentication"

5413330300201242

242

01/2023

N

N

Yes

wirecard

"Authentication failed"

5413330300201259

259

01/2023

Y

U

Yes

wirecard

"Unable to authenticate"

5413330300201267

267

01/2023

Y

A

Yes

wirecard

No consumer interaction

5413330300201275

275

01/2023

Y

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

5413330300201283

283

01/2023

Y

N

Yes

wirecard

Testing "Authentication failed"

5413330300201309

309

01/2023

U

U

Yes

wirecard

Testing "Unable to authenticate"

5413330300201317

317

01/2023

U

A

Yes

wirecard

No consumer interaction

5413330300201325

325

01/2023

U

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

5413330300201333

333

01/2023

U

N

Yes

wirecard

Testing "Authentication failed"

Visa

4012000300201215

215

01/2023

N

U

Yes

wirecard

"Unable to authenticate"

4012000300201223

223

01/2023

N

A

Yes

wirecard

No consumer interaction

4012000300201132

132

01/2023

N

R

Yes

wirecard

"Issuer is rejecting authentication"

4012000300201231

231

01/2023

N

N

Yes

wirecard

"Authentication failed"

4012000300201249

249

01/2023

Y

U

Yes

wirecard

"Unable to authenticate"

4012000300201256

256

01/2023

Y

A

Yes

wirecard

No consumer interaction

4012000300201264

264

01/2023

Y

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

4012000300201272

272

01/2023

Y

N

Yes

wirecard

Testing "Authentication failed"

4012000300201298

298

01/2023

U

U

Yes

wirecard

Testing "Unable to authenticate"

4012000300201306

306

01/2023

U

A

Yes

wirecard

No consumer interaction

4012000300201314

314

01/2023

U

R

Yes

wirecard

Testing "Issuer is rejecting authentication"

4012000300201322

322

01/2023

U

N

Yes

wirecard

Testing "Authentication failed"

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.

payment.

Field M/O Data Type Size Description

iso-transaction-type

O

Enumeration

2

iso-transaction-type is a 3D Secure 2 field. It identifies the type of ISO transaction. The values are derived from ISO 8583.
Accepted values:

  • 01 = Goods/ Service Purchase

  • 03 = Check Acceptance

  • 10 = Account Funding

  • 11 = Quasi-Cash Transaction

  • 28 = Prepaid Activation and Load

authorization-reason

O

Enumeration

authorization-reason is an industry-specific indicator for merchant-initiated transactions (MIT). It is used to fulfill a business practice as a follow-up to an original cardholder-merchant interaction that could not be completed with a single transaction.
This indicator is available for the following transaction types:

  • authorization

  • preauthorization

  • purchase

  • referenced-purchase

Accepted values:

  • resubmission = an indicator used when the original purchase took place, but the authorization was not executed at the time the goods or services were provided.

  • delayed-charges = an indicator for an additional account charge performed after the original services have been provided. It is typically used by hotels, cruise lines and vehicle rental services.

  • reauthorization = an indicator used in the event of a purchase made after the original purchase in different specific conditions. It is typically found in delayed/split shipments and extended stays/rentals scenarios.

  • no-show = an indicator enabling you to charge for services that the consumer agreed to purchase, but failed to fulfill the agreement terms.

  • deferred-authorization = an indicator for cases when an authorization is completed at a later time, after the initial authorization failed/was delayed due to connectivity, system issues or other technical limitations.

account-holder

browser

card

periodic

risk-info

shipping

three-d

account-holder.

account-holder is a child of payment.
With account-holder you can provide information about the consumer.

The fields email, first-name and last-name are mandatory for a 3D Secure 2 payment process. If you omit one of them, ACS downgrades it to a 3D Secure payment process.
Field M/O Data Type Size Description

email

M

String

256

Consumer’s email address as given in your shop.

first-name

M

String

32

First name of the consumer.

last-name

M

String

32

Last name of the consumer.

merchant-crm-id

O

String

64

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

mobile-phone

O

String

18

Mobile phone number provided by the consumer.

phone

M/O

String

18

Phone number provided by the consumer.
When using a credit card for the loyalty program VOP, at least one of the following must be present: payment.consumer-id, email or phone.

work-phone

O

String

18

Work phone number provided by the consumer.

account-info

address

account-info.

account-info is a child of payment.account-holder.
With account-info you can provide detailed information about the consumer.

We strongly recommend sending optional account-info fields. If you do, it is less likely that the issuer authenticates the consumer with a Strong Customer Authentication.
Field M/O Data Type Size Description

authentication-method

O

Enumeration

2

Type of consumer login in your shop.
Accepted values:

  • 01 = Guest checkout (i.e. the consumer is not logged in).

  • 02 = Login to the consumer’s account in your 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.

authentication-timestamp

O

Timestamp

20

Date and time (UTC) of the consumer login to your shop.
Accepted format: YYYY-MM-DDThh:mm:ssZ.
For guest checkout, the timestamp is now.

card-creation-date

O

Date

10

Date that the consumer’s card was added to their account in your 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.

card-transactions-last-day

O

Numeric

9

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

challenge-indicator

O

Enumeration

2

Specifies whether this transaction shall be subject to Strong Customer Authentication (SCA).
Accepted values:

  • 01 = No preference.

  • 02 = No challenge requested (Consequence: higher conversion rate, but higher risk of fraud).

  • 03 = Merchant requests challenge (Consequence: lower conversion rate, but lower risk of fraud).

  • 04 = Challenge requested: Mandate. Must be sent in a first transaction that stores a token (e.g. for one-click checkout).

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

creation-date

O

Date

10

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

password-change-date

O

Date

10

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

purchases-last-six-months

O

Number

9

Number of successful orders by the consumer in your shop within the past six months.

shipping-address-first-use

O

Date

10

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

suspicious-activity

O

Boolean

Indicates if you know of suspicious activities by the consumer (e.g. previous fraud).

transactions-last-day

O

Number

9

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

transactions-last-year

O

Number

9

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

update-date

O

Date

10

Date that the consumer last made changes to their account in your shop, e.g. 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.

address.

address is a child of

  1. We strongly recommend sending all optional address fields for account-holder as well as shipping. If you do, it is less likely that the issuer authenticates the consumer with a Strong Customer Authentication.

  2. For the fields city, country, postal-code, state and street1 the following applies:
    If you want to have a 3D Secure 2 payment process,

    • you must provide a value in either all of these fields or in none of them.

    • state must meet the ISO 3166-2 standard and country must follow the ISO 3166-1 alpha-2 country code.

Field M/O Data Type Size Description

street1

M/O

String

50

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

street2

O

String

50

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

street3

O

String

50

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

city

M/O

String

50

City of the consumer’s address.

country

M/O

String

2

Country of the consumer’s address.

postal-code

M/O

String

16

ZIP/postal code of the consumer’s address.

state

M/O

String

3

State/province of the consumer’s address.
Format: Numeric ISO 3166-2 standard.

browser.

browser is a child of payment.

  • For all the optional fields (except time-zone), Wirecard’s MPI automatically detects this and adds this field to your request.

  • We strongly recommend sending all optional browser fields. If you do, it is less likely that the issuer authenticates the consumer with a Strong Customer Authentication.

Field M/O Data Type Size Description

accept

O

String

2048

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.

We strongly recommend to provide this field if you want to prevent rejection from the ACS server.

challenge-window-size

O

Enumeration

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 is not part of the AReq flow. If not present, it will be omitted.
Accepted values:

  • 01 = 250 x 400

  • 02 = 390 x 400

  • 03 = 500 x 600

  • 04 = 600 x 400

  • 05 = Full screen

color-depth

O

Number

2

Value representing the bit depth of the color palette for displaying images, in bits per pixel. Obtained from consumer’s browser using the screen.colorDepth property. The field is limited to single and double digits.
Accepted values:

  • 1 = 1 bit

  • 4 = 4 bits

  • 8 = 8 bits

  • 15 = 15 bits

  • 16 = 16 bits

  • 24 = 24 bits

  • 32 = 32 bits

  • 48 = 48 bits

ip-address

M/O

String

45

IP address of the consumer’s browser, obtained by payment page during payment.
Accepted format: IPv4 or IPv6.
Mandatory for requests where

  1. deviceChannel = 02 (BRW) and

  2. where regionally acceptable.

java-enabled

O

Boolean

Boolean that represents the ability of the consumer’s browser to execute Java.
Value is returned by the navigator.javaEnabled property.

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 by the navigator.language property.

screen-resolution

O

String

12

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

time-zone

O

String

5

Time difference in minutes between UTC and the local time of the consumer’s browser. Value is returned from the getTimezoneOffset() method.

user-agent

O

String

256

User agent as retrieved from the cardholder’s browser in the HTTP request.
If it is longer than 256 bytes, it must be truncated.

We strongly recommend to provide this field if you want to prevent rejection from the ACS server.

card.

card is a child of payment. card details are sent only in the first transaction request when the card is used for the first time. Due to PCI DSS compliance, card details are immediately replaced by a token. Beginning with the first response, this token is used for every consecutive transaction (request and response) that is performed with this credit card. Token data is provided with the card-token element.

Field M/O Data Type Size Description

account-type

O

Enumeration

2

The type of account, e.g. for a multi-account card product.
Accepted values:

  • 01 = Not Applicable

  • 02 = Credit

  • 03 = Debit

merchant-tokenization-flag

M/O

Boolean

This flag is set to true as soon as the consumer’s card data has been stored for future transactions.
Maps the Visa field Stored Credential.
Mandatory for one-click checkout.

gift-card.

gift-card is a child of payment.risk-info.gift-cards.

Field M/O Data Type Size Description

@id

O

Number

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:
A number that ranges from 1 to 10.

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

amount/@currency

O

String

3

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

periodic.

periodic is a child of payment.
periodic references recurring transactions such as payments of a subscription or an installment.
For all recurring payments the fields periodic-type and sequence-type must be provided with a value.

Field M/O Data Type Size Description

number-of-installments

M/O

Number

3

Indicates the maximum number of authorizations permitted for installment payments.

Mandatory only for installment payments with periodic-type = installment. Sent in authentication of the first transaction.

recurring-expire-date

M/O

Date

10

Date after which recurring payments with this card are no longer allowed. Accepted format: YYYY-MM-DD.

Mandatory only for installment payments with periodic-type = installment. Sent in authentication of the first transaction.

recurring-frequency

M/O

Number

4

Indicates the minimum number of days between individual authorizations.

Mandatory only for recurring payments (installments or subscriptions) with periodic-type = installment or periodic-type = recurring. Sent in authentication of the first transaction.

risk-info.

risk-info is a child of payment.

Field M/O Data Type Size Description

availability

O

Enumeration

2

The consumer is placing an order for merchandise that is not yet available and will be released in the future.
Accepted values:

  • 01 = Currently available

  • 02 = Future availability

delivery-mail

O

String

254

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

delivery-timeframe

O

Enumeration

2

The approximate delivery time.
Accepted values:

  • 01 = Electronic delivery

  • 02 = Same-day delivery

  • 03 = Overnight delivery

  • 04 = Two-day or more delivery

preorder-date

O

Date

10

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

reorder-items

O

Enumeration

2

Specifies whether the consumer has previously ordered the same item.
Accepted values:

  • 01 = First-time order

  • 02 = Reorder

gift-cards.gift-card

shipping.

shipping is a child of payment.

We strongly recommend sending all optional shipping fields. If you do, it is less likely that the issuer authenticates the consumer with a Strong Customer Authentication.
Field M/O Data Type Size Description

shipping-method

O

Enumeration

The shipping method chosen by the consumer.
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 goods are digital goods, use the shipping indicator value that matches the most expensive item.
Accepted values:

  • home_delivery: Ship to consumer’s billing address.

  • verified_address_delivery: Ship to another address which you know and have verified.

  • 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)

address

three-d.

three-d is a child of payment.

For a 3D Secure 2 payment process you must send content in all the fields listed below. If you omit one of them, ACS downgrades it to a 3D Secure payment process.
You receive some of the values during the payment process, e.g. when you communicate with the ACS server.
Field M/O Data Type Size Description

acs-url

M

String

2048

Issuer URL. You need to direct the enrollment-check request via the cardholder’s browser to this URL. It is returned only if the cardholder is enrolled in the 3D Secure program.

cardholder-authentication-status

M

String

1

Status of the 3D Secure check.

cardholder-authentication-value

M

String

1024

A cryptographic value generated by the issuer. Used for

  • Visa’s Cardholder Authentication Verification Value (CAVV) and

  • Mastercard’s

    • Accountholder Authentication Value (AAV) and

    • Universal Cardholder Authentication Field (UCAF).

ds-transaction-id

M/O

String

36

Universally unique transaction identifier assigned by the Directory Server to identify a single transaction.
Mandatory for external 3D Secure servers not provided by Wirecard.
Accepted format: see IETF RFC 4122.

eci

M

String

2

Indicates the status of the VERes.

pareq

M

String

16000

A base64-encoded request message created for cards participating in the 3D Secure program. The PaReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to you.

pares

M

String

2048

Issuer URL. You need to direct the enrollment-check request via the consumer’s browser to this URL. It is returned only if the cardholder is enrolled in the 3D Secure program.

riid

O

Enumeration

2

Indicates the type of 3RI request.
Accepted values:

  • 01 = Recurring transaction

  • 02 = Installment transaction

  • 03 = Add card

  • 04 = Maintain card information

  • 05 = Account

server-transaction-id

O

String

36

Universally unique transaction identifier assigned by the 3DS server to identify a single transaction.
If not specified, Netcetera 3DS server generates a UUID.

status-reason

O

String

Mapping of EMVCo error messages to Wirecard Payment Gateway messages.

version

O

Enumeration

5

Identifies the version of 3D Secure authentication used for the transaction.
Accepted values:

  • 1.0

  • 2.1

xid

M

String

36

The unique transaction identifier.

Payment Flows

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

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 mit first payment with auth
  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 recurring mit two step
  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 recurring mit storing with auth
  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 recurring mit two step
  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 installment mit first payment with auth
  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 installment mit subsequent no auth two step
  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 installment mit first payment one step with auth
  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 mit with ucof subsequent no auth two step
  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 mit with ucof storing
  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 mit with ucof storing card two step
  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

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 Payment

One-time payment 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.

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

Option 1: One-Step Payment with Authentication

Download a Postman collection for this use case option here.

The 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.
They are also included in the REST API payment XSD.

  1. Check-Enrollment
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  2. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

  4. Purchase
    This final step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    Execute this step right after the check-enrollment or check-payer-response, while the consumer is in the session.
Option 2: Two-Step Payment with Authentication

Download a Postman collection for this use case option here.

The 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.
They are also included in the REST API payment XSD.

  1. Check-Enrollment
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  2. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

  4. Authorization
    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    Execute this step right after the check-enrollment or check-payer-response, while the consumer is in the session.
  5. Capture-Authorization
    This step in the payment flow must reference the authorization response.
    Enter the transaction ID from the authorization response in the parent-transaction-id field.

    Execute this step as soon as the products are ready to ship, within the allowed time limit.

General Multi-Party Commerce

In general multi-party commerce, a consumer buys a product or service from a primary, consumer-facing merchant. At the time of purchase, the consumer acquires an additional product or service provided by a secondary, non-consumer facing merchant. This merchant charges for the additional product or service.
For example, a consumer purchases a washing machine (from the primary merchant) and a breakdown and repair insurance (from the secondary merchant).

Authentication required: Yes

Download a Postman collection for this use case here.

The 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.
They are also included in the REST API payment XSD.

  1. Check-Enrollment

    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

    Only the primary merchant must perform the authentication for the full amount.
  2. Redirect the Consumer to the ACS URL

    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)

    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

  4. Authorization

    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    This step authorizes the amount due for the primary product or service (e.g. the washing machine).
  5. Capture-Authorization

    This step in the payment flow must reference the authorization response.
    Enter the transaction ID from the authorization response in the parent-transaction-id field.

    This step captures the amount due for the primary product or service (e.g. the washing machine).
  6. Authorization

    This step authorizes the remaining amount due for the additional product or service (e.g. the breakdown and repair insurance).
    Set the parent-transaction-id field to the transaction-id value of the first authorization.

    As merchant-initiated transactions (MIT) are not within the scope of SCA, a check-enrollment is not required prior to this request.

    To mark this transaction as merchant-initiated, set the authorization-reason field to reauthorization.
  7. Capture-Authorization

    This step captures the remaining amount due for the additional product or service (e.g. the breakdown and repair insurance).

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.


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 by agents.

You are an agent with Wirecard.

For a successful transaction:

Initiate 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


External 3D Secure Providers
Authentication with external 3D secure providers needs configuration of your merchant account.
Contact merchant support to activate this feature.

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

You are a merchant with Wirecard.

You receive the following 3D Secure 2 values from your external 3D Secure provider (from a 3rd Party MPI rather than Wirecard MPI) after a successful authentication. You need these values to proceed with the checkout in purchase, authorization or authorization-only transactions:

three-d/cardholder-authentication-value

Mandatory.
A cryptographic value generated by the issuer. Used for

  • Visa’s Cardholder Authentication Verification Value (CAVV) and

  • Mastercard’s

    • Accountholder Authentication Value (AAV) and

    • Universal Cardholder Authentication Field (UCAF).

three-d/eci

Mandatory.
Indicates the status of the VERes.

three-d/ds-transaction-id

Universally unique transaction identifier assigned by the Directory Server to identify a single transaction.
Mandatory for external 3D Secure servers not provided by Wirecard.
Accepted format: see IETF RFC 4122.

three-d/version

Mandatory.
Identifies the version of 3D Secure authentication used for the transaction.

three-d/cardholder-authentication-status

Status of the 3D Secure check.

When you are ready to ship/deliver:

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

  2. Capture-Authorization (full amount)
    This step in the payment flow must reference the authorization response.
    Enter 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

One-Click Checkout

For one-click checkout transactions, merchants store the consumer’s card details (as a token) for future transactions. If the consumer wants to buy goods at a later point in time, they can do so without having to re-enter their card details.

Card details can be either stored independently of a payment or during a payment.

  1. Independent of payment: A consumer creates an account with an online shop and provides their credit card details upon registration. At the moment of registration, no money is transferred.

  2. During payment: The credit card details are stored during the consumer’s first checkout.

Before storing card details on file, consumers must be clearly informed how they will be used in the future. Obtain the consumers' consent.

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

Option 1: One-Click Checkout - Independent of Payment

Download a Postman collection for this use case option here.

The 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.
They are also included in the REST API payment XSD.

  1. Check-Enrollment (initial transaction, zero amount)
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    • Include the three-d/version field and set its value to 2.1.

    • Set the challenge-indicator to 04.

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.

    • Include the merchant-tokenization-flag field and set its value to true.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  2. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

    It is not required to include the periodic-type and sequence-type fields in the check-payer-response.
  4. Authorization-Only (zero amount)
    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.

    • Include the merchant-tokenization-flag field and set its value to true.

  5. Check-Enrollment (subsequent transaction, payment amount)
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    • Include the three-d/version field and set its value to 2.1.

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.

    • Include the merchant-tokenization-flag field and set its value to true.

    It is not required to set the challenge-indicator to 04.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  6. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  7. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

    It is not required to include the periodic-type and sequence-type fields in the check-payer-response.
  8. Authorization (payment amount)
    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.

    • Include the merchant-tokenization-flag field and set its value to true.

  9. Capture-Authorization (payment amount)
    This step in the payment flow must reference the authorization response.
    Enter the transaction ID from the authorization response in the parent-transaction-id field.

    It is not required to include the periodic-type and sequence-type fields in the capture-authorization.
Option 2: One-Click Checkout - During Payment

Download a Postman collection for this use case option here.

The 3D Secure 2 fields can be found in the 3D Secure 2 Fields section.
They are also included in the REST API payment XSD.

  1. Check-Enrollment (initial transaction, payment amount)
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    • Include the three-d/version field and set its value to 2.1.

    • Set the challenge-indicator to 04.

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.

    • Include the merchant-tokenization-flag field and set its value to true.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

    This is a transaction used to sign a card-on-file agreement. Therefore, Strong Customer Authentication is required. Exemptions do not apply.
  2. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  3. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

    It is not required to include the periodic-type and sequence-type fields in the check-payer-response.
  4. Authorization (payment amount)
    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to first.

    • Include the merchant-tokenization-flag field and set its value to true.

  5. Capture-Authorization (payment amount)
    This step in the payment flow must reference the authorization response.
    Enter the transaction ID from the authorization response in the parent-transaction-id field.

    It is not required to include the periodic-type and sequence-type fields in the capture-authorization.
  6. Check-Enrollment (subsequent transaction, payment amount)
    Checks if the consumer’s card is enrolled in the 3D Secure 2 program.

    • Include the three-d/version field and set its value to 2.1.

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.

    • Include the merchant-tokenization-flag field and set its value to true.

    • The token-id can be used instead of the account-number.

    • It is not required to set the challenge-indicator to 04.

    As a result of the check-enrollment, you receive the PAReq with the Access Control Server (ACS) URL.

  7. Redirect the Consumer to the ACS URL
    Send an HTTPS POST request including the ACS URL, the PAReq, TermUrl and MD.

    three-d/pareq

    Base64-encoded request message created for cards enrolled in the 3D Secure program.
    The PAReq is returned by the issuer’s ACS via the VISA or Mastercard directory to the Wirecard Payment Gateway and from there passed on to the merchant.

    TermUrl

    Web address of your server to receive the PARes, i.e. the Payment Authentication response.

    MD

    Field reserved for specific merchant data.
    It may be useful for retrieving transaction data from the database or recalling a transaction.

    The MD field is mandatory. Make sure to include it in the request. You do not need to enter a value.
    If you omit this field, however, an authentication error occurs and the payment process is aborted.

    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 is posted to the TermURL via the consumer’s browser.

  8. Check-Payer-Response (optional)
    Use this request to receive, analyze and store authentication values. The check-payer-response returns the authentication values needed in the payment transaction that follows. It must contain the following fields:

    three-d/pares

    Digitally signed, base64-encoded authentication response message. It contains the ARes/CRes received from the issuer.

    parent-transaction-id

    Enter the transaction ID from the check-enrollment response.

    Use the check-payer-response only in case you have initiated the check-enrollment through the Wirecard Payment Gateway. The check-payer-response will not work if you have used an external 3D Secure provider (third-party MPI) to check if the consumer’s card is enrolled in the 3D Secure 2 program.

    It is not required to include the periodic-type and sequence-type fields in the check-payer-response.
  9. Authorization (payment amount)
    This step in the payment 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.

    • Following check-enrollment: Enter the transaction ID from the check-enrollment response in the parent-transaction-id field.

    • Following (optional) check-payer-response: Enter the transaction ID from the check-payer-response in the parent-transaction-id field.

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

    • Set the periodic-type to ci (consumer-initiated) and the sequence-type to recurring.

    • Include the merchant-tokenization-flag field and set its value to true.

  10. Capture-Authorization (payment amount)
    This step in the payment flow must reference the authorization response.
    Enter the transaction ID from the authorization response in the parent-transaction-id field.

    It is not required to include the periodic-type and sequence-type fields in the capture-authorization.

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.


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.