Introducing OpenACH, the world's first free, open-source, secure web-based ACH origination and payment processing platform... Payment processing made simple.

OpenACH API


One of the great benefits of using OpenACH is how easily it can be integrated with websites, e-commerce systems, invoicing systems, etc. The API can be used to create and maintain payment profiles, bank accounts, and payment schedules. Payment profiles can easily be linked to your customer records using an 'external id', making it very easy to find your customers later, even if you don't want to have to track the IDs that OpenACH creates for them. The basic flow through the API is as follows:

  1. Connect/Authenticate

  2. Load one or more records

  3. Optionally save one or more records

  4. Disconnect/Logout

API Client, Requests and Responses

The OpenACH API operates on a client/request/response model. First, a client is created which connects to a specific OpenACH host, authenticating with an auth-token and key. Once connected, a request is made of the server, and the server returns a response to the client.

Connect/Authenticate

A client is created to connect to the OpenACH host, using a pre-arranged auth-token and key. Each auth-token and key are configured to allow access to payment profiles, bank accounts and payment schedules belonging to a single origination account.

<?php
// Load the OpenACH SDK
require_once( 'OpenACHSdk.php' );

// Create a new client
$client = new OAClient();

// Connect to the server
$response = $client->connect(
       
'a546730e-6a09-11e1-83b4-f23c91dfda4e', // Auth token
       
'a5467336-6a09-11e1-83b4-f23c91dfda4e' // Auth key
   
);

// Alternatively, a connection can be made to a specific endpoint URL and port number
$response = $client->connect(
       
'a546730e-6a09-11e1-83b4-f23c91dfda4e', // Auth token
       
'a5467336-6a09-11e1-83b4-f23c91dfda4e', // Auth key
       
'https://your.openach.server/', // Endpoint URL
       
'443' // Port Number
   
);

// The response will tell us whether or not we were successful
if ( ! $response->success )
{
   
// If unsuccessful
   
echo $response->error;
    exit;
}
else
{
    echo
'Connected with a session id of ' . $response->session_id; // This is the PHPSESSID cookie
   
exit;
}
?>

Load One or More Records

After connecting, you can send one or more requests to load records. OpenACH API allows you to build requests to work with four distinct types of records: Payment Profiles, External Accounts (e.g. Bank Accounts), Payment Schedules, and Payment Types.

Payment Profiles

Each payment profile represents a customer, and includes first and last name, email address, password, security questions/answers and status. A payment profile can have multiple external accounts (e.g. bank accounts) and payment schedules.

External Accounts

External accounts are simply customer bank accounts. It may seem odd at first to refer to them as "external accounts" instead of "bank accounts", but understand that OpenACH deals with all sorts of different bank accounts. These particular bank accounts are external in the fact that they belong to people other than the originator, and more than likely reside at other banks than the originator's bank account(s). We chose not to rename them simply for the API in order to avoid confusion for developers who work with both internal and SDK aspects of OpenACH. When you are using the API, just remember that "external account" simply means "bank account".

Any given payment profile may have multiple external accounts, and a single external account may be associated with many payment schedules. External accounts are defined by bank name, bank country, routing/SWIFT number, account number, account holder name, account type, and a billing address (required only for international transactions).

Payment Schedules

At the heart of OpenACH are payment schedules. Each individual payment schedule is associated with a single external account which is used to process the payment(s). Payment schedules can be created as one-time payments, or recurring payments with intervals of daily, weekly, biweekly, monthly, bimonthly, biannually, annually, or biennially. Each payment schedule is assigned an amount, payment type, currency code, next date, frequency, an end date, and status. OpenACH automatically calculates the remaining occurrences for each payment schedule based on this information. Each payment schedule is linked to a payment type.

Payment Types

To process payments, each origination account in OpenACH is configured with one or more payment types which define the transaction as either a credit (depositing funds INTO an external account), or a debit (withdrawing funds FROM an external account). They can only be modified from within the OpenACH web interface and are available through the API simply for reference when setting up new payment schedules.

Using Requests to Load Records

The SDK uses several different classes of requests to load data from OpenACH. Most of these requests require that you provide it a record id to search on, or a specific record id to load.

Request class
Requires input field
Responds with
OAGetExternalAccountRequest external_account_id A single external account
OAGetExternalAccountsRequest payment_profile_id All external accounts for the payment profile
OAGetPaymentProfileRequest payment_profile_id A single payment profile
OAGetPaymentProfileByExtIdRequest payment_profile_external_id A single payment profile
OAGetPaymentScheduleRequest payment_schedule_id A single payment schedule
OAGetPaymentSchedulesRequest payment_profile_id All payment schedules for the payment profile
OAGetPaymentTypesRequest All payment types

After a client is created, a request is built and sent through the client.

<?php
// ... SDK already loaded, new client created, and connected to the server

// Create a new Payment Profile request

$paymentProfileReq = new OAGetPaymentProfileByExtIdRequest();

// Set the external id that we're looking for
$paymentProfileReq->payment_profile_external_id = '327';

