Set Up GIACT eCheck Verification

GIACT's gVERIFY is a real-time account verification service that confirms bank account legitimacy for ACH (eCheck) transactions. It checks if the account is open, active, and in good standing before processing payments, reducing fraud risks, administrative returns, and chargebacks. This service is useful for partners looking to improve transaction success rates and optimize risk management.

Each verification attempt incurs a fee, regardless of whether the outcome is Pass, Block, or Skip. After verification, future transactions from the same account won't incur additional charges. If a transaction is blocked, an Adverse Action Notice must be given to the consumer as required by the Fair Credit Reporting Act (FCRA).

To get started processing eCheck Verifications for Merchant transactions, you must set up a GIACT eCheck Verification Fee for Merchants or Groups.

Apply a GIACT eCheck Verification Fee to a Group

GIACT eCheck Verification Fees are configured like any other fee on the Payrix Pro platform, from the Group Profile page or Merchant Profile page. The following steps can be used on the Group Profile page for Group configurations, or from the Merchant Profile page, for individual Merchant assignment in the Portal:

Select Groups from from the left navigation panel.
Select your desired Group from the list to open the Group Profile page.
Click the Fees tab on the Group Profile page to open the Fees menu.
Click ADD FEES in the Fees menu to open the Add Fees dialog.
For When to trigger a fee? select GIACT Echeck Verification.
Set How much is the fee?, Fee start date, Fee name, and Currency as needed.
Click Add to complete setting up the fee.

Result: The GIACT eCheck Verification Fee now applies to all Merchants in the Group. When a GIACT Verification fee is assessed to your account, it will automatically assess a fee to the Merchant that triggered the verification to cover the verification service costs. With the GIACT eCheck Verification Fee set up, you can now run policy checks on transactions, allowing automated risk decisions based on eCheck verification responses.

Notes
For guidance on setting up Groups and adding Merchants, see Understanding Groups.
For details on setting up Fees, see Fee Type Configuration Parameters.

Review GIACT Inquiry Alerts for Merchants

As a Payrix Pro 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). See the Policy Run Summary Sandbox Testing section for more information.

Request Example

In the following request, the Payrix Pro transaction ID is sent as a required query parameter to verify if GIACT was called and its response:

GET /decision/policy-run-summary?stage=auth&transactionId={txn-id} HTTP/1.1
Host: apiv2.stage.payrix.com/risk/v2
Content-Type: application/json
APIKEY: {apiKey} 
legacy-auth-header-name: APIKEY

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

Response Body Example

The following is a sample code snippet of a response:

{
    "uuid": "1ab2c-45f6-7890-12gh-ij3k45l67m8n",
    "policyUuid": "ab2cde-45f6-7890-12gh-ij3k45l67m8n"
    "subject": "t1_txn_123abc4d567890efg1h2i34",
    "action": "BLOCK",
    "results": [
        {
            "decisionType": "GiactTxnInquiry",
            "result": "BLOCK"
        }     
    ] 
}

Parameter		Description	Notes and Valid Values
`uuid`		The Universally Unique Identifier (UUID) of the transaction being reviewed	N/A
`policyUuid`		The UUID of the GIACT Policy	N/A
`subject`		The transaction ID of the transaction in question	N/A
`action`		The result of running the Policy	N/A
`results`		GIACT Inquiry results information	N/A
	`decisionType`	Displays the type of the decision, in this case always `GiactInquiry`	N/A
	`result`	The result of the final GIACT Inquiry decision	Valid Values: `BLOCK` `PASS` `SKIP` Note: If `BLOCK` is the value, the Adverse Action Notice must be displayed.
	`resultSummary`	In case of failure, this will contain the error summary.

Review GIACT Inquiry Alerts in the Portal

GIACT Inquiry alerts are shown in the Alerts menu of the Merchant Profile page of the Merchant performing the transaction.

Alert log showing a GiacInquiry with a status of PASS on August 16, 2022.

Note
Partners and Merchants cannot see the GIACT Inquiry Check Code value. Additionally, Worldpay for Platforms is not permitted to disclose the nature or reason for a GIACT response to Merchants or Partners. All GIACT Inquiry Check codes are sent directly from the bank issuers. Account holders must contact their bank for more information on any hold or decline responses sent to the Payrix Pro platform.

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. Note: If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice must be displayed.
PASS	The transaction data was reviewed with GIACT and approved with an assessed fee.

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.

Note: If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice must be displayed.

PASS

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

Adverse Action Notice Message

For GIACT Inquiry Check BLOCK responses, the following Adverse Action Notice must be displayed to the customer:

Adverse Action Notice
Learn more about this declined transaction-
Check if you have entered the correct bank account and routing details.
Check if your bank account is in good standing.
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.

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.

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.

The following is an example of a GIACT response:

{
  "uuid": "1ab2c-45f6-7890-12gh-ij3k45l67m8n",
  "policyUuid": "ab2cde-45f6-7890-12gh-ij3k45l67m8n"
  "policyName": "Giact",
  "subject": "t1_txn_123abc4d567890efg1h2i34",
  "action": "BLOCK",
  "riskLevel": null,
  "startedAt": "1737138683",
  "results":
    [ 
      { 
      "decisionType": "GiactTxnInquiry", 
      "result": "BLOCK" 
      } 
    ]
}

