Transactions

This section describes the resource used to process transactions against The Secure Gateway.

Create

Method: POST

Url: https://api.thesecuregateway.com/rest/v1/transactions

POST /rest/v1/transactions HTTP/1.1
Host: api.thesecuregateway.com
Content-Type: application/xml
Accept: application/xml
api_key: a20effd6dc1d4512888e6b06d870248a
<transaction>
  <type>SALE</type>
  <card>4111111111111111</card>
  <amount>5.00</amount>
  <exp_date>1020</exp_date>
</transaction>
HTTP/1.1 200 OK
Content-Type: application/xml
<transaction>
  <result>Approved</result>
  <id>232352</id>
  <display_message>Transaction Approved</display_message>
  <authorization_code>654124</authorization_code>
  <result_code>0000</result_code>
</transaction>
HTTP/1.1 200 OK
Content-Type: application/xml
<transaction>
  <result>Error</result>
  <display_message>Field Validation: Invalid expiration date</display_message>
  <error_code>8000</error_code>
</transaction>

List

Method: GET

Url: https://api.thesecuregateway.com/rest/v1/transactions

Use this method to retrieve a list of transactions. The list can be filtered using the fields described below as query parameters. All fields are optional.

Filter fields

Name Format Description Default
page_size N Limits the number of transactions returned by this method. Sometimes called "limit." Maximum is 100. 25
page N Specifies which page of results is returned. Page index starts at '1'. Ex: if page = 2 and pageSize = 50, then this method will return transactions 51 - 100 (or the maximum transactions available). If no transactions exist in this range, then a blank list is returned. 1
order_by A Specifies which field to sort the transaction list by. Field names are case sensitive. See "Other Fields" list below for valid fields. id
descending A Specifies which direction to sort the transaction list by. Valid values are true and false. true
start_date A/N Filters the transaction list by the created date / time. Setting start_date will return transactions that were created after this date / time. Setting both start_date and end_date creates a range. See the "Valid Date / Time Formats" list below.
end_date A/N Filters the transaction list by the created date / time. Setting end_date will return transactions that were created before this date / time. Setting both start_date and end_date creates a range. See the "Valid Date / Time Formats" list below.
Valid Date / Time Formats

  • MM-dd-yyyy hh:mm a
  • MM-dd-yy HH:mm
  • MM-dd-yy HH:mm z
  • yyyy-MM-dd HH:mm
  • yyyy-MM-dd HH:mm z

Other Fields

Other fields available for filtering are: id, amount, type, result, last_four, authorization_code, invoice, order_id, first_name, last_name. See the Full Fields List for field details.

GET /rest/v1/transactions?page_size=3&amount=5.00&type=SALE&order_by=invoice HTTP/1.1
Host: api.thesecuregateway.com
Accept: application/xml
api_key: a20effd6dc1d4512888e6b06d870248a
HTTP/1.1 200 OK
Content-Type: application/xml
<transactions>
  <transaction>
    <amount>5.00</amount>
    <authorization_code>654124</authorization_code>
    <billing_is_shipping>false</billing_is_shipping>
    <card>**** **** **** 0026</card>
    <created>2012-09-07T16:29:23.257-05:00</created>
    <display_message>Transaction Approved</display_message>
    <id>23552</id>
    <invoice>689093</invoice>
    <result>Approved</result>
    <result_code>0000</result_code>
    <type>Sale</type>
  </transaction>
  <transaction>
    <amount>5.00</amount>
    <authorization_code>654125</authorization_code>
    <billing_is_shipping>false</billing_is_shipping>
    <card>**** **** **** 1174</card>
    <created>2012-09-07T16:25:11.141-05:00</created>
    <display_message>Transaction Approved</display_message>
    <id>23553</id>
    <invoice>378392</invoice>
    <result>Approved</result>
    <result_code>0000</result_code>
    <type>Sale</type>
  </transaction>
  <transaction>
    <amount>5.00</amount>
    <authorization_code>654128</authorization_code>
    <billing_is_shipping>false</billing_is_shipping>
    <card>**** **** **** 0026</card>
    <created>2012-09-07T16:24:22.190-05:00</created>
    <display_message>Geographic location is blocked</display_message>
    <id>23552</id>
    <invoice>215782</invoice>
    <result>Rejected</result>
    <error_code>8008</result_code>
    <type>Sale</type>
  </transaction>
