Skip to main content
Skip table of contents

Setup GIACT eCheck Verification

GIACT’s gVERIFY® provides real-time status updates for business or customer accounts, ensuring they are validated before approving a deposit or accepting payment.

Getting Started

Before running eCheck Verifications for Merchant transactions, you need to set up a GIACT eCheck Verification Fee and then apply it to the Merchant or add the Merchant to an existing Group with the fee set up.

Setting Up a GIACT eCheck Verification Fee to apply on a Merchant

Complete all steps in the following sections.

Create a New Group

  1. Access the Groups page.

  2. Click ADD GROUP.

  3. Enter the group name.

  4. Click CREATE GROUP.


Apply the GIACT eCheck Verification Fee to the Group

  1. From the Group Profile, click the Fees tab.

  2. Click ADD FEES to open the Add Fees lightbox.

  3. Set When to trigger a fee? to GIACT eCheck Verification.

  4. Add the required information.

  5. Click ADD.


Add Merchants to the Group

  1. Return to the Group Profile.

  2. Click ADD MEMBERS.

  3. Select the Merchant.

  4. Click SAVE.

See Fee Management to learn more about fee setup and management.

Now that you’ve set up the GIACT eCheck Verification Fee, you can begin running policy checks on transactions. This will allow you to apply automated risk decisions based on eCheck verification responses.


Reviewing GIACT Check Alerts for Merchants

API Request - Policy Run Summary

As a Payrix partner, you can use the following endpoint to run a GIACT policy check on a specific transaction or a set of transactions. When an eCheck transaction fails (status = 2), you need to verify if the transaction was blocked by the GIACT rule. If it was, you should display the Adverse Action Notice (AAN).

API Details

Base URL

  • Production: https://apiv2.payrix.com/risk/v2

  • Sandbox: https://apiv2.stage.payrix.com/risk/v2

See the Policy Run Summary Sandbox Testing section for more information.

Endpoint

/decision/policy-run-summary

HTTP Method

GET

Full HTTP Request

https://apiv2.payrix.com/risk/v2/decision/policy-run-summary?stage=auth&transactionId={txn-id}

Required Headers

Header

Valid Values

Notes

Content-Type

application/json

This needs to be a JSON content type.

Authorization

{yourAPIKey}

This can be found on the Portal Settings page in Sandbox or Production.

legacy-auth-header-name

APIKEY

Deprecated field, but still required to be sent in the headers.

Query Parameter

Parameter

Type

Required

Notes

{txn-id}

string

Yes

  • Replace {txn-id} with the transaction ID to verify if GIACT was called and its response.

  • Valid values are transactions that have taken place on the platform and follow the alphanumeric string format.

    • Example: t1_txn_12a3bc4de56f789012gh3ij

The transaction ID entered here will also appear in the subject field of your API call response within the results object.

Policy Run Summary Response Parameters

The expandable content below gives more in-depth information about the specific parameters available and required in the response body:

Click here to see details about all Response Body Parameters and applicable valid values.

Parameter

Description

Valid Values

uuid

The Universally Unique Identifier (UUID) of the transaction being reviewed

policyUuid

The UUID of the GIACT Policy

subject

The transaction ID of the transaction in question

action

The result of running the Policy

results

GIACT Inquiry results information

decisionType

Displays the type of the decision, in this case always GiactInquiry

result

The result of the final GIACT Inquiry decision

BLOCK
PASS
SKIP

Warning: If BLOCK is the value, you are required to display an Adverse Action Notice (shown below).

resultSummary

In case of failure, this will contain the error summary.

Policy Run Summary Response Body Example

Click here to see a sample code snippet of a response.
JSON
{
    "uuid": "XXX7c-038a-4881-af7d-7c029e022bbd",
    "policyUuid": "XXX90c-6b40-40fe-90e7-406da5d70852",
    "subject": " {txn-id} ",
    "action": "BLOCK",
    "results": [
        {
            "decisionType": "GiactTxnInquiry",
            "result": "BLOCK"
        }     
    ] 
}

