Challenge Flow

When a Challenge is requested, as detailed in the TransactionStatus field, you need to complete the following to allow the Cardholder to Authenticate.

Requirement

1. HTTP form POST redirecting the Cardholder to the provided ACSUrl.
2. Interpret the results in the returned HTTP POST from the ACSUrl.
3. Invoke the GetResult method to receive the outcome of the challenge and the data required to proceed to authorisation.
4. Intepret the GetResult Response.

Cardholder Redirection

The Authenticate Response will contain the values for the AcsUrl and CReq, which the you should use to perform the HTTP Post to the ACS.

An HTTPS form POST request should be sent to the AcsUrl with the following parameters:

POST ACSUrl
Field Name	State	Data Type	Description
CReq	Mandatory	String	This is the value as provided in the Authentication Response.

POST example code

<form name="frm" method="POST" action="AcsUrl">
    <input type="hidden" name="creq" value="CReq" />
</form>

Cardholder Redirection

During the Challenge flow, the cardholder is redirected to the ACS Url and is no longer visible to you. Should you need to, you can invoke the GetResult method and interrogate any ChallengeCancellationIndicator to identify reasons why the cardholder has not been redirected back.

Cardholder Challenge Results

After the cardholder has authenticated with the ACS, the ACS will post back the result of the challenge to the DS which in turn posts back to the ResultUrl Entrypoint Service. The cardholder is then posted back to the NotificationUrl provided by the merchant in the Authenticate Request with the CRes.

An HTTPS form POST will be sent to the NotificationUrl with the following parameters:

POST ACSUrl
Field Name	State	Data Type	Description
CReq	Mandatory	String	This is the result of the Challenge.
threeDSSessionData	Optional	String	This optional field may not be returned. It is a bse64-encoded string, maximum 1024 bytes.

Example Response

<form name="frm" method="POST" action="NotificationUrl">
    <input type="hidden" name="cres" value="CRes" />
    <input type="hidden" name="threeDSSessionData" value="threeDSSessionData" />
</form>

Next Steps

Once you have received the HTTP POST response, you must invoke the GetResult method to receive the outcome of the challenge and the data required to proceed to authorisation.

Get Result Request

JSON

URL

https://ppe.optpg.com/PayerAuthEntryPoint/v1/PayerAuthEntryPoint.svc/rest/GetResult

Method

HTTP POST containing the fields below

XML

URL

https://ppe.optpg.com/PayerAuthEntryPoint/v1/PayerAuthEntryPoint.svc/soap

Method

A well-formed and valid XML document using a properly encoded SOAP envelope in the following form: An XML Declaration A SOAP Envelope formed of: A SOAP Header A SOAP Body

GetResult Request
Field Name	State	Data Type	Description
Reference	Optional	String	Your payment reference for this request. The reference can be viewed in reporting and is useful for diagnostics. We recommend using a Globally Unique Identifier(GUID) Maximum of 50 Alphanumeric Characters
AuthenticationDetails	Mandatory	Object	Data that the platform uses to authenticate this request. Mandatory for all requests. See AuthenticationDetails for more information.
SendAttempt	Mandatory	Integer	Sequential increment based upon number of attempts to send,starting at 1. You should iterate this following any unsuccessful attempts, and monitor excessive attempts.
CardClassId	Mandatory	Integer	Indicates the card scheme that issued the card.
ThreeDsServerTransactionId	Mandatory	String	Universally unique transaction identifier assigned by the DS to identify a single transaction. Length: 36 characters Value accepted: Canonical format as defined in IETF RFC 4122. May utilise any of the specified versions as long as the output meets specified requirements.

AuthenticationDetails

Authentication Details
Field Name	State	Data Type	Description
MerchantSignatureKeyId	Mandatory	Integer	Gateway supports multiple signature keys to be stored against a merchants system. The ID for the required signature must be passed here. Most merchants will only have one signature key and this value will be 1
RequestDateTimeUtc	Mandatory	dateTime	Date and time of the transmission of the message, in UTC format. YYYY-MM-DDTHH:MM:SS format.
RequestType	Mandatory	String	Type of message being sent to the gateway ThreeDSecureV2GetResultRequest should be used
MerchantStoreId	Mandatory	Integer	ID of the Merchant Store being used for this transaction. This will be provided as part of your test credentials.
SignatureType	Mandatory	String	Type of signature used. Hmac256 must be used.
Signature	Mandatory	String	The signature generated for this request.

Request Code Examples

JSON

{
    "Reference":"TestTransaction",
    "AuthenticationDetails":{
        "MerchantSignatureKeyId":32767,
        "RequestDateTimeUtc":"\/Date(928146000000+0100)\/",
        "RequestType":"String content",
        "MerchantStoreId":2147483647,
        "SignatureType":0,
        "Signature":"String content"
    },
    "SendAttempt":1,
    "CardClassId":8,
    "ThreeDsServerTransactionId":"String content"
}

XML

<ThreeDSecureV2GetResultRequest>
  <Reference>TestTransaction</Reference>
  <AuthenticationDetails>
    <MerchantSignatureKeyId>32767</MerchantSignatureKeyId>
    <RequestDateTimeUtc>1999-05-31T11:20:00</RequestDateTimeUtc>
    <RequestType>String content</RequestType>
    <MerchantStoreId>2147483647</MerchantStoreId>
    <SignatureType>Hmac256</SignatureType>
    <Signature>String content</Signature>
  </AuthenticationDetails>
  <SendAttempt>2</SendAttempt>
  <CardClassId>8</CardClassId>
  <ThreeDsServerTransactionId>String content</ThreeDsServerTransactionId>
