Table of Contents
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.
...
Please see SOAP API Release Notes for a history of changes.
Version History
1.3 **DEPRECATED**
- Added getTransaction method
...
This section defines the various complex types used in this web service. Some of these type are used for Input, Output or both.
CustomerInfo
...
MerchantAuth
The MerchantAuth complex type allows for the delivery of the client credentials to authorize service requests.
MerchantAuth Fields
Field Name | Optional (O); Conditional (C); | Data Type & Length | Description & Field Values |
---|---|---|---|
| |||
| |||
access_token | O | string | Valid OAuth access token. |
access_key | O or C | string | Provide API access key pair parameters in lieu of standard MerchantAuth fields - CONDITIONALLY REQUIRED: if access_key parameter is supplied, access_secret parameter must also be supplied. For more information on obtaining an API access key, see: Managing API Access Keys |
access_secret | O or C | string | Provide API access key pair parameters in lieu of standard MerchantAuth fields - CONDITIONALLY REQUIRED: if access_key parameter is supplied, access_secret parameter must also be supplied. For more information on obtaining an API access key, see: Managing API Access Keys |
source_description | O | string | Description of the source originating the request. |
module_description | O | string | Description of the module originating the request. |
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
Field Name | Required (R); Optional (O); Conditional (C); Read Only (RO) | Data Type & Length | Description & Field Values |
---|---|---|---|
customer_id | C | String (50) | A unique customer identifier set by GTB. |
first_name | C | String (50) | Required if display_as='contact' |
last_name | C | String (50) | Required if display_as='contact' |
customer_name | R | String (100) | Externally defined unique field for each Customer. This is a free-form identifier that is created by the user to allow matching of customers by existing customer numbers in accounting or other customer databases and systems. This field MUST be unique in order for many other functions and features the customer may use. |
display_as | R | String (50) | Values: 'company' or 'contact'. Defaults to contact if not recognized. |
company | C | String (50) | Required if display_as='company' |
address1 | O | String (100) | |
address2 | O | String (50) | |
city | O | String (50) | |
state | O | String (2) | |
zip | O | String (20) | |
phone | O | String (50) | |
O | String (100) | ||
ssn | O | String (50) | |
dl_number | O | String (20) | |
dl_state | O | String (2) | |
notes | O | String | |
active | R | Boolean | Determines whether a customer record is Active or Inactive. Inactive customers show as grayed out within the GTB application
|
hidden | O | Boolean | Determines whether customer record is visible or not within the main GTB app. It’s the status field that is used when a customer record is deleted but in reality the we don’t delete the customer from the database, we just make it invisible to the user.
|
date_added | RO | String | The date the customer was originally added to GTB. YYYYMMDD format |
...
AccountInfo Fields
Field Name | Required Optional Conditional (R); Optional (O); Conditional (C); Read Only (RO) | Data Type & Length | Description & Field Values |
---|---|---|---|
account_id | C | Int | A unique identifier assigned by GTB for every Account that is added to the system. |
customer_id | R | Int | Unique ID of the customer the account is being assigned to. |
account_name | O | String (100) | This field allows a consumer to name their checking or credit card account to anything they want as an identifier for their account. |
account_number | C | String (100) For credit cards it is the 16 digit card number and for Checking Accounts it is the routing and account number including all leading zeros. | |
routing_number | C | String(9) | ABA Routing number for bank account. |
enabled | O | Boolean | Defines whether this Account is enabled for adding transactions or not. If it is disabled, then no transactions can be done using this account within GTB.
|
type | R | Int | Defines the account type, i.e. credit card or ACH
|
bank_name | C | String (50) | If account type is ACH, indicates the name of the banking institution |
cc_name | C | String (100) | Actual Name of the customer as it appears on their credit card. |
expiration | C | String | Card expiration date. In the format: MMYY |
cvv | C | String (4) | The 3 or 4 digit card security value on the card. When retrieving information about an account the CVV value will always be masked for security reasons. |
cc_zip | C | String (5) | The 5 digit billing zip code associated with the card. |
is_savings | C | Boolean | Tells you if the Checking Account is a Savings account or not.
|
date_added | RO | String | Format: YYYYMMDD |
date_modified | RO | String | Format:YYYYMMDD |
...
Field Name | Required (R); Optional (O); Conditional (C); Read Only (RO) | Data Type & Length | Description & Field Values |
---|---|---|---|
tran_id | C | Int | Unique number that is assigned by GTB for every transaction entered into the system. If trans_id exists in GTB then that record is updated; otherwise, a new record is created. If a tran_id is provided that doesn't exist then you get an error message. |
customer_id | R | Int | GTB generated customer ID, returned in CustomerInfo |
account_id | R | Int | GTB generated account ID for the payment account, returned in AccountInfo |
tran_type | R | Int | Determines type of transaction, i.e. ACH or credit card
(*) ARC must be MICR read and image of check stored. All of these transaction types have special ACH rules and should not be coded to without help from GTB. |
record_type | R | Int | Description: Determines whether transaction activity
|
auth_type | C | Int | Indicates method of ACH transaction authorization. These are ONLY used on ACH transactions. Before implementing any ACH transactions please consult GTB for compliance and NACHA regulations. Auth_type is normally 1, 2 or 3 under most circumstances. Values:
(*) Consult with GTB for extra compliance issues and NACHA regulations. |
occurrence | O | String | Indicates presence of any recurring transaction activity. Applicable to both CC and ACH transactions.
|
occurrence_number | C | Int | Determines the number of times that a particular transaction is to be recurred. Any integer value represents the number of occurrences left for this particular transaction. If not provided and occurrence type is not single, transaction will repeat indefinitely. |
amount | R | Float | The amount of the transaction. |
check_number | C | String (50) | |
tran_date | C | String (50) | The date the transaction is scheduled to process. Format is YYYYMMDD |
notes | O | String | |
memo | O | String | |
is_corporate | O | Boolean | |
po_number | C | String (50) | Required if is_corporate is TRUE |
sales_tax | C | Float | |
sales_tax_type | C | Int | Required if sales_tax is provided |
order_id | O | String (50) | Unique transaction ID field specified by the merchant. Also used in determining duplicate submissions. |
ticket_id | C | String (50) | Only Credit card transactions receive Ticket ID. This Ticket ID is required when submitting a VOID transaction. |
customer_int | O | Boolean |
|
process | O | Boolean | Set to true to immediately process a CC transaction for the current date, and approvals are not neededsent with today as the transaction date. If not set to true, transactions will be placed into batch for later processing. Transactions will not process immediately if management approval is required. Future-dated transactions will be placed in batch for the date given. |
account | RO | String | Masked account number associated with a transaction |
account_type | RO | String | Type of account for the transaction |
account_expiration | RO | String | Expiration date of a credit card account |
tran_code | RO | String | Not in a Post, only in a Get as it is the descriptive reason message on credit card transactions. Things like Decline reasons of invalid exp date, etc. They can exist even on Approvals. |
tran_status | RO | String | Status of a Transaction |
invoice_id | RO | String | GTB created. If someone pays an invoice that is generated out of GTB, the invoice number is entered into this field to tie the transaction to the invoice number. |
date_created | RO | String | |
approvals_needed | RO | Int | Is the number of people that need to approve the transaction before it can process. |
auth_code | RO | String | Authorization code for a credit card transaction |
avs_code | RO | String | Credit card transaction response foraddress verification. |
cvv2_code | RO | String | Credit card transaction response for the CVV security code supplied. |
reference_id | RO | String | The Reference ID is an internally generated number. It will be the order_id if supplied by the merchant. This field is displayed in the reports so that merchant supplied order_id’s would be visible to them. |
payment_category | RO | String | These are added to the transaction only from Click-n-pay when the consumer chooses one of the categories specified by the merchant when they schedule the payment. |
track1 | O | String | Track1 data obtained from scanned credit cards. This data is only accepted when creating a transaction and is not returned as part of the TransInfo object |
track2 | O | String | Track2 data obtained from scanned credit cards. This data is only accepted when creating a transaction and is not returned as part of the TransInfo objectas part of the TransInfo object |
check_image_front | O | Base64Binary | For imaged ACH transactions, this is the front image of the check |
check_image_frontback | O | base64BinaryBase64Binary | For imaged ACH transactions, this is the front image of the check |
check_image_back | O | base64Binary | For imaged ACH transactions, this is the back image of the check |
custom_fields | O | array | Array containing CustomField data that should be attached to the transactionback image of the check |
custom_fields | O | Array | Array containing CustomField data that should be attached to the transaction. |
verify_ach | O | Boolean | Set to true to enable.. otherwise, default is off. There are two levels of ACH verification but that is set on the Account Level at gotoBilling. If an ACH transaction receives an Authorization the status sent back will be R, if it is Declined, the status will be D. |
lock_status | O | intInt | The lock status will indicate any type of user or system lock that is current in affect for the transaction:
|
...
Field Name | Read Only (RO) | Data Type & Length | Description & Field Values |
---|---|---|---|
transaction_id | RO | Int | Unique number that is assigned by GTB for every transaction entered into the system. This number will match the tran_id field assigned in TransactionInfo. |
item_id | RO | String | No currently used. |
funds_direction | RO | String | Identifies the general direction of the settlement funds. There are two possible values for this field
|
category_code | RO | Int | Determines category of the settlement.
|
reason_code | RO | Int | A sub category code that provides more details about the transaction
|
process_date | RO | Int | Indicates the date on which the transaction was originally processed. Given in the format 'YYYMMDD'. |
settle_date | RO | String | Indicates the date on which the transaction was settled or returned. Given in the format 'YYYMMDD'. |
customer_account | RO | String | Account number of the customer |
customer_name | RO | String | Name of the customer |
account_number | RO | String | Masked account number that the transaction has settled or returned against. |
check_number | RO | String | Check number assigned when the transaction was processed. |
amount | RO | floatFloat | Amount of the transaction |
return_reason | RO | String | If record is a return, this will be the Return Code providing the reason for the return. |
...
CustomField Fields
Field Name | Required Optional Conditional Read Only (ROR); | Data Type & Length | Description & Field Values |
---|---|---|---|
id | R | Int | The unique identifier for the custom field as provided by GotoBilling. |
value | R | Int | Value assigned to the custom field. |
...
- 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.
Code | Description |
---|---|
101 | You are not authorized to use this service with the credentials you provided. Be sure you have supplied the correct Login and pin. |
102 | Invalid customer ID, either the supplied ID did not exist or was incorrectly formatted |
103.1 | Invalid account ID, either the supplied ID did not exist or was incorrectly formatted |
103.2 | Invalid account ID, either the supplied ID did not exist or was incorrectly formatted |
104 | A routing number is required for ACH accounts |
105 | The account type supplied is unknown |
106 | Invalid account number |
107 | A valid routing number must be supplied |
108 | Card expiration date was in an invalid format. Valid format is: MMYY |
109 | An attribute was supplied out of order, make sure that the parameters are in the correct order and resubmit |
110 | Invalid transaction ID, either the supplied ID did not exist or was incorrectly formatted |
111 | Auth_type field is required for ACH transactions. |
112 | A PO number is required for corporate card transactions |
113 | The sales_tax_type field is required when submitting sales tax |
114 | A ticket_id must be supplied to void a transaction. |
115 | An occurrence type is required for all transactions. |
116 | Invalid transaction date. The date you supplied was not a valid date string representation. |
117 | Transaction date must be for the current or future date. |
118 | Transaction is locked and cannot be changed at this time. |
119 | Invalid tran_type. |
120 | Invalid record type. Refer to the TransactionInfo complex type for valid values. |
121 | Invalid amount. Amounts must be a valid number. |
122 | You do not have the necessary permissions to do the requested action. |
123 | The first_name attribute must be supplied for a customer contact. |
124 | The last_name attribute must be supplied for a customer contact. |
125 | The company attribute must be supplied for a company customer. |
126 | Invalid customer_name given. |
126.1 | Invalid customer_name given. Already in use by another customer. |
127 | The occurrence number you specified is invalid. |
128 | Invalid card security code(CVV). The CVV code submitted was invalid, it must be 4 or less numbers. |
129 | Invalid card zip code. |
130 | Invalid search criteria |
131 | Invalid lock status given. |
132 | Cannot delete this account, there are pending transaction associated with it |
133 | Velocity Limit has been exceeded. |
Usage Examples
Create a customer and return the GTB assigned Customer ID
...