GIACT Alerts in the Portal

The GIACT Check alerts will be shown in the Alerts section of the Merchant Profile page of the Merchant performing the transaction.

Note: Only Facilitators can view the GIACT Code field on this page. Referrers and Merchants are unable to view the specific GIACT Check block code. Additionally, Payrix is not permitted to disclose the nature or reason for a GIACT response to Merchants or Referrers.

The following table lists the possible GIACT Inquiry Check response messages and the descriptions.

Message

Description

SKIP

The data submitted did not meet the initial requirements to begin a GIACT review.

BLOCK

The transaction data was reviewed with GIACT and has been declined with an assessed fee.

If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice Requirement Message (shown below) should be displayed.

PASS

The transaction data was reviewed with GIACT and approved with an assessed fee.

Learn more about this declined transaction-

  1. Check if you have entered the correct bank account and routing details.

  2. Check if your bank account is in good standing.

  3. If the details are correct and are in good standing, This notice is intended to comply with the requirements of the federal Fair Credit Reporting (FCRA). We are unable to process your request because we were unable to verify or authenticate your account information. Our decision was based in whole, or in part, on information obtained from a consumer reporting agency, GIACT Systems, LLC. However, GIACT Systems, LLC played no part in the decision process and is unable to supply specific reasons for the denial of services. Under the FCRA, you have a right to know the information contained within your report. You also have a right to make a written request, no later than 60 days after you receive this notice, for disclosure of this information. You may request a free consumer report from GIACT Systems, LLC no later than 60 days following the receipt of this notice. You may also dispute information contained in the report if you believe that it is inaccurate or incomplete. GIACT Systems, LLC’s contact information is provided below: GIACT Systems, LLC 700 Central Expy S. Suite 300 Allen, TX 75013 1 (833) 802-8092”


GIACT Microservice Implementation Example

This example illustrates a front-end service operating on localhost:3000, paired with a back-end service on localhost:5000. Together, they exemplify the microservice architecture essential for securely handling any HTTP calls that involve sensitive keys. This configuration is specifically designed to safeguard private API keys needed for these requests, thereby reducing the risk of exposure.

Front-End Service

When using PayFields, you have access to the callbacks mentioned in the following table. In the case of a response within the PayFields.onFailure callback, you must determine whether it constitutes a GIACT error.

Available PayFields Callbacks

Action

Description

PayFields.onSuccess = (response) => {}

Runs when the API responds with a successful transaction or token

PayFields.onValidationFailure = () => {}

Runs when invalid or incomplete cardholder or payment data is entered

PayFields.onFailure = (response) => {}

Runs when API Key, Transaction Session Key, or Merchant ID fails validation before creating the API call or when the API responds with a failed transaction or token

PayFields.onFinish = (response) => {}

Runs when the API responds

PayFields.onRestore = () => {}

Runs when PayFields.restore() is run

PayFields.onUnmount = () => {}

Runs when PayFields.unmountAll() is run

GIACT Function

In this example, the GIACT function requires a transaction ID as a parameter and initiates a GET request to the back-end server http://localhost:5000/giact-data/{txnId}, which is wrapped in a returned promise. This allows waiting for a response from the back-end server before proceeding to display the appropriate error message.

JS
function GIACT(txnId) {
    return new Promise((resolve, reject) => {
      try {
        fetch(`http://localhost:5000/giact-data/${txnId}`)
          .then((response) => response.json())
          .then((data) => {
            resolve(data.action);
          });
      } catch (error) {
        console.log("Failed to call GIACT verification service");
        reject(error);
      }
    });
  }


onFailure Callback

Within the definition of the PayFields.onFailure callback, you can call the function above if PayFields.config.txnType = “ecsale” to initiate an additional required GET request that the back-end service executes.

