Transaction Validation
Once you've received a response that signifies a completed transaction, such as a payment completion redirect, you may want to validate the transaction. Validation is not required, but if you're bound by regulatory requirements or simply want to double-check that the transaction has not been altered in transit, you can validate it.
There are two ways to validate a transaction:
By comparing the MAC (message authentication code) received from Hyp with the MAC that you calculate yourself.
By making an additional API call, providing the transaction ID and receiving a response that confirms the outcome of the transaction.
Validating a transaction using the MAC
The preferred way of validating a transaction is by comparing the MAC (message authentication code) that Hyp provides in the payment completion redirect with the MAC that you calculate yourself. This method does not introduce any network latency and can be safely used to validate all transactions.
In the query string that Hyp passes in the payment completion redirect, one of the parameters, responseMac, is the transaction MAC that Hyp calculates. You should use several of the other parameters, along with your merchant password, to calculate the MAC on your end, and then compare it to responseMac. If they're identical, the transaction is valid.
First, concatenate the following values in this exact order:
Your merchant password.
txId(transaction ID) from the payment completion redirect.errorCode(if received;000otherwise).cardToken(if received; an empty string otherwise).cardExp(if received; an empty string otherwise).personalId(if received; an empty string otherwise).uniqueId(your unique merchant ID).
If any parameters are empty, use an empty string instead. One notable exception is errorCode: if it's empty, use the value 000.
Hash the resulting string using SHA-256, convert it to Base64, and compare the resulting value with responseMac.
For a hands-on example of validating a transaction using the MAC in a sample Express.js application, see Basic Integration Flow: Hello World With a Full Working Charge.
Validating a transaction using an API call
You can also validate a transaction by making an additional API call, which is a variation of a transaction inquiry. This call adds network latency compared to the MAC validation method, but the upside is that it provides more information about the transaction (card type, issuer, etc.) if that's what you're looking for.
To validate a transaction, send a standard Hyp API request. In the int_in parameter, include an XML payload with the inquireTransactions command. The XML payload should look like this:
The command element should be set to inquireTransactions, and the inquireTransactions element must include the following child elements:
terminalNumber: a unique number assigned to you as a merchant during registration.
mid: merchant ID assigned to you as a merchant during registration.
mpiTransactionId: the transaction ID that is returned as thetxIdparameter in the payment completion redirect.queryName: must be set tompiTransaction.
If the transaction is found, the response will look like this:
In the success response, the row element inside inquireTransactions contains values you can compare with those from the payment completion redirect. The table below shows how the redirect parameters map to response elements:
uniqueID
uniqueid
cardExp
cardExpiration
cardToken
cardId
cardMask
cardMask
authNumber
authNumber
cgUid
cgUid
If all the values match, the transaction is valid.
If the API call does not find a transaction with the given mpiTransactionId, the transaction is invalid and the response looks like this:
Note that, like other transaction inquiries, this API call is not intended for every transaction. Use it only when you need to verify specific transactions and retrieve extended details about them. If you need to validate all transactions, use the MAC validation method instead.
Last updated
Was this helpful?