Direct Post Verify
- 06 Jun 2024
- 8 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Direct Post Verify
- Updated on 06 Jun 2024
- 8 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
This message is useful for merchants when they want to verify the user’s card information in order to use the returned Token later on in other messages such as Recurring. Therefore, once SmartRoute receives a verify message, a payment is conducted followed by a reversal in case the payment was successful.
This message is based on the Direct Post Communication Model.
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. Supported values depend on the requested version as follows:
|
| 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) except (CardNumber, SecurityCode, CardHolderName, ExpiryDateYear, ExpiryDateMonth since those parameters are entered by the customer (cardholder) on the screen and are submitted directly to SmartRoute’s URL, so they can’t be captured and entered in the secure hash parameters.) Ordered alphabetically by parameter’s name should be part of the secure hash, with no separators and no terminating character. Appendix B: Secure Hash – Direct Payment; for more information, see secure hash generation.
|
| CardNumber Conditional | The customer’s card number is used in the payment. If they sent PaymentMethod parameter is 1 (Card), this parameter is required.
Note: It should not be included in the Secure Hash. |
| 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). This parameter is required if the sent PaymentMethod parameter is 1 (Card).
Note: It should not be included in the Secure Hash. |
| 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). If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. |
| SecurityCode Conditional | The customer’s card Security Code (e.g. CVV or CVC) depends on the Card Type used in the payment. If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. |
| CardHolderName optional | The customer’s cardholder name is used in the payment. If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: It should not be included in the Secure Hash. Spaces are allowed in the cardholder name. |
| 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.
|
| Language optional | An alphabetic value that represents the interface's language is displayed to the customer and used for the payment description parameter. SmartLink will use this value during the payment process to display the interface. Thus, supporting the selected language to the customer. For example, Supported values are En, Ar.
|
| ItemID optional | An alphanumeric value that represents the custom item ID.
|
| 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.
|
| Channel optional | The Channel to be used by SmartRoute System. It could be one of the following:
|
| Quantity optional | A numeric value greater than ZERO represents the quantity of purchased Items.
|
| ResponseBackURL optional | Merchant site response page URL that will receive the response from SmartRoute. It can help merchants have different response pages based on the requested service or other criteria.
|
| GenerateToken optional | This flag indicates whether to generate a token for the entered card information or not. It accepts the values “Yes” and “No”. Sending this field as “No” acts like when the field is not sent at all. This parameter is a part of the tokenization. For more information, see Tokenization.
|
| Token optional | The token is used in this request; to represent a previously used card information. This parameter is a part of the tokenization parameters. For more information, see Tokenization.
|
| AgreementID optional | 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 optional | An alphabetic value that is used to distinguish if the recurring transaction initiated is of type unscheduled or recurring. Provide this value if the payment is first in a series of payments. Supported values are:
|
| FailedResponseBackURL optional | Merchant site Failed response page URL that will receive the failed response from SmartRoute. It can help merchants have different response pages based on the requested service or other criteria, if not set, the failed response will be sent to the URL set in (ResponseBackURL)
|
Response Parameters
| Parameter | Description |
|---|---|
Response.StatusCode required | An alphanumeric value that represents the response code that covers errors generated by the SmartRoute. Appendix A: Direct Post 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 – Direct Post 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: If Version is 1.0 :
Condition: The SmartRoute operation team, upon merchant enrollment, provides possible Card Names. |
| Response.CardExpiryDate optional | An alphanumeric value that represents the expiry date of the card in MMYY format. For example, 1221 for 12th December.
|
| Response.CardHolderName optional | An alphanumeric value that represents the cardholder name.
|
| Response.CardNumber optional | An alphanumeric value that represents the masked Card Number.
|
| 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.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.IssuerName Conditional | An Alphanumeric value indicates the Bank Issuer Name.
Condition: This parameter will be provided back to the merchant if the provided version in the request is 3.1. |