Code Block

Step 1.
curl "https://apigateway.payfirma.com/customer-service/customer" 
--request POST  
--header "Content-Type: application/json"       
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data "{  
         "email": "brandon@stark.com",  
         "first_name": "Brandon",  
         "last_name": "Stark",  
         "company": "Payfirma",  
         "bcc_emails": "john.snow@stark.com",  
         "telephone": "1234567891",  
         "address1": "No. 1 Road",  
         "address2": "Street 2",  
         "city": "Vancouver",  
         "province": "BC",  
         "country": "Canada",  
         "postal_code": "V6E 1B2", 
         "custom_id": "Internal456"}"
Step 2. 
curl "https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID/card/"
--request POST  
--header "Content-Type: application/json"  
--header "Authorization: Bearer {BEARER_TOKEN}"
 
--data '{
   
   "card_expiry_month": 11,
  
    "card_expiry_year": 16,
   
   "card_number": "4111111111111111",
 
     "cvv2": "595",
   
   "is_default": true,

      "card_description": 
       "test card"
}'

Making a payment on a stored card

...

Code Block

Step 1.
curl " https://apigateway.payfirma.com/plan-service/plan/"
--request POST      
--header "Content-Type: application/json"     
--header "Authorization: Bearer {BEARER_TOKEN}"      
--data "'{
 {   "name": "Sample Daily Plan",
    "amount": 10.99,
    "currency": "CAD",
    "frequency": "DAILY",
    "number_of_payments": 10,
    "send_receipt": false
}'
}"

Step 3. 
curl " https://apigateway.payfirma.com/customer-service/customer/{CUSTOMER_LOOKUP_ID}/subscription "
--request POST      
--header "Content-Type: application/json"   
--data '{
 { "plan_lookup_id": "{PLAN_LOOKUP_ID}",
  "card_lookup_id": "{CARD_LOOKUP_ID}",
  "amount": 10.99,
  "start_date": 1467760023000,
  "email": "brandon@stark.com",
  "description": "My test subscription"
} ”'

Reporting

Transaction reporting can be accessed through the PayHQ web application or through the PayHQ API.

...

Code Block

POST: https://sandbox-apigateway.payfirma.com/invoice/invoice_id_here/send/email_address_here

Headers
Content-Type:application/json Accept:application/json Authorization:Bearer
Response Sample
{
"email_address": "email_address_here"
}

Hosted Payment Page

Steps to setup HPP on PayHQ

Basic requirements for integrating with PayHQ Hosted Payment Page

Setup your hosted payment page
Provide the domain name and return page URL
Generate your access token
Use this access token to send payment request to the hosted payment page endpoint

Customer Vault Feature - If you would like to enable the customer vault feature for Hosted Payment Page (HPP), please inform our team and we will configure it from our admin side. With this feature, customers who have at least one card saved in the PayHQ will be able to make transactions using their saved card details.

Follow these steps to get started with HPP setup

Login to your merchant account
Open settings and select hosted payment page
Image Removed
Enter your domain, return URL and callback URL(optional) to setup your hosted payment page
Image Removed
Once you enter this your hosted payment page will get set up and you will notice that you have been provided the init endpoint to send transaction requests to.
Image Removed
But before you can start using the hosted payment page you will need the access token in order to get access to the backend functionality.
Click on Generate Token button to generate your access token
Image Removed
At this point you are all set to start integrating with our hosted payment page
Additionally if you are interested in collecting billing and shipping information on the hosted payment page then you can select the capture billing address and capture shipping address options. You can select both or just one of these options, depending on your requirements.
Image Removed
At this point you are done with creating your hosted payment page settings.
Next step is to use these settings in your e-commerce application.

Using the sample application

Clone the sample application
Open App.js and replace ENDPOINT, DOMAIN and TOKEN values with the InitEndpoint, domain entered in your HPP settings page and the access token respectively.
Open the package.json file and change the HTTPS and port settings as per your requirements

Run and test this demo application

Additional info:

Please note that if your platform will not be using PayHQ’s HPP module, then your company will need to complete the PCI DSS questionnaire for Service Providers to validate your adherence to PCI DSS with a Qualified Security Assessor (QSA)
▪ You can find a list of approved QSAs here: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors

iFrame Integration

Basic requirements for integrating with PayHQ iFrame

Enable iFrame from your PayHQ account
Generate your iFrame access token
Use this access token in your iFrame integration code
Request payment token for your transaction
Exchange the payment token to complete the transaction

Before you start

Please make sure you have access to PayHQ Sandbox account
Go to https://www.payfirma.com/signup or call 1 (800) 747-6883 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

Developer portal – https://developers.payfirma.com

Integration Process

The integration process comprises of 3 stages

Stage 1 – Your team works on the integration work by using the Sandbox account
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.
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

Login to your merchant account
Click “Settings” on the top right menu
Select “Hosted Pay Page and iFrame” tab on settings page
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

...

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
At this point you are ready to start writing your code to integrate iFrame into your web page.

Write your integration code

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
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.
You may choose to provide any id of your choice to the three placeholder divs you added in step 2
The next step is to write Javascript code to initialize the iFrame in your webpage. (See example below)
At this point you should be ready to run your webpage and see the iFrame in action.

Step 4 - script tag

Code Block
START SCRIPT TAG

Card Terminal

Card Terminal API

This document includes sample data and responses. For more information on the JSON to be sent in the body of

various requests, please refer to the request body (via the inspect manager) in your browser.

How To: Make a Sale using Customer Lookup

Code Block

POST: https://sandbox-apigateway.payfirma.com/transaction-service-vt/sale/terminalcustomer/customer_lookup_id
Headers
Content-Type:application/json
Authorization:Bearer
Body
{
"amount":"1.00",
"first_name":"customer_first_name",
"last_name":”customer_last_name",
"company":"company_name",
"order_id":"",
"invoice_id":"",
"description":"",
"currency":"CAD",
"email":"customer_email",
"card_expiry_month":"/",
"card_expiry_year":"",
"card_number":"",
"is_card_terminal_transaction":true,
"processor_id":123456
}
Response Sample
{
"amount": 1,
"email": "customer_email",
"first_name": "customer_first_name",
"last_name": "customer_last_name",
"company": "company",
"card_type": "OTHER", "card_suffix": "1933",
"id": 3039875,
"transaction_id": "62lY3jxBKrRk6yo1RkXN",
"transaction_success": true,
"transaction_result": "APPROVED",
"transaction_time": 1551297351000,
"transaction_type": "SALE"
}

How To: Make a Sale without Customer Lookup

Code Block

POST: https://sandbox-apigateway.payfirma.com/transaction-service-vt/sale/terminal
Headers
Content-Type:application/json
Authorization:Bearer
Body
{
"amount":"1.00",
"first_name":"",
"last_name":"",
"company":"", "bcc_emails":null, "telephone":"",
"address1":"",
"address2":"",
"city":"",
"province":"",
"country":"",
"postal_code":"",
"order_id":"",
"invoice_id":"",
"description":"",
"currency":"CAD",
"card_expiry_month":"/",
"card_expiry_year":"",
"card_number":"",
"is_card_terminal_transaction":true,
"processor_id":1234567
}
Response Sample
{
"amount": 1,
"card_type": "OTHER",
"card_suffix": "1933",
"id": 3039873,
"transaction_id": "N4kqMbjy0WEzKd7eZLQY",
"transaction_success": true,
"transaction_result": "APPROVED",
"transaction_time": 1551297100000,
"transaction_type": "SALE"
}

How To: Make a Refund

Code Block

POST: https://sandbox-apigateway.payfirma.com/transaction-service-vt/refund/transaction_id
Headers
Content-Type:application/json
Authorization:Bearer
Body
{
"amount":"1.00",
"first_name":"customer_first_name",
"last_name":"customer_last_name",
"company":"company_name",
"invoice_id":"invoice_id",
"currency":"CAD",
"email":"customer_email",
"is_card_terminal_transaction":true,
"processor_id":12345
}
Response
{
"amount": 1,
"email": "customer_email",
"first_name": "customer_first_name",
"last_name": "customer_last_name",
"company": "Payfirma",
"invoice_id": "000003039874",
"card_type": "OTHER",
"card_suffix": "1933",
"id": 3039877,
"transaction_id": "z6jAROvgvWj3vd14wZnl",
"transaction_success": true,
"transaction_result": "APPROVED",
"transaction_time": 1551297616000,
"transaction_type": "REFUND"
}

