Recurring Pre-Authorization Payment
- 16 Jul 2024
- 6 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Recurring Pre-Authorization Payment
- Updated on 16 Jul 2024
- 6 Minutes to read
- Contributors
- Print
- DarkLight
- PDF
Article summary
Did you find this summary helpful?
Thank you for your feedback
Recurring pre-authorization payment is an agreement where the payer authorizes the merchant to process pre-authorization payments for recurring bills or invoices at agreed intervals.
Merchant can submit recurring pre-authorization payments for processing to SmartRoute where the payer agrees to store their payment details for future use and authorizes the merchant to initiate subsequent recurring pre-authorization payments without their active participation.
The merchant should provide the AgreementID in the recurring message. This AgreementID should be the same one used in the early first transaction where the payer performed the authentication (i.e. 3DS authentication).
It is based on the API communication model described in the Communication Model section.
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.
|
| 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 – Recurring 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 is used in the payment. If they sent PaymentMethod parameter is 1 (Card), this parameter is required.
|
| ExpiryDateYear conditional | The customer’s card expiry date (year)digits 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).
|
| 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.
|
| AgreementID conditional | The same agreement Id that is used in the first transaction (Payment, Pre-Authorization or Verify). The value should be same across the recurring series.
|
| 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. If the PaymentMethod parameter is 1 (Card) is sent, this parameter is required.
Note: This parameter is optional if no token is present. It should not be included in the Secure Hash. Spaces are allowed in the cardholder's name. |
| ItemID optional | An alphanumeric value that represents the custom item ID.
|
| 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.
|
| 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"
|
| FrameworkInfo optional | 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.
|
Response Parameters
| Parameter | Description |
|---|---|
Response.StatusCode required | An alphanumeric value that represents the response code that covers errors generated by the SmartRoute. Appendix A: Recurring 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 response parameters appended in alphabetical order based on the parameter’s name, with no separators and no terminating character. Appendix B: Secure Hash – Recurring 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.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.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 |