// Use the client to send the request to OpenACH
$paymentProfile = $client->sendRequest( $paymentProfileReq );

// We can check the response status
if ( ! $paymentProfile->success )
{
    echo
$paymentProfile->error;
    exit
}

// Create a new external account request
$externalAccountsReq = new OAGetExternalAccountsRequest();

// Set the payment_profile_id to the profile we just loaded
$externalAccountsReq->payment_profile_id = $paymentProfile->payment_profile_id;

// Create a new payment schedules request (we will reuse this several times)
$paymentSchedulesReq = new OAGetPaymentSchedulesRequest();

$externalAccounts = $client->sendRequest( $externalAccountsReq );

// We could check for success, but a convenient feature of the response objects are that
// they implement array iterators, allowing us to spin through the results as if it were an array
// If there are no results or there was an error, the 'array' will simply be empty
foreach ( $externalAccounts as $externalAccount )
{
   
$paymentSchedulesReq->external_account_id = $externalAccount->external_account_id;
   
$paymentSchedules = $client->sendRequest( $paymentSchedulesReq );
    foreach (
$paymentSchedules as $paymentSchedule )
    {
       
// display the payment schedule info, or whatever else you would like to do with the data...
   
}
}
?>

Optionally save one or more records

After loading records, you may wish to update some information and save them, or even create new records from scratch. The SDK contains a set of request classes to facilitate saving records. In your workflow, you may create new records and/or update existing records. Regardless of which, the SDK provides a single save request that is capable of handling both situations. The only real difference is that when creating a new record, you will leave the record id blank so a new one can be assigned as it is created. When updating an existing record, the record id is provided so OpenACH knows what record to update.

Request class
Requires input fields
Responds with
OASaveExternalAccountRequest external_account_id*
external_account_type
external_account_name
external_account_bank
external_account_holder
external_account_country_code
external_account_dfi_id
external_account_number
external_account_billing_address
external_account_billing_city
external_account_billing_state_province
external_account_billing_postal_code
external_account_billing_country
external_account_business
A single external account
OASavePaymentProfileRequest payment_profile_id*
payment_profile_external_id
payment_profile_first_name
payment_profile_last_name
payment_profile_email_address
payment_profile_security_question_1
payment_profile_security_question_2
payment_profile_security_question_3
payment_profile_security_answer_1
payment_profile_security_answer_2
payment_profile_security_answer_3
A single payment profile
OASavePaymentScheduleRequest payment_schedule_id*
payment_schedule_external_account_id*
payment_schedule_payment_type_id*
payment_schedule_amount
payment_schedule_currency_code
payment_schedule_next_date
payment_schedule_frequency
payment_schedule_end_date
payment_schedule_remaining_occurrences
A single payment schedule

Disconnect/Logout

When your session is complete, you can disconnect/logout from the OpenACH session. Doing so will both remove your current session id and auth details from the client, as well as close your session on the server. If you plan on reusing the same session id across multiple requests on your website/webapp, you can store the session id and bypass the connect/authenticate step for subsequent connections. Note however that for security purposes, you should not persist the session id for long periods of time, as the authentication will allow you to better control security from within OpenACH.

<?php
// ... SDK already loaded, new client created, and connected to the server

// Option 1: Save the session Id for later and destroy the client without disconnecting

$sessionId = $client->sessionId;
$client = null;

// Create a new client reusing an existing session id
$client = new OAClient();
$client->sessionId = $sessionId;
// ... continue using the client as before

// Option 2: Disconnect from the session completely (if not reusing the session id)

$client->disconnect();
?>

Using OpenACH Endpoints Directly

The OpenACH SDK relies on a REST/JSON web service framework. As such, the web service endpoints can be accessed directly by any language capable of REST/JSON calls. This also allows developers to port the OpenACH SDK into the programming language of their choice. The endpoints are available on every OpenACH installation. In the list below, the host name should be replaced as necessary, depending on which OpenACH server you intend to access. Parameters can be passed as either GET or POST, though we recommend using POST for reasons of security (GET requests are often logged by web servers, whereas POST are not.)

Request
Requires input field(s)
Responds with
https://secure.openach.com/api/connect user_api_token, user_api_key success, (error), session_id
https://secure.openach.com/api/disconnect (none) success
https://secure.openach.com/api/getExternalAccount external_account_id (success, error) OR external_account object
https://secure.openach.com/api/getExternalAccounts payment_profile_id (success, error) OR Array of external_account objects
https://secure.openach.com/api/getPaymentProfile payment_profile_id (success, error) OR payment_profile object
https://secure.openach.com/api/getPaymentProfileByExtId payment_profile_external_id (success, error) OR payment_profile object
https://secure.openach.com/api/getPaymentSchedule payment_schedule_id (success, error) OR payment_schedule object
https://secure.openach.com/api/getPaymentSchedules payment_profile_id (success, error) OR Array of payment_schedule objects
https://secure.openach.com/api/getPaymentTypes (none) (success, error) OR Array of payment_type objects