{

Note
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. Note: If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice must be displayed.
PASS	The transaction data was reviewed with GIACT and approved with an assessed fee.

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.

Note: If a BLOCK is issued from a GIACT Inquiry Check, the Adverse Action Notice must 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.

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)
})

Locally Run Example

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

giact-example

222.92 KB

Front End Requirements

Back End Requirements

Requirements:

Public API key
Merchant ID

Open the project in VS Code and do the following:

Find a file named config.json in /src to insert the requirements.
Within a terminal, change the directory to giact_example/front-end.
Run npm install.
Run npm start to serve the react app on port 3000.

Requirements:

Private API key

Open the project in VS Code and do the following:

Find a file named config.json to insert the requirements.
Within a terminal, change the directory to giact_example/giact-service.
Run npm install.
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:

Create a POST /txns request:

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

Build the request body using the a simulator trigger values in the payment object:

{
  "merchant": "t1_mer_123abc4d567890efg1h2i34",
  "type": "7",
  "origin": "2",
  "payment": {
      "method": "8",
      "number": "123456789",
      "routing": "122105278"
  },
  "total": "10000",
  "first": "Joe",
  "last": "Smith"
}

GIACT Simulator Triggers

GIACT Action Simulator Response	`method` Value	`routing` Value
BLOCK	8	122105278
HOLD	9	122105278
RESERVE	10	122105278
POST_REVIEW_ONLY	11	122105278

Submit the request. A successful 200 OK response contains details about the transaction:

{
  "response": {
    "data": [
      {
        "id": "t1_txn_123abc4d567890efg1h2i34",
        "created": "2025-06-06 18:13:13.9376",
        "modified": "2025-06-06 18:13:16.3387",
        "creator": "t1_log_123abc4d567890efg1h2i34",
        "modifier": "000000000000001",
        "ipCreated": "0.0.0.0",
        "ipModified": "0.0.0.0",
        "merchant": "t1_mer_123abc4d567890efg1h2i34",
        "token": null,
        "payment": {
          "id": "g123456abc7de8f",
          "method": 8,
          "number": "6789",
          "routing": "5278",
          "bin": null,
          "payment": null,
          "lastChecked": null,
          "last4": null,
          "mask": null,
          "plaidConsumerAccount": null
        },
        "fortxn": null,
        "fromtxn": null,
        "batch": "t1_bth_123abc4d567890efg1h2i34",
        "subscription": null,
        "type": 1,
        "expiration": null,
        "currency": "USD",
        "platform": "VCORE",
        "authDate": null,
        "authCode": null,
        "captured": null,
        "settled": null,
        "settledCurrency": null,
        "settledTotal": null,
        "allowPartial": 0,
        "order": "",
        "description": null,
        "descriptor": null,
        "terminal": null,
        "terminalCapability": null,
        "entryMode": null,
        "origin": 2,
        "tax": null,
        "total": 10000,
        "cashback": null,
        "authorization": "12345",
        "approved": 1000,
        "cvv": 1,
        "swiped": 0,
        "emv": 0,
        "signature": 0,
        "unattended": null,
        "clientIp": null,
        "first": null,
        "middle": null,
        "last": null,
        "company": null,
        "email": null,
        "address1": null,
        "address2": null,
        "city": null,
        "state": null,
        "zip": null,
        "country": null,
        "phone": null,
        "mid": "12345678",
        "status": 1,
        "refunded": 0,
        "reserved": 0,
        "misused": null,
        "checkStage": "capture",
        "imported": 0,
        "inactive": 0,
        "frozen": 0,
        "discount": 0,
        "shipping": 0,
        "duty": 0,
        "pin": 0,
        "traceNumber": null,
        "cvvStatus": null,
        "unauthReason": null,
        "fee": null,
        "fundingCurrency": "USD",
        "authentication": null,
        "authenticationId": null,
        "cofType": null,
        "copyReason": null,
        "originalApproved": 10000,
        "currencyConversion": null,
        "serviceCode": null,
        "authTokenCustomer": null,
        "debtRepayment": 0,
        "statement": null,
        "convenienceFee": 0,
        "surcharge": null,
        "channel": null,
        "funded": null,
        "fundingEnabled": 1,
        "requestSequence": 1,
        "processedSequence": 0,
        "mobile": null,
        "pinEntryCapability": null,
        "fbo": "WORLDPAY_FBO1",
        "returned": null,
        "txnsession": null,
        "networkTokenIndicator": 0,
        "softPosDeviceTypeIndicator": null,
        "softPosId": null,
        "tip": null,
        "pinlessDebitConversion": null
      }
    ],
    "details": {
      "requestId": 1
    },
    "errors": []
  }
}

Build a query to test the Policy Run Summary using the returned transaction id value from the previous step:

GET /decision/policy-run-summary?stage=auth&transactionId={transactionID} HTTP/1.1
Host: apiv2.stage.payrix.com/risk/v2
Content-Type: application/json
APIKEY: {apiKey} 
legacy-auth-header-name: APIKEY

Submit the request. A successful 200 OK response contains GIACT action response details about the transaction:

{
    "uuid": "1ab2c-45f6-7890-12gh-ij3k45l67m8n",
    "policyUuid": "ab2cde-45f6-7890-12gh-ij3k45l67m8n"
    "subject": "t1_txn_12a3bc4de56f789012gh3ij",
    "action": "BLOCK",
    "results": [
        {
            "decisionType": "GiactTxnInquiry",
            "result": "BLOCK"
        }     
    ] 
}