How To: Authorize a Card

Code Block

POST: https://sandbox-apigateway/transaction-service-vt/authorize/terminal
Headers
Content-Type:application/json
Authorization:Bearer
Body
{
"amount":"1.00",
"first_name":"customer_first_name",
"last_name":”customer_last_name",
"company":"company_name",
"order_id":"",
"invoice_id":"",
"description":"",
"currency":"CAD",
"email":"customer_email",
"card_expiry_month":"/",
"card_expiry_year":"",
"card_number":"",
"is_card_terminal_transaction":true,
"processor_id":123456
}
Response
{
"amount":1.00,
"card_type":"MASTERCARD",
"card_suffix":"2995", "id":3893431,
"transaction_id":"2lY3jxBKvvn66yo1RkXN",
"transaction_success":true,
"transaction_result":"APPROVED",
"transaction_time":1551304094000,
"transaction_type":"AUTHORIZE"
}

How To: Capture a Payment

Code Block

GET: https://sandbox-apigateway/transaction-service-vt/capture/transaction_id
Headers
Content-Type:application/json
Authorization:Bearer
Body
{
"amount":"1.00",
"invoice_id":"000003893431",
"currency":"CAD",
"is_card_terminal_transaction":true,
"processor_id":51832
}
Response Sample
{
"amount": 1,
"email": "ravinder.singh@payfirma.com",
"first_name": "Ravinder",
"last_name": "Singh",
"company": "Payfirma",
"invoice_id": "000003893432",
"card_type": "MASTERCARD",
"card_suffix": "2995",
"id": 3893434,
"transaction_id": "GXRKDxBl55z9pg04wY7W",
"transaction_success": true,
"transaction_result": "APPROVED",
"transaction_time": 1551304500000,
"transaction_type": "CAPTURE"
}

Hosted Payment Page

Steps to setup HPP on PayHQ

Basic requirements for integrating with PayHQ Hosted Payment Page

Setup your hosted payment page
Provide the domain name and return page URL
Generate your access token
Use this access token to send payment request to the hosted payment page endpoint

Customer Vault Feature - If you would like to enable the customer vault feature for Hosted Payment Page (HPP), please inform our team and we will configure it from our admin side. With this feature, customers who have at least one card saved in the PayHQ will be able to make transactions using their saved card details.

Follow these steps to get started with HPP setup

Login to your merchant account
Open settings and select hosted payment page
Image Added
Enter your domain, return URL and callback URL(optional) to setup your hosted payment page
Image Added
Once you enter this your hosted payment page will get set up and you will notice that you have been provided the init endpoint to send transaction requests to.
Image Added
But before you can start using the hosted payment page you will need the access token in order to get access to the backend functionality.
Click on Generate Token button to generate your access token
Image Added
At this point you are all set to start integrating with our hosted payment page
Additionally if you are interested in collecting billing and shipping information on the hosted payment page then you can select the capture billing address and capture shipping address options. You can select both or just one of these options, depending on your requirements.
Image Added
At this point you are done with creating your hosted payment page settings.
Next step is to use these settings in your e-commerce application.

Using the sample application

Clone the sample application
Open App.js and replace ENDPOINT, DOMAIN and TOKEN values with the InitEndpoint, domain entered in your HPP settings page and the access token respectively.
Open the package.json file and change the HTTPS and port settings as per your requirements

Run and test this demo application

Additional info:

Please note that if your platform will not be using PayHQ’s HPP module, then your company will need to complete the PCI DSS questionnaire for Service Providers to validate your adherence to PCI DSS with a Qualified Security Assessor (QSA)
▪ You can find a list of approved QSAs here: https://www.pcisecuritystandards.org/assessors_and_solutions/qualified_security_assessors

