Transaction Response

Upon completion, the transaction details will be sent back to the defined ‘responseSuccessURL’ or ‘responseFailURL’ as hidden fields. You can define these URLs in your transaction request.

Standard set

Field NameDescriptionValue
approval_codeApproval code for the transaction. The first character of this parameter is the most helpful indicator for verification of the transaction result.Y indicates that the transaction has been successful, N indicates that the transaction has not been successful, ? indicates that the transaction has been successfully initialized, but a final result is not yet available since the transaction is now in a waiting status. The transaction status will be updated at a later stage.
oidOrder ID, if not defined in the request, the Gateway generates it automaticallye.g. C-2101f68a-45e9-4f3c-a6da-1337d5574717
refnumberReference number-
statusTransaction statusAPPROVED, DECLINED (by authorisation endpoint or due to fraud prevention settings),FAILED (wrong transaction message content/parameters, etc.) or WAITING (asynchronous Alternative Payment Methods)
txndate_processedTime of transaction processing-
ipgTransactionIdTransaction identifier assigned by the Gateway, e.g. to be used for a Void-
tdateIdentification for the specific transaction-
fail_reasonReason the transaction failed-
response_hashHash-Value to protect the communication See note below-
extended_response_hashHash-Value to protect the communication, where all response parameters are included in the hash calculation see note below.
processor_response_codeThe response code provided by the backend system.Note that response codes can be different depending on the used payment type and backend system. While for credit card payments, the response code 00 is the most common response for an approval, the backend for giropay transactions for example returns the response code 4000 for successful transactions.
fail_rcInternal processing code for failed transactions-
terminal_idTerminal ID used for transaction processing-
ccbin6 digit identifier of the card issuing bank-
cccountry3 letter alphanumeric ISO code of the cardholder’s countrye.g. USA, DEU, ITA, etc. Filled with N/A if the cardholder’s country cannot be determined or the payment type is not credit card
ccbrandBrand of the credit or debit cardMASTERCARD, VISA, AMEX, DINERSCLUB, JCB, CUP, CABAL, MAESTRO, RUPAY, BCMC, SOROCRED. Filled with N/A for any payment method which is not a credit card or debit card.
merchantAdviceMessageUsed in the authorization response, for both approved and declined transactions, indicating when consumer non-reloadable prepaid cards and single-use VCNs are recognized.-

Hash Validation

Make sure to use the parameter response_hash to recheck if the received transaction response has really been sent by Fiserv to protect you from fraudulent manipulations. The value is created with a HMAC Hash using the following parameter string:

   approval_code|chargetotal|currency|txndatetime|storename

Shared secret (sharedsecret) will be used as a key in HMAC to calculate the hash with the above hash string. The hash algorithm is the same as the one that you have set in the transaction request.

Please note that you have to implement the response hash validation, when doing so remember to store the txndatetime that you have submitted with the transaction request in order to be able to validate the response hash. Furthermore, you must always use the https-connection (instead of http) to prevent eavesdropping of transaction details.

You can also use the parameter extended_response_hash to include all response parameters in the hash calculation. Please contact your local support team if you want to enable this feature. This will be managed with a specific setting performed on your account (service configuration extendedResponseHashSupported).

Creating the extended response hash:

  • Step 1: Retrieve all non-empty Gateway specified response parameters and then remove the parameter extended_response_hash from your list, so that it will not get included in the hash calculation. Consider also that shared secret will be used as a key in HMAC to calculate the hash and the hash algorithm must be the same as the one that you have set in the transaction request.
  • Step 2: Sort the response parameters in ascending order of the parameter names, where the upper-case characters come before the lower case (based on ASCII value). Join the parameters’ values to one string with pipe separator (use only parameters’ values and not the parameters’ names).
  • Step 3: Pass the created string to the HMAC algorithm while using shared secret (‘sharedsecret’) as a key for calculating the hash value.
  • Step 4: Encode the result of HMAC with Base64 to generate the extended response hash. Only HMAC algorithm (i.e.: HMACSHA256, HMACSHA384 or HMACSHA512) is supported for generating the extended response hash.