JS
window.PayFields.onFailure = (response) => {
  let transactionId = response.data[0]
    ? response.data[0].id
    : console.log("no transaction Id found");

  if(window.PayFields.config.txnType = "ecsale") {
    GIACT(transactionId).then((res) =>
      res == "BLOCK"
        ? alert(
            "**ADVERSE ACTION NOTICE** \n\n 1) Check if you have entered correct bank account and routing details.\n\n 2) Check if your bank account is in good standing. \n\n 3) If the details are correct and is in good standing, This notice is intended to comply with the requirements of the federal Fair Credit Reporting (FCRA). We are unable to process your request because we were unable to verify or authenticate your account information. Our decision was based in whole, or in part, on information obtained from a consumer reporting agency, Giact Systems, LLC. However, Giact Systems, LLC played no part in the decision process and is unable to supply specific reasons for the denial of services. Under the FCRA, you have a right to know the information contained within your report. You also have a right to make a written request, no later than 60-days after you receive this notice, for disclosure of this information. You may request a free consumer report from Giact Systems, LLC no later than 60-days following the receipt of this notice. You may also dispute information contained in the report if you believe that it is inaccurate or incomplete. Giact Systems, LLC’s contact information is provided below: GIACT Systems, LLC 700 Central Expy S. Suite 300 Allen, TX 75013 1 (833) 802-8092."
          )
        : alert("giact error response")
    );
  }
  //Non GIACT error
  console.log(response);
};

In the response received from calling the GIACT function (example below), you can determine the cause of the failure. If the response from the call is BLOCK, at that point you need to display an Adverse Action Notice to the user.

Example GIACT response
CODE
{
  uuid: 'f739460d-64ae-4d46-80a6-721329b52c29',
  policyUuid: '2e33033f-0300-496c-8e6c-1a7b659bcfeb',
  policyName: 'Giact',
  subject: 't1_txn_678aa1f9c3e579b88ffb3ad',
  action: 'BLOCK',
  riskLevel: null,
  startedAt: 1737138683,
  results:
    [ 
      { 
      decisionType: 'GiactTxnInquiry', 
      result: 'BLOCK' 
      } 
    ]
}

*The GIACT function returns only the action attribute off of the example response.

GIACT Response Status

Message

Description

SKIP

The data submitted did not meet the initial requirements to begin a GIACT review.

BLOCK

The transaction data was reviewed with GIACT and has been declined with an assessed fee.

If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice Requirement Message (shown below) will be displayed.

PASS

The transaction data was reviewed with GIACT and approved with an assessed fee.

Back-End Service

To make a request to the GIACT endpoint, a private API key is required. Therefore, to ensure the API key’s security, the GIACT HTTP call is stored in a separate back-end service, preventing the key from being exposed in public client-side network request.

The below example of a server-side request takes a transaction ID as a request parameter to use for the GIACT call. This ID is passed through req.params, which is captured in a variable called txnId. In the front-end service, this ID is passed within the GIACT function. This transaction ID is required to call the GIACT endpoint.

The second portion of this example is the sensitive part. On line 10, we make a request to the GIACT endpoint, which requires the following:

GIACT Endpoint Requirements

Required Header

Valid Values

Notes

Content-Type

application/json

None

Authorization

{privateAPIKey}

This can be found on the Portal Settings page.

legacy-auth-header-name

APIKEY

Deprecated field; APIKEY is the valid value.

We then return the entire response in a new variable named result_data, as illustrated in the example GIACT response above. This approach effectively separates the GIACT call from any metadata associated with the network request, allowing us to send only the response JSON payload back to the front-end service.

JS
app.get('/giact-data/:txnId', async (req, res) => {
  let txnId = req.params.txnId
  let result_data

  let sandbox_base_url = "https://apiv2.stage.payrix.com/risk/v2"
  let production_base_url = "https://apiv2.payrix.com/risk/v2"

  console.log(txnId);
  let giact_url = `${sandbox_base_url}/decision/policy-run-summary?stage=auth&transactionId=${txnId}`
  await fetch(giact_url, {
    headers: {
      "Content-Type": "application/json",
      "Authorization": config.private_api_key,
      "legacy-auth-header-name": "APIKEY" 
    }
  })
  .then(res => res.json())
  .then(data => {
    result_data = data
  })
  .catch(err => console.log(err))
  console.log(result_data);
  res.json(result_data)
})

