| Table of Contents |
|---|
Overview
Purpose
The Gateway Submission API defines the type of information that may be sent to the gateway. When transmitting data to the gateway, information should be posted to
...
Changelog
| x_version | Description | Date | 1.3 |
|---|---|---|---|
| ~ | Added PN transaction-type for indicating ACH Pre-Note requests. | 2021-07-14 | |
| 1.3 | x_customer_id now allows for alpha-numeric characters, as well as, the special characters period ., underscore _, and dash - | 2021-06-15 |
...
| Field | Required | Description |
|---|---|---|
| client_id | Required | Generated Client ID |
| access_token | Required | User access token |
Merchant ID and PIN
...
**DEPRECATED**
For more information on obtaining your PIN, see: Generating a Merchant Gateway Pin
Optional Fields
| Field | Required | Max Length | Description |
|---|---|---|---|
| x_relay_url | Optional | an. .. | Contains the URL to which the gateway will post the response. Include http:// or https://. When set the gateway response will automatically be sent via HTTP POST to this location. |
| x_relay_type | Optional | a. 7 | Indicates the type of action of the response. When ACTIVE is set the browser will automatically be sent to the location specified with x_relay_url. When PASSIVE is set the browser will not be redirected, but the response will be sent to the location specified with x_relay_url via HTTP POST. This is set to default to PASSIVE |
x_debug | Optional | n. 1 | When set to 1 (numerical one) transactions will be sent in test mode. A response will be given for the transaction, but no processing will occur. Default: 0 (zero). |
| x_version | Optional | ns 3 | DEFAULT: 1.1 (When this value is set to 1.2, the transaction Gateway Response will be returned in JSON format, rather than XML format) |
...
| Field | Required | Max Length | Description |
|---|---|---|---|
| x_transaction_type | Required | 2 | This field identifies the type of transaction being submitted. Valid transaction types are: Credit Card Type:
ACH Transactions:
Transaction Administration:
|
| x_invoice_id | Required | an 32 | Unique transaction ID field specified by the merchant. Also used in determining duplicate submissions. For transaction type ‘RM’ this can be set to a specific id to remove a single transaction, or can be set to ‘ALL’ to remove all transactions currently pending for the given customer id. |
| x_amount | Required | n 10 | Amount to be charged or credited. AmountThe amount may be formatted with or without a decimal. If no decimal is given two (2) decimal places are assumed (1.00 = 100). Note: Must be zero (0) for |
| x_process_date | Optional | n 8 | Date on which the transaction is to be processed. If no date is given, the transaction will default to the date it is submitted on. Format: YYYYMMDD |
| x_invoice_file | Optional | File containing information to be sent to the customer via email when the transaction is processed. | |
| x_payment_token_id | Optional | an 20 | 1) Initially the payment account information (CC Number, ACH Account) can be sent along with the x_payment_token_id. 2) The account can then be accessed in the future simply by passing the x_payment_token_id for the desired account. The individual account information is not needed. 3) If any account information is passed with an existing x_payment_token_id. That account information will be updated to match the information given. The x_payment_token_id should be unique. Validation will be added for this, however it is not currently live. |
| x_memo | Optional | ans 255 | Description of transaction to be forwarded to the customer. |
| x_notes | Optional | ans 255 | Internal notes to be stored with the transaction. |
| x_occurrence_type | Optional | an 10 | Used for setting up recurring transactions. Available types: • week • biweek • month • bimonth • quarter • semiannual • annual |
| x_occurrence_number | Optional | n 3 | Specify the number of occurrences for a recurring transaction. If no occurrence number is giving, the default will be set to indefinite until deleted manually. |
| x_source_description | Optional | an 20 | This is to be used by the developer to send the name and version number of the software that is sending the transactions. It’s a free form description field to tell GTB the source of the transactions. |
| x_module_description | Optional | an 20 | This field is used by the developer to send the name and version number of a module or plugin that was built using this API. This allows for proper tracking of plugins or modules that may be built and then used in other software applications. The end software application name and version number would be put into the “source_description” field. |
| x_custom_field | Optional | n 1 | Presentment indicator for ACH transactions. |
| x_po_number | Optional | an 50 | PO number associated with the transaction. Unique PO numbers can also be used by allow duplicate transactions if duplicate processing is current disabled. |
...
| Field | Required | Max Length | Description |
|---|---|---|---|
| x_cc_type | For cc transactions: Optional | a 2 | Card Types:
|
| x_cc_name | Optional | a 32 | Contains the name located on the credit card |
| x_cc_number | Conditional | n 22 | Contains the credit card number. Can send the x_payment_token_id to reference an existing Credit card on file. |
| x_cc_exp | Conditional | n 4 | Contains the expiration date for the credit card. Format: MMYY Can send the x_payment_token_id to reference an existing Credit card on file |
| x_cc_cvv | Optional | n 4 | Three or Four digit validation number for the credit card |
| x_ticket_id | Conditional | n 32 | Ticket ID of a transaction previously approved by the gateway. This is required for the following transaction types: DS (capture), CR (refund), VO (void) |
| x_authorization | Conditional | n 32 | Authorization code of a transaction previously authorized by the gateway. This is required for the following transaction types: OF (offline force) |
| x_trackdata | Optional | n 4 | Combined Track1 and Track2 data from credit card POS device. |
Example Requests
Credit Card AUTH-CAPTURE
Request
...
| x_token | Optional | ans .. | A valid 3DS (3D Secure) payment token, issued by a trusted provider offering payment tokenization, must be presented in this field. The x_token field value must be included along with the other conditionally required fields for Credit Card type transactions (x_cc_number, x_cc_exp and x_cc_cvv). |
Example Requests
Credit Card AUTH-CAPTURE
Request
POST https://secure.gotobilling.com/os/system/gateway/transact.php
Content-Type: application/x-www-form-urlencoded
merchant_id = "123456"
merchant_pin' = "gatewayPin"
x_transaction_type = "ES"
x_customer_id = "27500000001"
x_first_name = "Test"
x_last_name = "Account"
x_zip = "55555"
x_amount = "36.00"
x_cc_number = "4111111111111111"
x_cc_name = "Ester Tester"
x_cc_exp = "1215"
...
<ResponseData> <status>D</status> <order_number>122879-20081217198384</order_number> <term_code>0</term_code> <tran_amount>1.01</tran_amount> <tran_date>20081217</tran_date> <tran_time>131643</tran_time> <invoice_id>44444</invoice_id> <description>CHEXDIRECT|DECLINE CHECK|3 UNPAIDS (ALL)|UNPAID AMT= 35|PHN 800-238-5888|EXPRESS RECOVERY</description>
</ResponseData> id>44444</invoice_id> <description>CHEXDIRECT|DECLINE CHECK|3 UNPAIDS (ALL)|UNPAID AMT= 35|PHN 800-238-5888|EXPRESS RECOVERY</description>
</ResponseData>
Level 1 Verification Information
Level 1 ACH verification compares the given account information against a neg file database. Results for accounts that do not contain any negative data will return an AUTH NUM indicating that no negative events have been recorded for the account. Additional info will be passed in the <description> field.
Additional Info
| value | description |
|---|---|
| History of Ineligible | Account does have a reported history and there is known transaction history on the account. |
| Routing Number is Invalid | Invalid bank routing number |
| History of Unauthorized | Account does not have a reported history or returns for Account Closed, Invalid Account, No account found, or Unable to locate, the routing number and account format are verified and there is no known transactional history on the account. |
Wrong Account Structure | The account identified as suspicious format |
| Not populated | Account does not have a reported history or returns for Account Closed, Invalid Account, No account found, or Unable to locate, the routing number and account format are verified, and there is known transactional history on the account. |
Format Accept
<auth_code>
AUTH NUM
</auth_code>
Example Accept
<auth_code> AUTH NUM 6847027C </auth_code>
Format Warning/Reject
<description>
ADDITIONAL INFO
</description>
Example Warning/Reject
<description>
HISTORY OF UNAUTHORIZED
</description>Debug and Test ACH Information
| decision | value | bank name | routing number | account number |
|---|---|---|---|---|
| ACCEPT | Valid (AUTH NUM) | Bank of America | 053200983 | 11101010 |
| WARNING | History of Ineligible | Bank of America | 226078036 | 13590100098321 |
| WARNING | Routing Number is Invalid | Bank of America | 053200983 | 11101012 |
| DECLINE | History of Unauthorized | Bank of America | 226078036 | 13590100098319 |
| WARNING | Wrong Account Structure | Bank of America | 053200983 | 11101015 |
Level 2 Verification Information
Level 2 verification will return some additional information with the verification AUTHNUMAUTH NUM. This additional info will be passed with the AUTHHUM AUTH NUM in the <description> field with a pip ("|") delimiter.
Additional Info
| value | description |
|---|---|
| Non-Participating: Negative Information | This customer's bank does not participate in the Bank ACH Verification system. However, the normal negative database has negative information (returned checks) that are in the system. |
| ACH Unavailable | This merchant's bank account is not able to be debited via the ACH system. |
| Non-Participating: No Info | This customer's bank does not participate in the Bank ACH Verification system and the customer's bank account has not been seen in the negative database system. |
| Account Closed or Neg Status | The customer's bank participates in the Bank ACH Verification system and is reporting this account as Closed or in a state that will result in the ACH transaction being returned. |
| Account Good | The customer's bank participates in the Bank ACH verification system and is reporting this account as open and in good standing. |
Format
<description> AUTH AUTHNUMNUM|ADDTIONALINFOADDITIONAL INFO </description>
Example
<description> AUTH NUM 53793041|Non-Participating: No Info </description>
...