Integration Guide
Below, the development steps.
Hash Generation
Each of the transactions made through the Connect solution requires the inclusion of a security hash to ensure the integrity of the message on our server.
To achieve this, we will need, at a minimum, the following parameters within our HTML form in the specified order (additional parameters may be required depending on the operation).
Parameter Name | Definition | Example |
---|---|---|
Charge total | The total amount of the transaction using a point or a comma as a decimal separator | 13.00 |
checkoutoption | Set the value of this parameter to "combinedpage" combinedpage for a standard payment page integration. | |
currency | The Transaction Currency ISO numeric code 484 is the code for Mexican pesos, 840 USD. | 484 |
hash_algorithm | Indicates the algorithm used for hash calculation. Possible valid values are: HMACSHA256. | HMACSHA256 |
responseFailURL | The URL you want to direct customers to after a successful or transaction | https://localhost:8643/webshop/response_success.jsp |
storenme | The StoreID that we will provide you by mail, always start with 62 | 62666666 |
timezone | Time zone of the transaction in Area/Location format according to IANA format | America/Mexico_City |
txndatetime | YYYY:MM:DD-hh:mm:ss exact transaction time (24-hr format). Never use a fixed value. It must always match the specified timezone | 2022:05:11-12:32:45 |
txntype | 'sale’, 'preauth’, 'postauth’, or ‘payer_auth’ | sale |
sharedsecret | The key we have shared for hash calculation | TopSecret |
Form Parameters
Step 1 - The hash needs to be calculated using ALL the parameters you are going to send.
Create a list of all the parameters to be sent and order them alphabetically by the parameter name (except sharedsecret and hashExtended).
With the sorted parameter list, concatenate the values of the parameters separated by pipes "|" to generate a single string.
Step 2 - We must encrypt the previously created string using the HMCASHA256 algorithm and the SharedSecret shared with you as the key to generate the calculated Hash value.
It is important that the value obtained from this operation remains in binary format and is not converted to a string, as this could cause issues in the second step.
In PHP, the correct syntax for this step is to include the raw_output parameter as true. When set to true, the output will be raw binary data:
Step 3 - Encode the returned value of the HMACSHA256 algorithm using Base64. This encoded value is the one you can use for the hashExtended parameter within the HTML form to be sent.
Hash Validation
A very good security practice is also to validate the hash obtained in response to each transaction. This is done to ensure that the integrity of the message has been preserved when receiving a response.
To do this, we will perform the following steps:
- Generate a string with the following command:
approval_code|chargetotal|currency|txndatetime|storenamestr = “N: -5010:Hosted data was not found|10.00|484| 2023:02:17-09:13:19|6266666”
Replace the parameters with the values obtained in your response. - Use the string from the previous step and encrypt it using your SharedSecret and the HMACHSHA256 algorithm.
- Convert the value to base64 and compare it with the value obtained in response_hash. If they match, it is evidence that the information comes from Fiserv and not from a malicious agent.
Order ID (oid)
This is the parameter that will help us identify each of our transactions. By default, it is not necessary to include it in the form, as the gateway automatically generates this field and returns it to us in the response as "oid."
Example: C-424d61f0-2225-4EC8-b2e0-db2a8f926422
However, if we want to use our own "oid," we can send it in the form as follows. It is important not to forget to include this parameter in the hash calculation:
It has a limit of 78 characters with the following allowed character ranges: A-Z, a-z, 0-9, "-".
Now, for each transaction, we need to generate a unique "oid" to ensure correct identification of each transaction (whether approved or declined). In addition, we need to ensure that the user cannot reuse an "oid" since doing so would result in an error.
Direct sales
Below is a form representing a $100.00 MXN sale taking place on January 2, 2020, at 12:51:05 PM for the store with ID 399000002. After completing the transaction, the buyer is redirected to the URLs specified in responseFailURL or responseSuccessURL.
iFrame
If you want to embed your form within an iFrame, consider the following steps:
-
Add the following JavaScript code snippet to your "Checkout" page. This way, you can receive notifications of the transactions made and redirect the buyer to the "SUCCESS" or "ERROR" page
-
Create a simple payment form with HTML on your website and on the "Checkout" page. Additionally, to the parameters of Direct Sale, add the target attribute to the form element and the parentUri parameter.
Updated 6 months ago