Full Example (How to run locally)

This example serves to illustrate a proper method for making an HTTP call while ensuring that the private API key remains secure and undisclosed.

giact_example.zip

Front End

Requirements
  • Public API key
  • Merchant ID

Open the project in VS Code and do the following:

  1. Find a file named config.json in /src to insert the requirements.

  2. Within a terminal, change the directory to giact_example/front-end.

  3. Run npm install.

  4. Run npm start to serve the react app on port 3000.

Back End

Requirements
  • Private API key

Open the project in VS Code and do the following:

  1. Find a file named config.json to insert the requirements.

  2. Within a terminal, change the directory to giact_example/giact-service.

  3. Run npm install.

  4. Run npm start to run the express server on port 5000.


Policy Run Summary Sandbox Testing

Creating a test transaction to execute a Policy Run Summary is done in two parts:

  1. Create a new transaction using testing trigger payment method values.

Process a POST request using the /txns endpoint, with the following values in the payment object within:

Click here for the /txns endpoint information

Base URL

https://api-test.payrix.com/

Endpoint

/txns

HTTP Method

POST

Full HTTP Request

https://api-test.payrix.com/txns

Required Header

Valid Values

Notes

Content-Type

application/json

None

Authorization

{yourAPIKey}

This can be found on the Portal Settings page.

Click here for available transaction payment object sandbox testing triggers.

To receive a BLOCK action response from the GIACT eCheck Verification:

JSON
"payment": {
    "method": 9,
    "number": "0000000004",
    "routing": "122105278"
  }

To receive a HOLD action response from the GIACT eCheck Verification:

JSON
"payment": {
    "method": 9,
    "number": "0000000009",
    "routing": "122105278"
  }

To receive a RESERVE action response from the GIACT eCheck Verification:

JSON
"payment": {
    "method": 9,
    "number": "0000000001",
    "routing": "122105278"
  }

To receive a POST_REVIEW_ONLY action response from the GIACT eCheck Verification:

JSON
"payment": {
    "method": 9,
    "number": "0000000003",
    "routing": "122105278"
  }
  1. Use the returned id response value to execute the Policy Run Summary.

Click here for a copy of the endpoint information to test the Policy Run Summary

Base URL

https://apiv2.stage.payrix.com/risk/v2

Endpoint

/decision/policy-run-summary

HTTP Method

GET

Full HTTP Request

https://apiv2.stage.payrix.com/risk/v2/decision/policy-run-summary?stage=auth&transactionId={txn-id}

Query Parameter

Type

Required

Notes

{txn-id}

string

Required

The id value returned in the response body for part one above.

Example: t1_txn_12a3bc4de56f789012gh3ij

Required Header

Valid Values

Notes

Content-Type

application/json

None 

Authorization

{yourAPIKey}

This can be found on the Portal Settings page.

login

{yourLoginID}

User your login ID that begins with t1_log_.

legacy-auth-header-name

APIKEY

Deprecated field; APIKEY is the valid value.

Result: You successfully created a test GIACT action response to either block, hold, or reserve funds for a transaction, as well as allowing the transaction to process as normal, being marked for further review at a later time.

Example Response:

CODE
{
    "uuid": "XXX7c-038a-4881-af7d-7c029e022bbd",
    "policyUuid": "XXX90c-6b40-40fe-90e7-406da5d70852",
    "subject": "t1_txn_12a3bc4de56f789012gh3ij",
    "action": "BLOCK",
    "results": [
        {
            "decisionType": "GiactTxnInquiry",
            "result": "BLOCK"
        }     
    ] 
}

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.