</transactions>
HTTP/1.1 204 No Content

Request

Name Format Description Transaction Types
type A/N Supported Transaction Types are:
  • SALE
  • FORCED SALE
  • AUTH
  • CAPTURE
  • REFUND
  • VOID
See Transaction Types list for details.
ALL Required
id N Used to identify the transaction to be captured, refunded or voided. The value provided here must be the one returned in the original transaction response. CAPTURE, REFUND, VOID only Required
card N Cardholder’s payment card account number. SALE, FORCED SALE, AUTH only Required (Not required if encrypted_track_data is present)
csc N

The Card Security Code (‘CSC’) is an embossed or printed number located on the card (but not referenced in the magnetic stripe) that is often collected in Card Not Present transaction processing.

These codes are alternatively known as Card Verification Value 2 ('CVV2') for Visa cards, Card Verification Code 2 ('CVC2') for MasterCard and Card ID ('CID') for American Express and Discover.

For MasterCard, Visa and Discover, the code is typically a separate group of three digits to the right of the signature strip. For American Express, the code is a printed, not embossed, string of four digits on the front towards the right.

SALE, FORCED SALE, AUTH only Optional
exp_date N The expiration date of the payment card – note that leading zeroes are material. For example, the value depicting an expiration date of July 2015 should be sent as ‘0715’ not ‘715’. SALE, FORCED SALE, AUTH only Required
amount N The amount of the transaction – must include a decimal place. For example, 25.00, 8.32, etc. Only US Dollars are supported today. SALE, FORCED SALE, AUTH, CAPTURE, REFUND only Required
invoice A/N An optional field that allows the user to identify and track the transaction through the use of a number or code. SALE, FORCED SALE, AUTH, CAPTURE, REFUND only Optional
authorization_code A/N An authorization code must be provided by the transaction originator in a Forced Sale transaction request. FORCED SALE only Required
purchase_order A/N Required for Level II and Level III purchasing card transactions. Allows the user to provide a unique ID per customer. The Gateway will automatically assign a unique Purchase Order number if one is not given. strong>SALE, FORCED SALE, AUTH only Optional
email A/N Customer email address, also used for customer receipts. SALE, FORCED SALE, AUTH only Optional
customer_id A/N Required for Level II and Level III purchasing card transactions. Allows the user to provide a unique ID per customer. SALE, FORCED SALE, AUTH only Optional
order_number A/N An order number required on all transactions (up to 18 positions in length, 0–9; A–Z) ALL Optional
client_ip A/N IP address from where the request originated. Used for location services and fraud module processing. ALL Optional
description A/N Text that describes the purpose of the transaction. ALL Optional
comments A/N May be used to provide additional information. ALL Optional
tip_amount N The amount of the tip that will be added to the amount of the original transaction – must include a decimal place. For example, 25.00, 8.32, etc. Only US Dollars are supported today. Only allowed if Tip Support is enabled for your account. CAPTURE, FORCED_SALE Optional
server_id N A 2-digit number, often used at restaurants, that identifies the server for the transaction. The server_id received in a CAPTURE will override what was provided in the AUTH. AUTH, CAPTURE Optional
encrypted_track_data A/N Used for card swipe transactions. Output from a card reader goes here. SALE, AUTH, FORCED_SALE Optional
track_format A/N Used for card swipe transactions. Specifies the type of card reader. Accepted values: MAGTEK SALE, AUTH, FORCED_SALE Optional but is Required for card swipe transactions
billing_is_shipping A To use information in the billing object as shipping information, include this element with the value ‘true’. SALE, FORCED SALE, AUTH Optional
billing O Contains fields that define billing information. (See Billing and Shipping Fields table) SALE, FORCED SALE, AUTH Optional
shipping O Contains fields that define shipping information [Note: Object not required if billing_is_shipping = true] (See Billing and Shipping Fields table) SALE, FORCED SALE, AUTH Optional
Billing and Shipping Fields
Name Format Description
billing [first_name] A/N First name that appears on the card
billing [last_name] A/N Last name that appears on the card
billing [company] A/N Company name
billing [street] A/N Address, first line – used for Address Verification service (’AVS’)
billing [street2] A/N AVS address, second line
billing [city] A/N City
billing [state] A/N State
billing [country] A/N Country
billing [zip] A/N AVS zip code
billing [phone] A/N Billing contact phone number
shipping [first_name] A/N First name as it should appear on the shipping label
shipping [last_name] A/N Last name as it should appear on the shipping label
shipping [company] A/N Company name as it should appear on the shipping label
shipping [street] A/N Street address as it should appear on the shipping label
shipping [street2] A/N Line 2 of the street address as it should appear on the shipping label
shipping [city] A/N City name as it should appear on the shipping label
shipping [state] A/N State as it should appear on the shipping label
shipping [zip] A/N Five or nine-digit ZIP code as it should appear on the shipping label
shipping [phone] A/N Phone number for where the goods are being shipped