3-D Secure transactions

Response code indicates the classification of the transaction, values are valid for both HPP and APIs.

Field NameDescription
response_code_3dsecure OR
responseCode3dSecure
1 - Successful authentication (VISA ECI 05, MasterCard ECI 02)
2 - Successful authentication without AVV (VISA ECI 05, MasterCard ECI 02)
3 - Authentication failed / rejected by the DS or ACS (transaction declined by the Gateway)
4 - Authentication attempt (VISA ECI 06, MasterCard ECI 01)
5 - Unable to authenticate / DS not responding (VISA ECI 07)
6 - Unable to authenticate / ACS or DS are unable to authenticate the cardholder (VISA ECI 07)
7 - Cardholder not enrolled for 3-D Secure (VISA ECI 07) - relevant for 3DS 1.0
8 - Invalid 3-D Secure values received
9 - Tokenisation (tokenised PAN, eWallet)

Credential-on-file transactions

Field NameDescription
schemeTransactionIdReturned in the response by a scheme for stored credentials transactions to be used in subsequent transaction requests as a reference

Currency Conversion (Global Choice™) transactions

Field NameDescription
dcc_foreign_amountConverted amount in cardholder home currency. Decimal number with dot (.) as a decimal separator
dcc_foreign_currencyISO numeric code of the cardholder home currency. This transaction is performed in this currency
dcc_margin_rate_percentagePercent of margin applied to the original amount. Decimal number with dot (.) as a decimal separator
dcc_rate_sourceName of the exchange rate source (e.g. Reuters Wholesale Inter Bank)
dcc_rateExchange rate. Decimal number with dot (.) as a decimal separator
dcc_rate_source_timestampExchange rate origin time. Integer - Unix timestamp (seconds since 1.1.1970)
dcc_acceptedIndicates if the card holder has accepted the conversion offer (response value ‘true’) or declined the offer (response value ‘false’)

iDEAL transactions

Field NameDescription
accountOwnerNameName of the owner of the bank account that has been used for the iDEAL transaction
ibanIBAN of the bank account that has been used for the iDEAL transaction

SEPA Direct Debit as part of the Local Payments offering

Field NameDescription
mandateReferenceMandate reference as returned for the first direct debit transaction
mandateDateDate of the initial direct debit transaction as returned for the first transaction
mandateTypeRepresents a type of Direct Debit transactions that are based on mandates
for recurring collections.
Available values:
'single' - for a single (one-off) debit collections (default value)
'firstCollection' - for initial debit collection
'recurringCollection' - for subsequent recurring debit collection; to be
submitted together with 'mandateReference' field
'finalCollection' - for the last recurring debit transaction in a serie
mandateUrlThe field to be used for submitting a URL for SEPA Direct Debit mandate
processed via Local Payments. Must be submitted together with
mandateReference and mandateDate

SEPA Direct Debit as part of the TeleCash offering

Field NameDescription
bnameAccountholder's name
ibanBank account IBAN
bicBIC is provided only if the German IBAN has been used
mandateReferenceMandate reference as returned for the first direct debit transaction
mandateDateInitial debit transaction date

Global Merchant Acquiring model

Field NameDescription
associationResponseCodeThe raw association value tells exactly how the issuer has responded to the transaction without any mapping done either by the authorization platform or the Gateway. It will be returned only for Visa, MasterCard, Amex, and Discover

Partial Approval

Field NameDescription
PartiallyApprovedAmountAvailable balance as a partial amount approved.
StatusTransaction status: ‘PARTIALLY APPROVED’.
This unique status allows you to identify this transaction and subtract the partially approved amount from the total transaction amount, and request another form of payment, using split-tender functionality.

Account Updater Service transactions

When your store is enabled for the MasterCard real-time account updater service on the Gateway, and you have the payment information vaulted on your side then when applicable the updates are sent as part of the Gateway response, and you have to react upon it accordingly i.e.: update the account number for a token when you store PAN and a token on your side.

