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
...
Transactions are broken up into delimited fields. A transaction is transmitted either in the request header for the GET method , or following the request headers for the POST method.
Notes about the Merchant IDs and PINs
...
Changelog
x_version | Description | Date |
---|---|---|
~ | 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 |
Notes about the Merchant IDs and PINs
- Merchant IDs (also called Merchant-IDs) and PINs are issued by gotoBilling upon approval of a merchant's account application. These are sensitive fields that must remain confidential. Under no circumstances should the contents of these fields be available to the shopper, either on-screen or through a browser's View/Source command. Instead, they should be filled in by the merchant's web application prior to forwarding to GOTOBILLING.
- Merchants must be approved in advance to submit electronic check credit transactions. Once approved, specific conditions apply.
...
The Purpose of the x_payment_token_id field is to allow a “one-time” sending of the Credit Card number or the Route and Account number (for an ACH transaction) and then be able to reference it in the future without needing to send the card number or account number again. This allows an application to be developed where it does not have to store these sensitive numbers but instead, gotoBilling is the only place these numbers are stored securely. A future transaction may be as simple as needing to process a credit card refund or an ACH credit. This can now be accomplished if the associated x_payment_token_id from the original transaction is sent. Therefore, the application must keep a database of x_payment_token_ids for all transactions sent if future transactions using this field are to be performed. The following are the basic points regarding using this feature:
- Initially, the payment account information (CC Number, ACH Account) can be sent along with the x_payment_token_id.
- The account can then be accessed in the future by simply by passing the x_payment_token_id for the desired account. The individual account information is not needed.
- 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. Technically it only has to be unique per Customer ID (x_customer_id) but it might be easier to design if it is unique across the entire Merchant ID (merchant_id) so there’s no duplication at all. One suggestion would be to have the x_payment_token_id be the x_customer_id+(some value) where the value could be the date in YYYYMMDD format. This would facilitate easier research if needed and would likely be easier to implement than other numbering schemes. Especially since the x_customer_id must be unique across the Merchant ID.
IMPORTANT NOTE: Validation for the uniqueness of this field will be added in the future, however, it is not currently live.
...
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) |
Customer Fields
Field | Required | Max Length | Description |
---|---|---|---|
x_customer_id | Required | ans 32 | A unique customer Identification number set by the merchant. |
x_company | Conditional | an 32 | The company associated with the billing address. Either first name & last name, or company name must be given. |
x_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. |
x_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. |
x_address1 | Optional | an 32 | The address associated with the billing address |
x_address2 | Optional | an 32 | Continuation address associated with the billing address |
x_city | Optional | a 40 | The city associated with the billing address |
x_state | Optional | a 2 | The state associated with the billing address. The state is formatted using the two letter post abbreviation. Example: FL |
x_zip | Optional | ns 10 | The zip code associated with the billing address |
x_phone | Optional | n 10 | The phone number of the customer associated with the billing address. Does not contain any dashes – ex. 2223334444 |
x_email | Optional | ans 50 | The email of the customer associated with the billing address. |
...
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>G</status> <order_number>122879-20050804-985829</order_numbernumber> <term_code>0</term_code> <tran_amount>36.00</tran_amount> <tran_date>20160804</tran_date> <tran_time>091121</tran_time>
<ticket_id>1234</ticket_id> <auth_code>094533</auth_code>"; <description>APPROVED</description> <avs>GOOD</avs> <cvv>UNKNOWN</cvv>
</ <type>card</type>
<card>
<network>Visa</network>
<number>4111xxxxxxxx1111</number>
<expiration>1215</expiration>
</card>
</ResponseData>
Credit Card PRE-AUTH, CAPTURE
...
<ResponseData> <status>G</status> <order_number>123456-20050804-985829</order_number <term_code>0</term_code> <tran_amount>36.00</tran_amount> <tran_date>20160804</tran_date> <tran_time>091121</tran_time> <ticket_id>1234</ticket_id> <auth_code>094533</auth_code>"; <description>APPROVED</description> <avs>GOOD</avs> <cvv>UNKNOWN</cvv>
<type>card</type>
<card>
<payment_token_id>tok_194bfc699e124281b87f1ad4266e64be</payment_token_id> </ResponseData>
CAPTURE Request
POST https:// <network>Visa</network>
<number>4111xxxxxxxx1111</number>
<expiration>1215</expiration>
</card> <payment_token_id>tok_194bfc699e124281b87f1ad4266e64be</payment_token_id> </ResponseData>
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 = "DS"
x_customer_id = "27500000001"
x_amount = "36.00"
x_ticket_id = "1234"
...
<ResponseData>
<status>G</status>
<order_number>123456-20170509-59120e0c5b178</order_number>
<term_code>0</term_code>
<tran_amount>36.00</tran_amount>
<tran_date>20160804</tran_date>
<tran_time>091121</tran_time>
<ticket_id>1234</ticket_id>
<auth_code>094533</auth_code>";
<description>APPROVED</description>
<avs>GOOD</avs>
<cvv>UNKNOWN</cvv>
<phard_code>SUCCESS</phard_code>
<payment_token_id>tok_194bfc699e124281b87f1ad4266e64be</payment_token_id>
</ResponseData>
...
<ResponseData> <status>G</status> <order_number>123456-20161128-583c83a833fcd</order_number> <term_code>0</term_code> <tran_amount></tran_amount> <tran_date>20161128</tran_date> <tran_time>132112</tran_time> <invoice_id></invoice_id> <transaction_id></transaction_id>
<type>card</type>
<card>
<network>Visa</network>
<number>4111xxxxxxxx1111</number>
<expiration>1215</expiration>
</card> <payment_token_id>tok_9fc0739aa554441e96151bae88943154</payment_token_id> </ResponseData>
...
<ResponseData> <status>G</status> <order_number>122879-20050804-985829</order_number <term_code>0</term_code> <tran_amount>36.00</tran_amount> <tran_date>20160804</tran_date> <tran_time>091121</tran_time> <ticket_id>1234</ticket_id> <auth_code>094533</auth_code>"; <description>APPROVED</description> <avs>GOOD</avs> <cvv>UNKNOWN</cvv>
<type>card</type>
<card>
<network>Visa</network>
<number>4111xxxxxxxx1111</number>
<expiration>1215</expiration>
</card> <payment_token_id>tok_5aeda1a4e5e244cbbb45d6594dbb1ad</payment_token_id> </ResponseData>
...
The Gateway Response API defines the type of information that will be sent by the gateway once a transaction has been processed. The gateway response type can be changed from the default XML response to a JSON response by passing in x_version=1.2 through incoming parameters, as outlined in the Optional Fields section above.
Non-Rely Response.
Gateway Responses are delimited by the GOTOBILLING tags:
<ResponseData> </ResponseData>
Tag name | Description |
---|---|
<status></status> | Transaction Status. Values are:
Response Statuses for Various Transaction Types: Credit Card:
Future dated transactions always get R on both Credit Card and ACH transactions. When using the ACH Verification option, if an ACH transaction receives an Authorization the status sent back will be R, if it is Declined, the status will be D. An |
<order_number></order_number> | A 22-digit code, formatted nnnn-nnnnn-nnnnn, used by GOTOBILLING to synchronize and track transactions and orders. It is not used or recognized by the GOTOBILLING host computers. |
<term_code></term_code> | The reason the gotoBilling process terminated. Values are: 30998 Internal software error. 20999 Missing or invalid Merchant-ID 20998 Could not validate Merchant-ID 20997 Invalid server (potential security violation) 20996 Missing transaction type 20995 Invalid transaction type 20994 Reserved 20993 Reserved 20992 Reserved 20991 Reserved 20990 Reserved 20989 Both Card and Check services are turned off 20988 Merchant is not approved for service 20987 Reserved 20986 Reserved 20985 Reserved 20984 Reserved 20983 Reserved 20982 Reserved 20981 Reserved 20980 Reserved 20979 A required transaction field is missing 20978 A required transaction field is invalid/missing 0 Normal Termination On 20979 and 20978 the <description> field will tell what field it is that is missing or invalid. |
<tran_amount></tran_amount> | The amount of the transaction. This field should be the same as the field x_amount in the submitted transaction (see above). |
<tran_date></tran_date> | Date Stamp of when the transaction was processed. Format: YYYYMMDD |
<tran_time></tran_time> | Time Stamp of when the transaction was processed. Format: HHMMSS |
<invoice_id></invoice_id> | Echo of merchant submitted Order ID |
<ticket_id></ticket_id> | For credit card transactions this is the 'x_ticket_id' that is used when performing a void or refund. |
<auth_code></auth_code> | Reference number identifying the transaction on the gateway |
<description></description> | Description of any error or decline returned for the transaction. |
<avs></avs> | AVS response text
|
<cvv></cvv> | CVV response text
|
<phard_code></phard_code> | Text supplied by the card issuer. Generally additional details about a decline |
Example Non-Relay Response Data
<ResponseData>
<status>R</status>
<order_number>122879-20050804-985829</order_number
<term_code>0</term_code>
<tran_amount>12.33</tran_amount>
<tran_date>20050804</tran_date>
<tran_time>091121</tran_time>
<invoice_id>123549854</invoice_id>
</ResponseData>
Relayed Response
A relayed response will contain the same information, but will be formatted in a HTTP REQUEST string. Active being POST and Inactive being GET.
Example Relay Response Data
?status=R&order_number=122879-20050804-
985829&term_code=0&tran_amount=12.33&tran_date=20050804&tran_time=091121&invoice_id=123549854
Example Non-Relay Response Data with ACH Verification
Approval
<ResponseData>
<status>R</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>AUTH NUM 123-1234</description>
</ResponseData>
Decline
...
<version></version> | (optional response) Version response text is returned ONLY when x_version is specified in incoming parameters.
|
<type></type> | (Conditional response based on type of payment specified) The type of payment received will be indicated by the following values:
The type value returned in this node will indicate what payment type value node to look for in the provided response. |
<card> <network></network> <number></number> <expiration></expiration> </card> | (Conditional response provided ONLY for Credit Card payments) Additional information about the credit card payment type will now be included in the card node. Children nodes include:
|
<bank> <account></account> <routing></routing> </bank> | (Conditional response provided ONLY for ACH payments) Additional information about the ACH payment type will now be included in the bank node. Children nodes include:
|
<payment_token_id></payment_token_id> | Token assigned to the payment account. Can be used in subsequent request instead of providing the actual card or bank details. |
Example Non-Relay Response Data
<ResponseData>
<status>R</status>
<order_number>122879-20050804-985829</order_number
<term_code>0</term_code>
<tran_amount>12.33</tran_amount>
<tran_date>20050804</tran_date>
<tran_time>091121</tran_time>
<invoice_id>123549854</invoice_id>
</ResponseData>
Relayed Response
A relayed response will contain the same information, but will be formatted in a HTTP REQUEST string. Active being POST and Inactive being GET.
Example Relay Response Data
?status=R&order_number=122879-20050804-
985829&term_code=0&tran_amount=12.33&tran_date=20050804&tran_time=091121&invoice_id=123549854
Example Non-Relay Response Data with ACH Verification
Approval
<ResponseData>
<status>R</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>AUTH NUM 123-1234</description>
</ResponseData>
Decline
<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>
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>
...