iFrame Integration

Basic requirements for integrating with PayHQ iFrame

Enable iFrame from your PayHQ account
Generate your iFrame access token
Use this access token in your iFrame integration code
Request payment token for your transaction
Exchange the payment token to complete the transaction

Before you start

Please make sure you have access to PayHQ Sandbox account
Go to https://www.payfirma.com/signup or call 1 (800) 747-6883 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

Developer portal – https://developers.payfirma.com

Integration Process

The integration process comprises of 3 stages

Stage 1 – Your team works on the integration work by using the Sandbox account
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.
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

Login to your merchant account
Click “Settings” on the top right menu
Select “Hosted Pay Page and iFrame” tab on settings page
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

...

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
At this point you are ready to start writing your code to integrate iFrame into your web page.

Write your integration code

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
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.
You may choose to provide any id of your choice to the three placeholder divs you added in step 2
The next step is to write Javascript code to initialize the iFrame in your webpage. (See example below)
At this point you should be ready to run your webpage and see the iFrame in action.

Step 4 - script tag

Code Block

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 *"
                        }
                      },
                      // 4.1 select the payfirma test environment set the CSS styles to apply to the payment fields
                      // LIVE, TEST, SANDBOX camelCases instead dash-separated CSS attributes  
                      style: {
                        input: {
       const environment = 'TEST'                       // 4.2 set apiKey for authorization token"fontFamily": "robotoregular,Helvetica,Arial,sans-serif",
                              const apiKey = "iframe access token";"fontWeight": "700",
                                "fontSize": "1em",
                                "color": "#ff0000",
           // 4.3 set options                  "backgroundColor": "#a2d157",
   var      options = {             }
         fields: {            } 
           cardNumber: {        };

                 selector: "#cardNumber_container",  // 4.4 init payfirma object
                    placeholder: "Credit Card *",const payfirmaObject= Payfirma.payfirmaInit(environment, apiKey,options);
                      payfirmaObject.NumberField().render(options.fields.cardNumber.selector);
 },                     payfirmaObject.ExpiryField().render(options.fields.cardExpiry.selector);
   cardExpiry: {                  payfirmaObject.CVVField().render(options.fields.cardCvv.selector);
        selector: "#cardExpiry_container",        
                  placeholder: "Expires (MM//YY) *"
   4.5 set button event 
                    },
document.querySelector('button#payNow').addEventListener('click', () => {
                       cardCvv: {
  // 4.6 Get Form fields data
                      const formData selector: "#cardCvv_container",= {first_name,last_name,email,amount}
      
                   placeholder: "CVV *" // 4.7 get card token  
                 }     payfirmaObject.tokenize().then((response)=>{
                 },         // Set result
           //  set the CSS styles to apply to the payment fields    document.querySelector('#cardtoken-result').innerText = response.payment_token;

               // camelCases instead dash-separated CSS attributes      // If you need to check payment token expiry, 
         style: {                // you need to make a logic with response.expires_in
input: {                         // console.log('payment token will expire in ',response.expires_in + "fontFamily seconds": "robotoregular,Helvetica,Arial,sans-serif",)
                          
      "fontWeight": "700",                   // 4.8 Make a sale transaction with card token.
     "fontSize": "1em",                    makeSaleRequest(response.payment_token, formData);
      
    "color": "#ff0000",                 }).catch(error => {
             "backgroundColor": "#a2d157",          // There was an error tokenizing your card data
      }                  console.log('error from server')
  }                      };console.log(error);
                      })
  // 4.4 init payfirma object              });

     const payfirmaObject= Payfirma.payfirmaInit(environment, apiKey,options);            END SCRIPT TAG
            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;

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

The payment token received in the previous step can be used to complete the sale
Finally call the makeSaleRequest method to complete the sale. This method will make an API call to PayHQ backend and complete the sale
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.

PayHQ Plugin - WooCommerce

Installation

The first step in your integration will be installing WooCommerce to your WordPress storefront.

Once you’ve logged into your WordPress account, you’ll be able to find the Plugins category in the main menu to the left side of the page, commonly just below Appearance. Click on

Plugins to expand available options before clicking on the revealed option Add New.

Under the Install Plugins header, you’ll find several options; the second, Upload, will enable you to select your .zip of the Payfirma WooCommerce plugin. Click on the Choose File button, and find your .zip of the Payfirma WooCommerce plugin.

Once your plugin is selected, click on Install Now. The plugin will install itself automatically, and after your installation is finished, click on Activate Plugin, just beneath the notification.

Configuration

One of our mandatory requirements for PayHQ is an SSL connection for credit card transactions. To force this, select your newly accessible WooCommerce option in the main menu on the left side of the page. Once the WooCommerce options have expanded in the menu, click on Settings.

From the Settings page, you will automatically be brought to the General Settings Tab. Ensure your Base Location and Currency are set.

Go to the Payments tab within Settings,

Go to Manage

This is where you will be able to enter your assigned Iframe Access Token, as provided through PayHQ Settings.

PayHQ Settings

To get Iframe Access Token

Please, Login at PayHQ and go to Settings. PayHQ Settings

Create Iframe Access Token

GitHub - Reference:

GitHub - Payfirma/New_Payfirma_Woo_Gateway

Download plugin:

https://github.com/Payfirma/New_Payfirma_Woo_Gateway/blob/master/download/Payfirma_Woo_Gateway.zip

EFT

Base URL

The base URL for all API requests is:

https://apigateway.payfirma.com

Balance

Code Block
GET /transaction-service-vt/eft/balance

Returns wallet balance for EFT to do instant transactions else would be a few days for settlement.

Response

Returns a JSON object with the following properties:

available_balance: fund available balance currently for transaction
actual_balance: total balance - Funds are in the wallet

Example:

Request

Code Block
GET /transaction-service-vt/eft/balance

Response:

Code Block
{ "available_balance": 13.36, "actual_balance": 13.36 }

Incoming Request - EFT Debit

Code Block
GET /transaction-service-vt/eft/incoming-requests

Returns list of incoming requests asking you for funds - EFT Debit

Response

Returns a JSON object with the following properties:

incoming_requests: Array of objects of incoming request
- amount: amount asking for processor_transaction_id: unique identifier
- email: email of the user asking for
- status: status of the request
- redirect_url: redirect URL to start EFT transaction date: date of the EFT request
- description: description of the EFT request

Example:

Request:

Code Block
GET /transaction-service-vt/eft/incoming-requests

Response:

Code Block

incoming_requests: [
    {
        "amount": 1,
        "processor_transaction_id": "PAY24204476",
 // If you need to check payment token expiry"email": "sample@gmail.com",
        "status": "PENDING",
                 // you need to make a logic with response.expires_in"redirect_url": "https://sample.com?redirect",
                          // console.log('payment token will expire in ',response.expires_in + " seconds")"date": "1/17/2024 11:26:40 PM",
        "description": "API Test Doc"
    }
    ]

Requesting Funds - EFT Credit

Code Block
POST /transaction-service-vt/eft/request/{customer_lookup_id}

Requesting funds to PayHQ customer via EFT - EFT Credit

Request Body

Code Block
{ "amount": 1, "description": "API Test Doc" }

Response

Returns a JSON object with the following properties:

amount: amount requested
email: email of the customer request sent to
card_type: Type of Card Transaction(Internal Use)
description: description of the EFT request sent
id: unique identifier for PayHQ
transaction_id: unique identifier for PayHQ hashed
transaction_success: Is request sent successfully
transaction_result: result of the EFT request sent - at first would be “PENDING” until other user do some action on it. Status would be updated on your side too
transaction_time: time of request epoch time format transaction_type: Type of the transaction(Internal Use)

Example:

Request:

Code Block
POST /transaction-service-vt/eft/request/{customer_lookup_id}

Response:

Code Block

{
                  // 4.8 Make a sale transaction with card token."amount": 1,
    "email": "sample@gmail.com",
    "card_type": "EFT",
    "description": "API Test Doc",
    "id": 9587492,
      makeSaleRequest(response.payment_token, formData);"transaction_id": "8Xj5QZyE499o9dGv6pA2",
    "transaction_success": true,
    "transaction_result": "PENDING",
    "transaction_time": 1705534494112,
    "transaction_type": "EFT_CREDIT"
}

Bank Deposit:

Code Block
POST /transaction-service-vt/eft/bank-deposit

Deposit to your linked bank account from your wallet available balance

Request Body

Code Block
{ "amount": 1 }

Response:

Only status 200 - If successful else 400 with error message

Example:

Request:

Code Block
POST /transaction-service-vt/eft/bank-deposit

Send Funds - EFT Debit

Code Block
POST }).catch(error => { /transaction-service-vt/eft/send/{customer_lookup_id}

Send funds to the customer’s Bank account directly - EFT Debit

Request Body

Code Block

{
    "amount": 1,
    "description": "API Test Doc",
    "transit_number": "12345",
    "institution_number": "123",
// 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

The payment token received in the previous step can be used to complete the sale
Finally call the makeSaleRequest method to complete the sale. This method will make an API call to PayHQ backend and complete the sale
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.

PayHQ Plugin - WooCommerce

Installation

The first step in your integration will be installing WooCommerce to your WordPress storefront.

Once you’ve logged into your WordPress account, you’ll be able to find the Plugins category in the main menu to the left side of the page, commonly just below Appearance. Click on

Plugins to expand available options before clicking on the revealed option Add New.

Under the Install Plugins header, you’ll find several options; the second, Upload, will enable you to select your .zip of the Payfirma WooCommerce plugin. Click on the Choose File button, and find your .zip of the Payfirma WooCommerce plugin.

Once your plugin is selected, click on Install Now. The plugin will install itself automatically, and after your installation is finished, click on Activate Plugin, just beneath the notification.

Configuration

One of our mandatory requirements for PayHQ is an SSL connection for credit card transactions. To force this, select your newly accessible WooCommerce option in the main menu on the left side of the page. Once the WooCommerce options have expanded in the menu, click on Settings.

From the Settings page, you will automatically be brought to the General Settings Tab. Ensure your Base Location and Currency are set.

Go to the Payments tab within Settings,

Go to Manage

This is where you will be able to enter your assigned Iframe Access Token, as provided through PayHQ Settings.

PayHQ Settings

To get Iframe Access Token

Please, Login at PayHQ and go to Settings. PayHQ Settings

Create Iframe Access Token

GitHub - Reference:

GitHub - Payfirma/New_Payfirma_Woo_Gateway

Download plugin:

https://github.com/Payfirma/New_Payfirma_Woo_Gateway/blob/master/download/Payfirma_Woo_Gateway.zip

Shopify

Configuration

Install the app

Shopify Settings
Select Payments
Select Search by Provider
Search for “Merrco Payments”
Select Merrco Payments Activate and Connect

Connect to PayHQ

...

Select settings within the Merrco Payments app

...

Enter your PayHQ login credentials

...

Enable both capture billing and shipping address

...

 "account_number": "123467"
}

Response

Returns a JSON object with the following properties:

amount: amount to send
email: email of the customer
first_name: first name of the customer
last_name: last name of the customer
province: province(in code) - BC
country: country(in code) - CA
card_type: Type of Card Transaction(Internal Use) description: description of the EFT request sent
id: unique identifier for PayHQ
transaction_id: unique identifier for PayHQ hashed transaction_success: Is request sent successfully
transaction_result: result of the EFT request sent - at first would be “PENDING” until other user do some action on it. Status would be updated on your side too
transaction_time: time of request epoch time format
transaction_type: Type of the transaction(Internal Use)

Example:

Request:

Code Block
POST /transaction-service-vt/eft/send/{customer_lookup_id}

Response:

Code Block

{
    "amount": 1,
    "email": "sample@payfirma.com",
    "first_name": "Sample",
    "last_name": "Test",
    "province": "BC",
    "country": "CA",
    "card_type": "EFT",
    "description": "API Test Doc - Account Number: ***1234",
    "id": 9587494,
    "transaction_id": "EmJVqxBX1ZZKogz6NeGn",
    "transaction_success": false,
    "transaction_result": "PENDING",
    "transaction_time": 1705535538104,
    "transaction_type": "EFT_DEBIT"
}

Shopify

Configuration

Install the app

Shopify Settings
Select Payments
Select Search by Provider
Search for “Merrco Payments”
Select Merrco Payments Activate and Connect

Connect to PayHQ

Select settings within the Merrco Payments app
Enter your PayHQ login credentials
Enable both capture billing and shipping address
Select Activate

Partner Integration

Partner Code:

Please note that each partner will be assigned a three-letter word by Merrco Payfirma (please ask us if you require one).

To tag all transactions originating from your application, please send your assigned three-letter word

in the custom_id field in the sales request packet. This identifying word will help us to reconcile all data for

merchants using your application.

Sandbox Environment:

Create a Sandbox Account:

To create a sandbox account for testing, kindly proceed by completing the form accessible through the following link: Sandbox PayHQ Select "Request one today!" during the process.

Endpoints:

Please note that all URLs mentioned in the API documentation point to our live environment. To point them

to our sandbox environment, all URLs in the format https://xxxx.payfirma.com need to be replaced with

https://sandbox-xxxx.payfirma.com, which will start pointing to the sandbox environment.

Test Processor:

The Test Processor is a simulated processor designed for testing purposes, featuring placeholder processing logic. Specific outcomes are triggered based on the following conditions:

All transactions with an odd amount (digits before decimals) will be approved.
All transactions with an even amount (digits before decimals) will be declined.
Refunds exceeding the actual sale amount will be declined.
Captures with an even amount will also be declined.

Special Cases:

$2.10 will result in a decline with the reason "Failed to tokenize card information."
$2.20 will result in a decline with the reason "Email is required."
$2.30 will result in a decline with the reason "Missing mandatory card information field(s) in the request."
$2.40 will result in a decline with the reason "Transaction Not Supported."
$2.50 will result in a decline with the reason "Failed to de-tokenize card information."
$2.60 will result in a decline with the reason "Failed to authorize."

Important info:

Production environment: https://hq.payfirma.com/#/login
Sandbox environment: https://sandbox.payfirma.com/#/login
Email: partnersupport@merrco.com

Page Comparison

Versions Compared

Old Version 24

New Version Current

Key

Making a payment on a stored card

Reporting

Hosted Payment Page

Steps to setup HPP on PayHQ

Using the sample application

Additional info:

iFrame Integration

Basic requirements for integrating with PayHQ iFrame

Before you start

iFrame in action

Important URL

Integration Process

The integration process comprises of 3 stages

Enable iFrame and generate access token

Write your integration code

Card Terminal

Card Terminal API

How To: Make a Sale using Customer Lookup

How To: Make a Sale without Customer Lookup

How To: Make a Refund

How To: Authorize a Card

How To: Capture a Payment

Hosted Payment Page

Steps to setup HPP on PayHQ

Using the sample application

Additional info:

iFrame Integration

Basic requirements for integrating with PayHQ iFrame

Before you start

iFrame in action

Important URL

Integration Process

The integration process comprises of 3 stages

Enable iFrame and generate access token

Write your integration code

Request payment token

Complete the sale

PayHQ Plugin - WooCommerce

Installation

Configuration

EFT

Base URL

Balance

Response

Incoming Request - EFT Debit

Response

Requesting Funds - EFT Credit

Request Body

Response

Bank Deposit:

Request Body

Response:

Send Funds - EFT Debit

Request Body

Request payment token

Complete the sale

PayHQ Plugin - WooCommerce

Installation

Configuration

Shopify

Configuration

Install the app

Connect to PayHQ

Response

Shopify

Configuration

Install the app

Connect to PayHQ

Partner Integration

Partner Code:

Sandbox Environment:

Create a Sandbox Account:

Endpoints:

Test Processor:

Important info: