SOAP Web Service

Overview

Purpose

The purpose of the GoToBilling (GTB) SOAP Web Service is to provide an easy set methods for sending and receiving information from GTB in the form of SOAP requests. This allows you have a readily available platform integrating many current applications with GTB.

Summary of GoToBilling SOAP Web Service

The GoToBilling SOAP Web Services main functions are to create and update customers records and accounts, search for future, pending and past transactions and to process transactions. This web service can be used to integrate any new or existing application with the GTB application.

The rest of this document will summarize the web service, it's methods, the complex types used, and examples of usage. A WSDL for the web service can be found at:

https://secure.gotobilling.com/gateway/services/1.4/soap.php?wsdl

Please see SOAP API Release Notes for a history of changes.

Version History

1.3 **DEPRECATED**

• Added getTransaction method

1.4

• Added CustomField support
• getCustomFields method now available.
• saveAccount - Invalid routing number now correctly throws error code: 107

Complex Types

This section defines the various complex types used in this web service. Some of these type are used for Input, Output or both.

MerchantAuth

The MerchantAuth complex type allows for the delivery of the client credentials to authorize service requests.

MerchantAuth Fields

CustomerInfo

Customers or Customer Records are the individual people or companies that are customers to the Business(MID) we are working with. Typical customer data is Name, Address, Phone number etc. There are two unique fields in GTB that help identify customers. More will be explained below but one is a unique internal ID created by GTB called customer_id and the other one is created externally by the business called customer_name. The customer_name created by the business allows them to use a unique value from their accounting or other customer service systems so they can tie their data to the data in GTB.

CustomerInfo Fields

AccountInfo

Accounts are one or more payment accounts(methods) a customer may have. For example, a customer may have 4 payment accounts. One that is a VISA card, another that is a MasterCard and 2 different bank accounts. Under normal situations a customer usually only has one Account but any one customer may have multiple Accounts they may be paying from for any given Business(MID).

AccountInfo Fields

TransactionInfo

There are several different types of transactions but there are two broad categories for Transactions. Pending transactions and History Transactions. Pending transactions are those that are scheduled to process on some day in the future. History transactions are ones that have already processed. Transactions can be ACH, credit card, Void, Refund, and a host of other types. All of them still fall into either a pending transaction or a History transaction. Also, transactions are tied to Customers, of course, but also tied to the Account as a single customer may have made several transactions using different credit card numbers and different checking accounts but they were all done by the same customer. Therefore, the web services dealing with Transactions you will see each Transaction holds information that may seem like Account information.

TransactionInfo Fields

TransactionSettle

TransactionSettle contains transactions that have processed and have either settled funds to the merchant, or have returned for some reason.

TransactionSettle Fields

CustomField

The CustomField complex type allows the attachment of custom field data to a transaction, provided the custom fields have been confirgured within the GotoBilling application.

CustomField Fields

Web Service Methods

getCustomFields

Description: Returns the current custom fields available.

Parameters:

Returns: CustomField[]

deleteAccount

Description: Deletes a payment account with the generated account ID.

Parameters:

Returns: String, representing the result of the method

Possible Exception Codes

• 103.1: Invalid Account ID.
• 132: Cannot delete this account, there are pending transaction associated with it

deleteTransaction

Description: Deletes a pending transaction given the transaction ID.

Parameters:

Returns: String, representing the result of the method.

Possible Exception Codes

• 110: Invalid Transaction ID

getAccounts

Description: Retrieve the Accounts for a specified customer

Parameters:

Returns: AccountInfo[], an array of AccountInfo, one for each account associated with the customer.

getAccountById

Description: Get Account information by GTB generated account ID.

Parameters:

Returns: CustomerInfo

Possible Exception Codes

• 103.1: Invalid Account ID

getBatchInfo

Description: Retrieve information about the current batch.

Parameters:

Returns: BatchInfo

getCustomerById

Description: Get Customer information by GTB generated customer ID.

Parameters:

Returns: CustomerInfo

Possible Exception Codes

• 102: Invalid Customer ID

getCustomers

Description: Gets a list of customers for a merchant.

Parameters:

Returns: CustomerInfo[]

getTransaction

(v1.3)

Returns the transaction resource for a given Transaction ID.

Parameters:

Returns: TransactionInfo

Example

$soapClient->getTransaction(array('login'=>'username','pin'=>'password'), 123456)

Possible Exception Codes

• 110: Invalid transaction ID#

getTransactions

(v1.3)

Returns array of transaction resources matching the specified search criteria.

Parameters:

Returns: TransactionInfo[]

Example

$soapClient->getTransactions(array('login'=>'username', 'pin'=>'password'), array('customer_id'=>123456, 'amount'=>1.00))

Possible Exception Codes

• 130: Invalid search criteria

getPendingTransactions

Description: Gets a list of pending transactions.

Parameters:

Returns: TransactionInfo[]

Possible Exception Codes

• 109: attribute out of order

getTransactionHistory

Description: Gets a historical list of transactions. Parameters:

Returns: TransactionInfo[]

Possible Exception Codes

• 109: attribute out of order

getTransactionReturns

Description: Get merchant transaction returns

Parameters:

Returns: TransactionInfo[]

Special Field Notes: The tran_code field that is returned with each transaction will contain the ReturnCode-ReturnDefinition, example R01-Insufficient Funds. Full List of Return Codes

Possible Exception Codes

• 109: attribute out of order

getTransactionSettlements

Description: Retrieve a list of all merchant settlements for the given date range. Settlements include any transactions that have settled to the merchants account as well as any returned transactions.

Parameters:

Returns: TransactionSettle[]

runBatch

Description: Process all transactions in the batch for the given type of batch run. Options are: ACH, CC, or ALL.

Parameters:

Returns: True on successful run, False otherwise.

Possible Exception Codes

• 122: insufficient privileges

saveAccount

Description: Adds or updates account information Parameters:

Returns: AccountInfo

Possible Exception Codes

• 103: Invalid Account ID.
• 102: Invalid Customer ID
• 105: Unknown Account Type
• 108: Invalid card expiration date
• 106: Invalid account number
• 129: Invalid card zip code

saveCustomer

Description: Adds or updates customer information

Parameters:

Returns: CustomerInfo

Possible Exception Codes

• 102: Invalid Customer ID
• 123: first_name attribute is required for contact display
• 124: last_name attribute is required for contact display
• 125: company attribute is required for company display
• 126: customer_name field is required
• 126.1: customer_name given is already in use by another customer

saveTransaction

Description: Adds or updates a pending transaction

Parameters:

Returns: TransactionInfo

Possible Exception Codes

• 102: Invalid customer ID
• 103: invalid account ID
• 110: Missing transaction ID
• 111: authorization type required for ACH transactions
• 112: A PO number is required for Corporate cards
• 113: sales tax type is required when submittin a tax amount
• 114: a ticket ID must be specified to submit a void transaction
• 115: occurrence type is a required field
• 116: invalid transaction date
• 117: Invalid transaction date. Date must be for the current date or the future, past dates are not allowe
• 118: transaction is locked, you cannot change a locked transaction
• 119: invalid transaction type
• 120: invalid record type
• 121: invalid amount
• 127: invalid occurrence number
• 131: invalid lock status given.
• 133: Velocity Limit has been exceeded.

Errors Codes

This is a list of returned error codes and descriptions of their meaning.

Usage Examples

Create a customer and return the GTB assigned Customer ID

<?php
$client = new SoapClient("https://secure.gotobilling.com/gateway/services/soap.php?wsdl");

// merchant auth, required fields
// MAKE SURE TO FILL THIS OUT
$login = '';
$pin = '';

$merchantAuth = array (
    'login' => $login,
    'pin' => $pin
);

// CustomerInfo Fields
$customer_name = 'New Company, Inc'; // string, unique identifier
$display_as = 'company';             // company' or 'contact'
$company = 'new Company';            // string(50), required if above='company'
$first_name = 'John';               // required if above='contact'
$last_name = 'Jones';               // required if above='contact'
$active = '1';                     // boolean, disabled=0, enabled=1
$address1 = '';

// make the array
$customerInfo = array(
'customer_name'=>$customer_name,
'display_as'=>$display_as,
'active'=>$active,
'company'=>$company,
'address1'=>$address1
);

// saveCustomer
// required: MerchantAuth, CustomerInfo
$result = $client->saveCustomer( $merchantAuth, $customerInfo );
print_r($result);
?>

Return Codes

Tran Status Codes

Tran Code Definitions