Requests

Formats and Fields

Transaction requests are submitted to the Clearent Payment Gateway using the HTTP POST method, with a URL in the following form:

https://gateway-sb.clearent.net/rest/v2/transactions

The body of the request consists of a Transaction Request Object. The Transaction API supports both Extensible Markup Language (XML) and JavaScript Object Notation (JSON).

If you use XML, include the following in the HTTP request header:

Content-Type:application/xml

If you use JSON, include the following in the HTTP request header:

Accept:application/json

The list of required and optional fields, along with their format and meaning, is provided in the following table. Please note that the column “Req” may contain one or more values that indicate whether a field is required, and under what conditions:

  • A value of ‘A’ indicates that the field is required for all transactions.
  • A value of ‘K’ indicates that the field is required for Keyed transactions.
  • A value of ‘M’ indicates that the field is required for Mag-Stripe transactions.
  • A value of ‘C’ indicates that the field is Conditionally required; see the Description for details.
  • If no indicator is provided, the field is not required in any case.

Arguments

Field Name Format Req Description
api-key A/N C An assigned value required for authentication of transaction processing via the RESTful API. Can be provided in request body or as a header field with the same name.
software-type A/N A Name of your software application; “CoffeeHouseApp”, etc.
type A/N A Supported Transaction Types are:

  • SALE
  • FORCED SALE
  • AUTH
  • CAPTURE
  • REFUND
  • VOID

Your API key must be configured with permission to conduct the transaction type in question in order for the Gateway to accept the request. See Chapter 3, “Configuration and Setup”, for details.

id N C (Required for CAPTURE, REFUND, VOID) Used to identify the transaction to be captured, refunded or voided. In the case of a Void or Matched Refund, the value provided here must match what was returned in the original transaction response.
card A/N C,K (Required for SALE, FORCED SALE, or AUTH on Keyed transactions) Cardholder’s payment card account number, formally known as the Primary Account Number (PAN).

Do not include the ‘card’ field when sending track data; instead, see ‘Encrypted Track Data’ or ‘track2Data’ below.

csc N K 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.

exp-date MMYY K The expiration date visible on 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’.
encrypted-track-data A/N C,M (Optional for SALE, AUTH, FORCED SALE, and UNMATCHED REFUND. Required for encrypted card swipe transactions). Includes track1/2 output from magnetic stripe as captured by the card reader.

With the secure card reader set to keyboard emulation mode, place the ENTIRE contents of the raw swipe read in this field.

Only ONE of ‘encrypted-track-data’ or ‘track2-data’ should be submitted, never both.

You will get an error if you submit encrypted track 2 data.

track2-data A/N C,M (Optional for Sale, Auth, Forced Sale, and Unmatched Refund.

Required for any card swipe transaction supporting unencrypted track2 data).Includes Track 2 output from the magnetic stripe read; note that leading and trailing sentinels must be removed.

The Clearent Gateway does not support the sending of Track 1 data at this time.

track-format A/N C,M (Required for SALE, FORCED SALE, or AUTH Mag-Stripe transactions) Specifies the type of card reader. Accepted values:

  • ‘MAGTEK’ – MagTek SCRM (must be present when the ‘Encrypted Track Data’ field is present).
  • ‘TRACK2’ – Non-Encrypting Card Reader (must be present when the ‘track2Data’ field is present).
amount N C (Required for all transaction types except VOID) The amount of the transaction in US Dollars; decimal notation is required, but the currency symbol (i.e. ‘$’) should be omitted. Examples include 25.00, 8.32, etc.

Only US Dollars are supported at this time. For Capture transactions that include a tip, the amount is the original authorization amount.

sales-tax-amount N C  (Required if sales-tax-type is “LOCAL_SALES_TAX. Should NOT be set if sales-tax-type is “TAX_EXEMPT”) Supported Transaction Types are:

  • SALE
  • FORCED SALE
  • AUTH

The amount of the sales tax in US Dollars; decimal notation is required, but the currency symbol (i.e. ‘$’) should be omitted. Examples include 2.00, 1.24, etc.

Only US Dollars are supported at this time.

sales-tax-type A C (Required if sales-tax-amount is non-zero) Specifies the sales tax type. Accepted values:

  • TAX_EXEMPT
  • LOCAL_SALES_TAX
tip-amount N C (Required for CAPTURE Transactions where the Amount differs from the Authorization Amount) Supported Transaction Types are:

  • SALE
  • CAPTURE

The amount of any tip that was added to the ticket amount by the cardholder, in US Dollars; decimal notation is required, but the currency symbol (i.e. ‘$’) should be omitted. Examples include 5.00, 1.92, etc.

Only US Dollars are supported at this time.

tip-adjusted A/N C Will be 1 if a tip is adjusted and 0 if not.
invoice A/N An optional field that allows the user to identify and track the transaction through the use of a number or code.
authorization-code A/N C (Required for FORCED SALE) A six-character code provided during a Voice Authorization.
purchase-order AN C (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.
email-address A/N Customer email address, which can be used to send the customer a transaction receipt.
customer-id AN C (Required for Level II and Level III purchasing card transactions) Allows the user to provide a unique ID per customer.
order-id A/N An order number required on all transactions (up to 18 positions in length, 0–9; A–Z)

For void transaction types (i.e. reversals), the order id supplied must be the same as the one referenced in the original purchase or return.

description A/N An optional field that includes a short description of the goods or services purchased.
comments A/N An optional field that includes any additional comments associated with this transaction, or the goods or services purchased.
client-ip A/N IP address of the request originator. Used for location services and fraud module processing.
billing-is-shipping A To use information in the billing object as shipping information, include this element with the value ‘true’.
billing Object Contains fields that define billing information.
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 K Address, first line – used for Address Verification Service (AVS) requests.
billing [street2] A/N AVS address, second line.
billing [city] A/N City.
billing [state] A/N Two-letter US State Code.
billing [country] A/N Country.
billing [zip] A/N K AVS ZIP code.
billing [phone] A/N Billing contact phone number.
shipping Object Contains fields that define shipping information.

If the ‘billing-is-shipping’ field is present, and set to ‘true’ (see above), the Gateway will re-use the billing information provided, and it is therefore not necessary to submit identical information in a shipping object.

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 Two-letter US State Code as it should appear on the shipping label.
shipping[country] A/N Country.
shipping [zip] A/N Five- or nine-digit US ZIP code as it should appear on the shipping label.
shipping [phone] A/N Phone number for where the goods are being shipped.