Import file specifications
Data Import
The Import API defines the file specifications that may be used to upload customer data to the GoToBilling application. Imports are broken up into comma delimited fields, and may be uploaded using the Import feature located in the Resources section.
The first row of the import file MUST contain the headers that specify the type of information given in that field. All records must follow the same template given in the header row.
Any mix of information is supposed.
Data Types Conventions
| Modifier | Definition |
|---|---|
| a | Alpha characters [a-z, A-Z] |
| n | Numeric digits [0-9] |
| s | Special characters [-_:@&+#$/’=~^] |
NOTE: Header Fields (must be used for the first row). Field order is not important.
Whether including customer or transaction data, the Account ID field MUST be present.
Please be sure that routing and account numbers have retained any leading zeros before uploading an import file.
File Import Fields
Customer Information
| Field | Required | Max Length | Description |
|---|---|---|---|
| Account ID | Required | an 64 | Set by the Merchant. Unique ID associated with the customer. MUST BE UNIQUE FOR EACH CUSTOMER |
| Company | Conditional | an 32 | The company associated with the billing address. Either first name & last name, or company name must be given. |
| First Name | Conditional | an 32 | The first name of the customer associated with the billing address. Either first name & last name, or company name must be given. |
| Last Name | Conditional | an 32 | The last name of the customer associated with the billing address. Either first name & last name, or company name must be given. |
| Display As | Optional | 'company' or 'contact' | Sets the display name of the customer account to either the company or contact name |
| Address 1 | Optional | an 32 | The address associated with the billing address |
| Address 2 | Optional | an 32 | Continuation address associated with the billing address |
| City | Optional | a 40 | The city associated with the billing address |
| State | Optional | a 2 | The state associated with the billing address. The state is formatted using the two letter post abbreviation. Example: FL |
| Zip Code | Optional | ns 5 | The five (5) digit zip code associated with the billing address |
| Phone Number | Optional | n 10 | The phone number of the customer associated with the billing address. Does not contain any dashes – ex. 2223334444 |
| Optional | ans 50 | The email of the customer associated with the billing address. |
Payment Account Information
| Field | Required | Max Length | Description |
|---|---|---|---|
| ACH INFORMATION | |||
| Bank Name | For ACH transactions: Optional | an 32 | The name of the bank the customer’s account is located under. |
| Bank Routing # | For ACH transactions: Required | n 9 | Routing number of the bank associated with the customers bank account |
| Bank Account # | For ACH transactions: Required | an 20 | Routing number of the bank associated with the customers bank account |
| Bank Account Type | For ACH transactions: Optional | a 2 | Personal Accounts
Business Accounts
|
| CREDIT CARD INFORMATION | |||
| Credit Card Type | For CC transactions: Optional | a 2 | Card Types:
|
| Name on Card | For CC transactions: Optional | a 32 | Contains the name located on the credit card |
| Credit Card Number | For CC transactions: Required | n 22 | Contains the credit card number |
| Expiration | For CC transactions: Required | n 4 | Contains the expiration date for the credit card. Format: MMYY |
| Card CVV | For CC transactions: Optional | n 4 | Three or Four digit validation number for the credit card |
Additional Information
| Field | Required | Max Length | Description |
|---|---|---|---|
| Notes | Optional | ans 255 | Merchant notes for the customer. |
| Owed Amount | Optional | n 10 | Used for scanned transactions. This amount will be displayed automatically when a check or credit card is scanned matching the customers account. If no decimal is given two (2) decimal places are assumed (1.00 = 100). |
Transaction Information
| Field | Required | Max Length | Description |
|---|---|---|---|
| Amount | Required for transactions | n 10 | The amount of the transaction. Decimal must be included. |
| Type | Required | a 10 | Specifies the transaction type. Valid Types:
|
| Authorization | Required for ACH transactions | a 10 | Specifies the form of authorization obtained to debit/credit the customers ACH account. Default is Written. Valid Types:
|
| Record | Required | a 10 | Specifies the record type. Default is Debit/Sale. ACH Valid Types:
Credit Card Valid Types:
|
| Occurrence | Optional | a 10 | Specifies the occurrence type. Default is Single. Valid Occurrences:
|
| Occurrence Number | Optional | n 4 | Specifies the number of occurrences a particular transaction will have. Default is blank (indefinite). |
| Transaction Date | Optional | an 10 | Process date for the transaction. If none is given defaults to today’s date. Format: MM/DD/YY |
| Transaction Memo | Optional | ans 250 | Note that pertains to the transaction and is emailed to the customer with the transaction confirmation. |
| Transaction Note | Optional | ans 250 | Note that pertains to the transaction and stays internal in gotoBilling |
| Transaction ID | Optional | n 10 | Unique Transaction ID provided in file by merchant that will carry through to GTB reports and file exports. |
| PO Number | Optional | n 25 | Contains the purchase order number. |
| Presentment | Optional | n 25 | Only used for RCK transactions. Indicates the presentment number for the check being submitted. |
Example:
Account ID, Company, First Name, Last Name, Address 1, City, State, Zip Code, Phone Number, Email, Bank Routing #, Bank Account # 12345,Test company,Test,Account,123 Main St.,Somewhere,US,36079,3345558562,test@tester.com,123123123,0029157
Notes: Use “text fields” if working in MS Excel so the leading zero is not dropped from Bank Routing and Account numbers.
If submitting multiple bank or credit card accounts for one customer, use different Account IDs for each. The 2nd set of account information will overwrite the 1st in the same file.