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

https://secure.gotobilling.com/os/system/gateway/transact.php

GOTOBILLING recognizes and processes both GET and POST methods. The interface between the ISP and GOTOBILLING is the standard HTTP/1.0 (or HTTP/1.1) protocol using Secure Sockets Layer (SSL) encryption.

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.

Changelog

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.

Use of the x_payment_token_id field

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 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.

When using the x_payment_token_id to reference an existing credit card on file, the following credit card fields are not needed as they will already be on file in gotobilling when the original transaction was sent:

• x_cc_type
• x_cc_name
• x_cc_number
• x_cc_exp

For ACH transactions, the following fields will not be needed since they will be on file:

• x_ach_route
• x_ach_account
• x_ach_account_type

Data Type Conventions

Transaction Fields

Merchant Credentials

Merchant credentials can be submitted in a couple of different ways.  The legacy method of using the six digit merchant ID and gateway pin, or using an API access key pair.  Only one set of credentials are required.  It is recommended to use the API key pair which allows for greater control over the credentials.  You can generate an Access key pair in the OmniFund dashboard by visiting:  Profile > API Access

API Access Key Pair

For more information on obtaining an API access key, see: Managing API Access Keys

OAuth2 Client ID & Secret

For more information on obtaining and working with an OAuth2 client, see: Managing OAuth Clients

OAuth2 Client ID & Access Token

For more information on obtaining and working with an OAuth2 client, see: Managing OAuth Clients

Merchant ID and PIN **DEPRECATED**

For more information on obtaining your PIN, see: Generating a Merchant Gateway Pin

Optional Fields

Customer Fields

Transaction Information

Transaction Information - ACH

Transaction Information – Credit Card

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"

Response (Approval)

<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>
</ResponseData>

Credit Card PRE-AUTH, CAPTURE

PRE-AUTH 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 = "AS"
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"

Response (Approval)

<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>
     <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"

Response (Approval)

<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>

Tokenization

Credit Card Tokenization 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 = "TK"
x_customer_id = "27500000001"
x_first_name = "Test"
x_last_name = "Account"
x_zip = "55555"
x_cc_number = "4111111111111111"
x_cc_name = "Ester Tester"
x_cc_exp = "1215"

Response

<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>

Credit Card Tokenization via Initial Sale 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"

Response

<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>

Subsequent Requests

All other request may utilize the 'x_payment_token_id' instead of the card data.

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 = "5.00"
x_payment_token_id = "tok_5aeda1a4e5e244cbbb45d6594dbb1ad"

Gateway Response

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>

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

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

Level 2 Verification Information

Level 2 verification will return some additional information with the verification AUTH NUM. This additional info will be passed with the AUTH NUM in the <description> field with a pip ("|") delimiter.

Additional Info

Format

<description>
AUTH NUM|ADDITIONAL INFO
</description>

Example

<description>
AUTH NUM 53793041|Non-Participating: No Info
</description>

Debug and Test Card Information

We also have some updated debug methods, which will be in the next version of the documentation. With this, while in debug mode (x_debug=1), you can trigger the gateway to give you an approve, decline or error response based on the reset of the information sent over.

Card #s that will return an approval "G"

• 370000000000002
• 6011000000000012
• 4007000000027
• 5424000000000015

Card #s that will return a decline "D"

• 4222222222222

All other Card#s return an error "E"

Loopback Testing Procedures

gotoBilling now provides a built in (offline) processor module called 'Loopback' that can be used for black-box testing.

Overview: The 'Loopback' processor module was designed and implemented to replicate the base functionality of a 'Live' Processor for testing, training and development environments. Currently the Loopback module supports the following transaction types:

• Credit Cards
• Debit Cards

Note: The 'Loopback' module was designed for black_box testing against defined transaction amounts (i.e by supplying a certain amount you will force a defined response back from the server). Any amount other than the ones listed below should return a valid Authorization(AUTH). For this module to work you must set debug=0 and be using a valid development account issued by gotoBilling. To test integration with live merchant accounts please use the debug instructions located in the HTTP Integration API Package.

Test Parameters

Valid AVS

Street: 14520 Main Street Zip: 32615

-or-

Street: 2831 NW 41st St STE J Zip: 32606

Valid CV: (This must be supplied or you will always receive a Decline response)

Visa/MC/DISC: 999 Amex: 1234

Old basic amount checks

New amount checks (phard_code)

New amount checks (msoft_code)

Visa Cardlevel Results

If you have any questions regarding testing with the Loopback module, simply email support@gotobilling.com or visit the support desk at support.gotobilling.com