</ThreeDSecureV2GetResultRequest>

Get Result Response

A detailed breakdown of all of the fields returned in the response are shown below.

GetResult Response
Field Name	Data Type	Description
Reference	String	Gateway returns the original reference passed by the integrator Length: Variable, max. 50 characters.
ErrorCode	Integer	If an error has occurred during the process the relevant code will be populated in this field.
ErrorMessage	String	If an error has occurred during the process the relevant message will be populated in this field.
ResponseTime	Integer	Number of milliseconds taken for the response to be returned
AtsData	String	Additional Transaction Security (ATS) data This will only be populated in the event of fallback to V1.
AuthenticationEci	String	Electronic Commerce Indicator (ECI) - consists of two digits
AuthenticationType	String	Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. 01 Static. 02 Dynamic. 03 OOB 04 Decoupled.
AuthenticationValue	String	Cardholder Authentication Verification Value (CAVV) - a 28-byte base64 encoded value
ChallengeCancellationIndicator	String	Indicates the type of authentication method the Issuer will use to challenge the Cardholder, whether in the ARes message or what was used by the ACS when in the RReq message. 01 Cardholder selected 'Cancel'. 02 Reserved for future EMVCo use (values invalid until defined by EMVCo). 03 Transaction Timed Out - Decoupled Authentication, 04 Transaction Timed Out at ACS - other timeouts, 05 Transaction Timed out at ACS - First CReq not received by ACS. 06 Transaction Error. 07 Unknown. 08 Transaction Timed Out at SDK. This field will only be provided if the authentication has been cancelled or is otherwise unsuccessful, as indicated.
DsTransactionId	String	Universally unique transaction identifier assigned by the DS to identify a single transaction. For information only, the solution uses ThreeDsServerTransactionId instead.
ThreeDsServerTransactionId	String	Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction. Length: 36 characters. Populated if DS interaction has taken place.
TransactionStatus	String	Indicates whether a transaction qualifies as an authenticated transaction or account verification. Note: The Final CRes message can contain only a value of Y or N. Y Authentication Verification Successful. N Not Authenticated/Account Not Verified; Transaction denied. U Authentication/Account Verification Could Not Be Performed; Technical or other problem, as indicated in ARes or RReq. A Attempts Processing Performed; Not Authenticated/Verified, but a proof of attempted authentication/verification is provided. C Challenge Required; Additional authentication is required using the CReq/CRes. D Challenge Required; Decoupled Authentication confirmed. R Authentication/Account Verification Rejected; Issuer is rejecting authentication/verification and request that authorisation not be attempted. I Informational Only; 3DS Requestor challenge preference acknowledged. Populated if DS interaction has taken place.
TransactionStatusReason	String	Provides information on why the Transaction Status field has the specified value. 01 Card authentication failed. 02 Unknown Device. 03 Unsupported Device. 04 Exceeds authentication frequency limit. 05 Expired card. 06 Invalid card number. 07 Invalid transaction. 08 No Card record. 09 Security failure. 10 Stolen card. 11 Suspected fraud. 12 Transaction not permitted to cardholder. 13 Cardholder not enrolled in service. 14 Transaction timed out at the ACS. 15 Low confidence. 16 Medium confidence. 17 High confidence. 18 Very High confidence. 19 Exceeds ACS maximum challenges. 20 Non-Payment transaction not supported. 21 3RI transaction not supported. 22 ACS technical issue. 23 Decoupled Authentication required by ACS but not requested by 3DS Requestor. 24 3DS Requestor Decoupled Max Expiry Time exceeded. 25 Decoupled Authentication was provided insufficient time to authenticate cardholder. ACS will not make attempt. 26 Authentication attempted but not performed by the cardholder. Populated if DS interaction has taken place.

Get Result Code Examples

JSON

{
    "Reference":"TestTransaction",
    "ErrorCode":00,
    "ErrorMessage":"String content",
    "ResponseTime":100,
    "AtsData":"String content",
    "AuthenticationEci":"String content",
    "AuthenticationType":"String content",
    "AuthenticationValue":"String content",
    "ChallengeCancellationIndicator":"String content",
    "DsTransactionId":"String content",
    "ThreeDsServerTransactionId":"String content",
    "TransactionStatus":"String content",
    "TransactionStatusReason":"String content"
}

XML

<ThreeDSecureV2GetResultResponse>
  <Reference>TestTransaction</Reference>
  <ErrorCode>00</ErrorCode>
  <ErrorMessage>String content</ErrorMessage>
  <ResponseTime>100</ResponseTime>
  <AtsData>String content</AtsData>
  <AuthenticationEci>String content</AuthenticationEci>
  <AuthenticationType>String content</AuthenticationType>
  <AuthenticationValue>String content</AuthenticationValue>
  <ChallengeCancellationIndicator>String content</ChallengeCancellationIndicator>
  <DsTransactionId>String content</DsTransactionId>
  <ThreeDsServerTransactionId>String content</ThreeDsServerTransactionId>
  <TransactionStatus>String content</TransactionStatus>
  <TransactionStatusReason>String content</TransactionStatusReason>
</ThreeDSecureV2GetResultResponse>

Challenge Complete

When the GetResultResponse contains a TransactionStatus value you can proceed to Using your Results for guidance on the next steps.