Developer Integration Guide

Introduction

Welcome to the Green API Documentation for integrating ValidiFi's bank login into your business solution! Our APIs lay the foundation for securely and seamlessly connecting with users' bank accounts. Dive into our documentation to unlock powerful tools designed to streamline user authentication, facilitate easy access to financial data, and enhance your application's functionality. With our comprehensive guides and robust API suite, integrating ValidiFi's bank login capabilities into your platform will provide users with a frictionless banking experience.

Customers

The Customers endpoint streamlines the checkout process by allowing you to securely store customer information. Each customer can be assigned a username and password, which are encrypted and securely stored in our system for swift account retrieval. Additionally, this endpoint offers diverse debit creation methods tailored to your specific processing requirements. In Green, customers are uniquely identified by the Payor_ID field.

Getting Started

We leverage the SOAP (Simple Object Access Protocol) API protocol to ensure seamless communication among systems and secure data exchange. SOAP employs XML-based messaging for data transmission across various transport protocols, enhancing interoperability among systems and programming languages. A SOAP message includes an envelope that outlines the message's structure, headers, and a body containing the actual data. This approach allows developers to create robust, standardized web services that support integration across diverse platforms and technologies while maintaining strict security measures.

Authentication

Our endpoints require authentication using a client ID and password. Every endpoint requires the Client_ID and ApiPassword parameters. To retrieve your API credentials, log into your merchant account.

To access your account settings, please navigate to the "Account" section in the navigation menu, as illustrated in the accompanying image. Within the account settings, you will find two types of credentials: Live Credentials and Test Credentials. Live Credentials are used for making actual API requests, while Test Credentials are designed to simulate API requests for testing purposes. To acquire Live Credentials, simply add a key to the Live Credentials section. Upon successful addition, you will be notified both on the page and via email, the latter containing your API credentials. Be sure to record your Merchant ID (MID), which can be found at the top-left corner of the page, along with your API password.

If you encounter any difficulty finding the API settings on your screen, please don't hesitate to contact our support team for assistance.

GreenPay™ Integration

This section outlines the steps required to seamlessly integrate the GreenPay™ bank login feature into your platform.

Integration Workflow

For Existing Customers:

If you already have the customer's Payor_ID, initiate an API call using the GetCustomerInformation endpoint to access the customer's bank account information, if they have previously registered one. For implementing a customer login system to retrieve the Payor_ID, you will need to save a username and password to your customer either using CreateCustomerWithLogin to create the customer with username and password or EditCustomerLogin to apply a username and password to an existing customer, and then authenticate these credentials using the CustomerAuth endpoint. We recommend displaying the RoutingNumber and AccountNumber returned from GetCustomerInformation, which are already obfuscated for security purposes, in order for your customer to confirm the bank account being used for the transaction.

The GetCustomerInformation endpoint provides access to the customer's bank account information if they have previously registered one. In cases where the customer doesn't have a bank account on file, incorporate the provided iframe link along with the supporting code snippet provided from the Client Side Integration section. Upon confirming the customer's bank account registration, proceed to call one of the following endpoints to finalize the transaction: CustomerOneTimeDraftBV, CustomerOneTimeDraftRTV, CustomerRecurringDraftBV, or CustomerRecurringDraftRTV

For New Customers:

To create a new customer, initiate an API call using the CreateCustomer or CreateCustomerWithLogin endpoint depending on whether you're implementing a login system. For implementing a customer login system to retrieve the Payor_ID, you will need to save a username and password to your customer using CreateCustomerWithLogin to create the customer with username and password, and then authenticate these credentials using the CustomerAuth endpoint.

Upon successful customer creation, you will receive a Payor_ID. Store this value as the subsequent API calls rely on the Payor_ID. Include the provided iframe link from the Client Side Integration section along with the supporting code snippet. After confirming the customer's bank account registration, we recommend displaying the RoutingNumber and AccountNumber returned from GetCustomerInformation, which are already obfuscated for security purposes, in order for your customer to confirm the bank account being used for the transaction. Proceed to call one of the following endpoints to complete the transaction: CustomerOneTimeDraftBV, CustomerOneTimeDraftRTV, CustomerRecurringDraftBV, or CustomerRecurringDraftRTV.

Client Side Integration

The ValidiFi integration is delivered to your page through an iframe link, ensuring a smooth integration process with your site's existing layout and functionality. Replace placeholders with your MID for the client_id parameter and the Payor_ID for the customer_id parameter.

The final step is to insert the following code snippet and implementing the necessary logic to intercept events triggered by the integration. The following code snippet listens for the iframe events so that you can code the succeeding logic after each event.

Customers

The following SOAP calls can be used to interact with Customers.

• GetCustomerInformation
• CreateCustomer
• CreateCustomerWithLogin
• EditCustomerLogin
• CustomerAuth
• CustomerOneTimeDraftRTV
• CustomerOneTimeDraftBV
• CustomerRecurringDraftRTV
• CustomerRecurringDraftBV

GetCustomerInformation

This function retrieves a single customer record identified by the Payor_ID.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CreateCustomer

Store a customer's information in our system as part of your Customer List.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CreateCustomerWithLogin

Store a customer's information in our system as part of your Customer List, also with a username and password.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CustomerAuth

Authenticate the Customer List Entry's Username and Password.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

EditCustomerLogin

Edit a Customer list entry's password.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CustomerOneTimeDraftRTV

Run a single draft from a customer into your merchant account using Real-Time Verification.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CustomerOneTimeDraftBV

Run a single draft from a customer into your merchant account using delayed Batch Verification.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript

CustomerRecurringDraftRTV

Start a recurring draft series from a customer into your merchant account using Real-Time Verification.

Request

XML Request

XML Request

Code Example - cURL

Code Example - Javascript

CustomerRecurringDraftBV

Start a recurring draft series from a customer into your merchant account using delayed Batch Verification.

Request

XML Request

XML Response

Code Example - cURL

Code Example - Javascript