Field NameDescription
updatedPANUpdated primary account number (PAN)
updatedExpirationDateUpdated expiry date
updatedAccountStatusTypeUpdated account status can have one of the following values:
ACCOUNT_CHANGED- Either the account number or account number along with the expiration date are being updated. Use the new account information going forward. The new account information should also be used in case of authorization reversals.
ACCOUNT_CLOSED- Closed account advice. This account has been closed. Try alternate method of payment on subsequent authorization or retries.
EXPIRY_CHANGED- Expiry date change. Use the new expiry information going forward. This should also be used in case of authorization reversals.
accountUpdaterErrorCodeError codes indicating the system/server communication errors.

When you are processing on the Fiserv North frontend (Nashville) endpoint and your store is enabled for account updater services:

Field NameDescription
updatedPANUpdated primary account number (PAN)
updatedExpirationDateUpdated expiry date
updatedAccountStatusTypeUpdated account status can have one of the following values:
ACCOUNT_CHANGED- Either the account number or account number along with the expiration date are being updated. Use the new account information going forward. The new account information should also be used in case of authorization reversals.
ACCOUNT_CLOSED- Closed account advice. This account has been closed. Try alternate method of payment on subsequent authorization or retries.
EXPIRY_CHANGED- Expiry date change. Use the new expiry information going forward. This should also be used in case of authorization reversals.
CONTACT_CARDHOLDER- Contact cardholder advice. Account updater cannot provide updates on this account owing to restrictions from cardholder. Use an alternate method of payment or contact customer to get one.
hostedDataIdReturned when the updates have been applied. New (TransArmor) token has to be used in place of the old/previous one. Note, that the old/previous token will not be deleted but will be honored by the gateway till the old payment information (account number) will be honored by the scheme (Visa).
accountUpdaterErrorCodeError codes indicating the system/server communication errors.

Validity & Errors

Additionally when using your own error page for negative validity checks (full_bypass=true):

Field NameDescription
fail_reason_detailsComma separated list of missing or invalid variables. Note that fail_reason_details will not be supported in case of payplus and fullpay mode.
invalid_cardholder_datatrue – if validation of card holder data was negative. false – if validation of card holder data was positive but transaction has been declined due to other reasons.

Server-to-server Notification

In addition to the response you received in hidden fields to your responseSuccessURL or responseFailURL, the Gateway can send server-to-server notifications with the above result parameters to a defined URL. This is useful to keep your systems in sync with the status of a transaction. To use this notification method, you can specify an URL in the Customisation section of the Virtual Terminal or submit the URL in the following additional transaction parameter transactionNotificationURL.

Please note, that:
• The transaction URL is sent as received therefore please don’t add additional escaping (e.g.: using %2f for a Slash(/).
• No SSL handshake or verification of SSL certificates will be done in this process.
• The notification URL needs to listen on port 443 (https) – other ports are not supported.

The response hash parameter for validation (using the same algorithm that you have set in the transaction request) notification_hash is calculated as follows:

chargetotal|currency|txndatetime|storename|approval_code

Shared secret (sharedsecret) will be used as a key in HMAC to calculate the hash with the above hash string.

Such notifications can also be set up for the recurring payments that get automatically triggered by the Gateway. Please contact your local support team to get a shared secret (rcpSharedSecret) agreed for these notifications. You can configure your Recurring Transaction Notification URL (rcpTransactionNotificationURL) in the Customisation section of the Virtual Terminal.

In case of the recurring transactions the response hash parameter notification_hash is calculated differently as follows:

chargetotal+rcpSharedSecret+currency+txndatetime+storename+approval_code

The shared secret (rcpSharedSecret) is part of the string (it is not used as a key in HMAC to calculate the hash with the hash string). Moreover, the response hash parameter for the recurring transaction notifications is calculated with the SHA256-value (as the default value).


Want a quick overview?