Response

Name Format Description
id A/N The Secure Gateway unique transaction ID. Save for referencing in CAPTURE, REFUND, and VOID transaction types.
result A Result of transaction performed:
  • APPROVED
  • DECLINED
  • REJECTED
  • ERROR
result_code A/N Result code of transaction. See Appendix: Result Codes
display_message A/N Transaction result display message
authorization_code A/N Approval Code of a transaction when a transaction result is APPROVED
avs_result_code A/N Address Verification Service ('AVS') Result Code. See Appendix: AVS Result Codes.
csc_result_code A/N Card Security Code ('CSC') Result Code. See Appendix: CSC Result Codes.
error_code A/N Error code of transaction when a transaction result is ERROR. See Appendix: Error Codes.

Sale

A Sale transaction is used by merchants for the immediate purchase of goods or services. This transaction completes both the authorization and capture in a single transaction request. The Sale transaction is an Authorization and Capture transaction that, if approved, is automatically included for settlement.

Authorization

The Authorization transaction is used by a merchant to obtain the authorization of a transaction amount as a pre-approval for the purchase of goods or services later during the fulfillment process. Authorization transactions are submitted for authorization and then funds are held by the issuer until that transaction is captured or the authorization expires.

Example: An online retailer initiates an Authorization transaction to guarantee funding by the card issuer prior to the shipment/delivery of the goods. When shipment/delivery has been fulfilled, the retailer runs a Completion transaction.

An Authorization is also referred to as an Auth-Only or Pre-Auth transaction.

Capture

The Capture transaction will allow merchants to capture a previously authorized transaction that is pending settlement, and submit it for clearing and settlement.

Example: An online retailer initiates an Authorization transaction to reserve a customer's funds prior to shipment/delivery of the goods, and then, once fulfillment has been completed, the transaction intiates a Capture.

A Capture is also referred to as a Pre-Authorization Completion transaction or more simply as a Completion transaction.

Forced Sale

A Forced Sale is a transaction initiated by a merchant with the intent of forcing the posting of the transaction against the customer account without receiving prior authorization by the card issuer, or after receiving a voice authorization code from the merchant acquiring call center.

Example: A merchant’s terminal is offline, requiring the purchase of goods to be completed without receiving online authorization by the card issuer. Or they received a Voice Approval. In these cases the merchant would run a Forced Sale transaction with the expectation of receiving funding for the goods or services rendered.

A Forced Sale does not require a matching Authorization. Forced Sales are also known as Off-Line Sales.

Refund

A Refund allows a merchant to refund a previously settled transaction and submit the refund for processing. Matched Refunds are allowed only for financial transactions (Sale, Forced Sale and Capture) and are limited to the original authorization amount (or a lesser amount). Multiple partial refunds are allowed up to the original transaction amount. Alternatively, a merchant may run a Refund that is not matched to a financial transaction (an Unmatched Refund). An Unmatched Refund credits an account for the amount specified and is not limited by an original authorization amount.

Refunds are also sometimes referred to as a Store Credit or Return transaction.

Void

Void transactions can reverse transactions that have been previously authorized or approved by the card issuer and are pending settlement. Merchants will only be allowed to void transactions that are in an open batch (pending settlement).