iFrame

Basic requirements for integrating with PayHQ iFrame

1. Enable iFrame from your PayHQ account

2. Generate your iFrame access token

3. Use this access token in your iFrame integration code

4. Request payment token for your transaction

5. Exchange the payment token to complete the transaction

Before you start

1. Please make sure you have access to PayHQ Sandbox account

2. Go to https://www.payfirma.com/signup or call 1 [phone] and ask for a Payment Advisor to set up a Demo / Sandbox Account for you.

iFrame in action

You can visit https://payhq-iframe-test-demo.firebaseapp.com/ to see the iFrame in action. You can use the test card data mentioned on this page to complete a test transaction.

Important URL

Sandbox – https://sandbox.payfirma.com

Test – https://test.payfirma.com

Production – https://hq.payfirma.com

Integration Process

The integration process comprises of 3 stages

1. Stage 1 – Your team works on the integration work by using the Sandbox account

2. Stage 2 – After you finish your integration we will help you go through a certification process to make sure that your integration satisfies your end goal that you had for this integration.

3. Stage 3 – Request a production PayHQ account. Make sure you change all the URLs in your code to point to the production environment before you go live with your code.

Enable iFrame and generate access token

1. Login to your merchant account

2. Click “Settings” on the top right menu

3. Select “Hosted Pay Page and iFrame” tab on settings page

4. At the top of the page that opens you will see the iFrame Settings

Click the create button on the right to generate your iFrame token

1. You will notice that the iFrame access token has been generated. You have an option to delete or refresh the access token as per your requirements

2. At this point you are ready to start writing your code to integrate iFrame into your web page.

Write your integration code

1. Link the PayHQ iFrame Javascript library in the webpage where you will be adding the iFrame. The URL of this library for the test environment is https://test-iframe.payfirma.com/payhq-js/payhq-iframe-lib-test.min.js

2. Add three placeholder div elements in your webpage to hold the iFrames for card number, expiry date and CVV. At this point it’s important to know that PayHQ iFrame is not a single iFrame that you add to your webpage. It comprises three different iFrames, one each for card number, expiry date and CVV. This gives you more flexibility to design your UI the way you want to.

3. You may choose to provide any id of your choice to the three placeholder divs you added in step 2

4. The next step is to write Javascript code to initialize the iFrame in your webpage. (See example below)

5. At this point you should be ready to run your webpage and see the iFrame in action.

Step 4 - script tag

START SCRIPT TAG
                    // 4.1 select the payfirma test environment
                    // LIVE, TEST, SANDBOX
                    const environment = 'TEST' 

                    // 4.2 set apiKey for authorization token
                    const apiKey = "iframe access token";
                    
                    // 4.3 set options
                    var options = {
                      fields: {
                        cardNumber: {
                          selector: "#cardNumber_container",
                          placeholder: "Credit Card *",
                        },
                        cardExpiry: {
                          selector: "#cardExpiry_container",
                          placeholder: "Expires (MM/YY) *"
                        },
                        cardCvv: {
                          selector: "#cardCvv_container",
                          placeholder: "CVV *"
                        }
                      },
                      // set the CSS styles to apply to the payment fields
                      // camelCases instead dash-separated CSS attributes  
                      style: {
                        input: {
                                "fontFamily": "robotoregular,Helvetica,Arial,sans-serif",
                                "fontWeight": "700",
                                "fontSize": "1em",
                                "color": "#ff0000",
                                "backgroundColor": "#a2d157",
                        }
                      } 
                    };

                    // 4.4 init payfirma object
                    const payfirmaObject= Payfirma.payfirmaInit(environment, apiKey,options);
                      payfirmaObject.NumberField().render(options.fields.cardNumber.selector);
                      payfirmaObject.ExpiryField().render(options.fields.cardExpiry.selector);
                      payfirmaObject.CVVField().render(options.fields.cardCvv.selector);
                 
                    // 4.5 set button event 
                    document.querySelector('button#payNow').addEventListener('click', () => {
                      // 4.6 Get Form fields data
                      const formData = {first_name,last_name,email,amount}
      
                      // 4.7 get card token  
                      payfirmaObject.tokenize().then((response)=>{
                          // Set result
                          document.querySelector('#cardtoken-result').innerText = response.payment_token;

                          // If you need to check payment token expiry, 
                          // you need to make a logic with response.expires_in
                          // console.log('payment token will expire in ',response.expires_in + " seconds")
                          
                          // 4.8 Make a sale transaction with card token.
                          makeSaleRequest(response.payment_token, formData);
      
                      }).catch(error => {
                        // There was an error tokenizing your card data
                        console.log('error from server')
                        console.log(error);
                      })
                    });

                  END SCRIPT TAG
    

Request payment token

In the code shared above the payfirmaObject.tokenize() is responsible for submitting the card details to PayHQ backend and receive a payment token.

Complete the sale

1. The payment token received in the previous step can be used to complete the sale

2. Finally call the makeSaleRequest method to complete the sale. This method will make an API call to PayHQ backend and complete the sale

3. The response of the final sale method contains the lookup ID of the transaction. This lookup ID should be saved for performing refund operations in future.