Authenticate Payer
- 28 Aug 2023
- 9 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Authenticate Payer
- Updated on 28 Aug 2023
- 9 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
This message is used to process Authentication for mobile payments coming through the Mobile SDK channel. It doesn't perform any financial transaction and it's limited to authentication only. The outcome of this message indicates whether the authentication is friction-less or requires further authentication steps (Challenge mode).
You need to invoke the Mobile Payment or Mobile Pre-Auth after invoking this message and proceeding with any further authentication steps if required.
It is based on the API Communication Model described in the Communication Model section. The merchant should handle the authentication process using 3DS Mobile SDK after invoking Authenticate Payer message and the returning ‘Response.StatusCode’ parameter is (20001) (Challenge).
If the returning ‘Response.StatusCode’ parameter is (00000), then no further authentication steps are required (friction-less).
This message is dedicated for credit card payments only and not suitable for Apple Pay or other payment methods.
Request Parameters
| Parameter | Description |
|---|---|
| MessageID required | An alphanumeric value that represents the action for defined unique numbers as mentioned below:
|
| TransactionID required | The merchant generates the Transaction ID. It represents a unique identifier for the transaction and is alphanumeric which must not include special characters or spaces.
|
| MerchantID required | An alphanumeric value that represents the unique Merchant ID at SmartRoute. The Payment Gateway operation team provides this value based on the merchant enrollment.
|
Amount required | A numeric value that contains the ISO Formatted item purchase invoice amount with no decimal point. For example, 100 for 1.00 USD.
|
| CurrencyISOCode required | A numeric value that contains the ISO formatted code for the currency, not the character value. For example, 840 for USD.
|
| PaymentMethod required | An Alphanumeric value indicates the payment method. It should be 1 indicating a Card Payment.
|
| SecureHash required | An alphanumeric value that represents the generated hex-encoded hash using hashing algorithm SHA-2 (256) by concatenating parameters as a single string starting with the merchant’s Merchant Authentication Token. Then all parameters (required parameters and optional parameters - if available) are ordered alphabetically. By parameter’s name should be part of the secure hash, with no separators and no terminating character. Appendix B: Secure Hash – API Payment; for more information, see secure hash generation.
|
ClientIPaddress required | An alphanumeric value that represents the client’s public IP Address.
|
| CardNumber conditional | The customer’s card number to be used in the payment.
|
| ExpiryDateYear conditional | The customer’s card expiry date (year)digits that are used in the payment. The format of this parameter should be in the form (YY).
|
| ExpiryDateMonth conditional | The customer’s card expiry date (month) digits are used in the payment. The format of this parameter should be in the form (MM).
|
| SecurityCode required | The customer’s card Security Code (e.g. CVV or CVC) depends on the Card Type used in the payment.
|
| AgreementID conditional | The agreement Id represents a unique identifier for the agreement between the merchant and the payer where the payer authorizes the merchant to perform subsequent transactions (i.e. recurring) without their active participation. The subsequent transactions shall share the same agreement Id provided in this first transaction. The value is generated by the merchant and should be unique per recurring series.
Note: The same value should be provided while performing a recurring payment across the recurring series for this payer. |
| AgreementType conditional | Alphabetical value represents the type of subsequent transactions, if any, that will be initiated based on this first transactions. Possible values are:
|
| PaymentDescription optional | An alphanumeric string that contains a narrative Payment Description of the invoice, which uses the language specified in the language parameter. This value should be UTF-8 encoded. It is entered into the secure hash generation process.
|
| CardHolderName conditional | The customer’s cardholder name is used in the payment.
|
| ItemID optional | An alphanumeric value that represents the custom item ID.
|
| Channel required | The Channel to be used by SmartRoute System. It should be sent 3 in this message.
|
| Quantity optional | A numeric value greater than ZERO represents the quantity of purchased Items.
|
| Version optional | A numeric value with (.) separator represents the command's version to be used. If this value is not provided, SmartRoute will consider its default value which is 1.0 Possible version values: - 2.0 or higher: an additional response field will be returned from SmartRoute to merchant that represents the payment method used "Response.PaymentMethod" - 2.1 or higher: indicates that the merchant will provide the AgreementID and AgreementType fields.
|
| FrameworkInfo required | An alphanumeric value that represents the client’s used framework.
|
| Token optional | The token is used in this request; to represent previously used card information. This parameter is a part of the tokenization parameters. For more information, see Tokenization.
|
| AppID required | A unique identifier for the app on the payer's device. The 3-D Secure SDK generates this identifier each time the app is installed or updated. This field corresponds to EMVCo field sdkAppID.
|
| SDKEncryptedData required | Information about the payer's device collected and encrypted by the 3-D Secure SDK. The data is a JSON Web Encryption (JWE) object in JSON format. This field corresponds to EMVCo field sdkEncData.
|
| EphemeralPublicKey required | A public key generated by the 3-D Secure SDK. This key is used to establish a secure session between the 3DS SDK and the issuer's Access Control Server (ACS) when the payer is required to be presented with an authentication challenge. The key is a JSON Web Key (JWK) object in JSON format. This field corresponds to EMVCo field sdkEphemPubKey.
|
| SDKReferenceNumber required | An identifier of the vendor and version of the 3-D Secure SDK assigned by EMVCo This field corresponds to EMVCo field sdkReferenceNumber.
|
| SDKTransactionID required | A unique identifier assigned by the 3-D Secure SDK for the transaction. This field corresponds to EMVCo field sdkTransID.
|
| SDKInterface required | The User Interface (UI) formats that the payer's device supports. These are the formats that can be used to render the screens presented to the payer during an authentication challenge. This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions. Possible Values:
|
| UIType optional | Indicates the UI types which the SDK supports for displaying authentication challenges within the app. A comma separated list of the payer authentication methods that you will accept for this payment. This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions.
|
| ExtraFields optional | A parameter which allows to send new parameters in CSV + JSON format Example of usage: “ExtraField1”:”Value” , “ExtraField2”:”Value2”. This filed will be implemented without an actual usage for it in the runtime, and is kept there for future purposes and used as per the need.
|
Response Parameters
| Parameter | Description |
|---|---|
Response.StatusCode required | An alphanumeric value that represents the response code that covers errors generated by the SmartRoute. Appendix A: API Payment Response Codes for descriptive details about Response Codes.
|
| Response.StatusDescription required | An alphanumeric value that represents a message describing the response status received from SmartRoute. This parameter is filled only after a complete execution process using the language specified in the request. This value should be UTF-8 encoded when it is entered into the secure hash generation process.
|
| Response.Amount required | A numeric value that contains the purchase amount of the item.
|
| Response.CurrencyISOCode required | The numeric value is in ISO format for the currency. The value should be neither character value nor decimal point. For example, 840 for US Dollar, 400 for JOD.
|
| Response.MerchantID required | An alphanumeric value that represents the unique ID of the merchant at SmartRoute. The SmartRoute operation team provides this value upon merchant enrollment.
|
| Response.TransactionID required | The merchant generates the Transaction ID. It represents a unique identifier for the transaction and is alphanumeric which must not include special characters or spaces.
|
| Response.MessageID required | An alphanumeric value that represents the action for defined unique numbers as mentioned below:
|
| Response.SecureHash required | An alphanumeric value that represents the generated hex-encoded hash using hashing algorithm SHA-2 (256) by concatenating parameters as a single string starting with the merchant’s Merchant Authentication Token. Then all parameters (required parameters and optional parameters - if available) are ordered alphabetically. By parameter’s name should be part of the secure hash, with no separators and no terminating character. Appendix B: Secure Hash – API Payment; for more information, see secure hash generation.
|
| Response.PaymentMethod conditional | An Alphanumeric value indicates the payment method. Supported values depend on the requested version as follows:
Condition: The SmartRoute operation team, upon merchant enrollment, provides possible Card Names. |
| Response.GatewayStatusCode optional | An alphanumeric value that represents the gateway response code. This code covers errors generated by the chosen gateway.
|
| Response.GatewayStatusDescription optional | An alphanumeric value that represents a message describing the response status received from the chosen gateway using the language specified in the request. After completing the execution process, this parameter is filled in. This value should be UTF-8 encoded when it is entered into the secure hash generation process.
|
| Response.GatewayName optional | This value represents the gateway name that processed the transaction. It can be alphanumeric with special characters like space, ‘@’ and ‘_’.
|
| Response.RRN optional | An alphanumeric value that represents a Receipt Reference Number for the current payment transaction. This value is returned if the value is provided from the gateway.
|
| Response.ApprovalCode optional | Approval Code received from Payment Processor such as Visa. The values are returned in the following cases:
|
| Response.CardNumber optional | An alphanumeric value represents the masked Card Number.
|
| Response.Token optional | The token that is assigned to the entered card information; responds to a “GenerateToken” flag with the value “Yes”. This parameter is a part of the tokenization parameters; for more information, see Tokenization.
|
| Response.ThreeDServerTrxnID conditional | The field contains the unique identifier assigned by the 3DS Server for this authentication. This is referred to in the EMVCo specification for 3-D Secure as threeDSServerTransID. This field is returned in case of 3DS v.2 only.
|
| Response.ACSTrxnID conditional | A unique transaction identifier assigned by the Access Control Server to identify the 3DS transaction. This field is returned in case of 3DS v.2 only.
|
| Response.ChallengeContent conditional | Information provided by the issuer's Access Control Server (ACS) that is used to render the screens presented to the payer during an authentication challenge. This field corresponds to EMVCo field acsSignedContent. This field is returned in case of 3DS v.2 only.
|
| Response.UIType conditional | A comma separated list of the payer authentication methods that 3DS SDK will accept for this payment. Indicates the UI types which the SDK supports for displaying authentication challenges within the app. This field corresponds to EMVCo data element sdkUiType in the field deviceRenderOptions. This field is returned in case of 3DS v.2 only. Value must be one or more comma separated members of the following list.
|
| Response.ChallengeCompletionUrl conditional | This value is only returned when you authenticate the payer in-app using 3-D Secure authentication version 2 and a challenge is required. This URL must be called after the challenge has been completed; for example, when the ACS has confirmed the challenge completion. This allows the gateway to retrieve the authentication result after the challenge has been completed.
|
| Response.SDKInterface conditional | The User Interface (UI) formats that the payer's device supports. These are the formats that can be used to render the screens presented to the payer during an authentication challenge. It is retuned only for 3DS v2 when a challenge is required. This field corresponds to EMVCo data element sdkInterface in the field deviceRenderOptions. Possible Values:
|
| Response.ACSRefNumber conditional | Unique identifier assigned to the issuer's Access Control Server (ACS) by the EMVCo. It is retuned only for 3DS v2. This field corresponds to EMVCo field acsRefNumber.
|
| Response.ChallengeRequired conditional | An identifier which informs the merchant if this transaction requires a challenge (for 3DS v1 and 3DS v2). Possible Values:
|
| Response.ThreeDSVersion required | 3DS Version as received from the Authentication process. Possible Values:
|