List

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.

Full Fields List

Request

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.

Transaction Types

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