Token Requests

The Clearent Payment Gateway provides two ways to create tokens: 1) by submitting a Token Request Object and 2) by submitting a Transaction Request. In both cases, the body of the request can be in Extensible Markup Language (XML) or 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

Token Request

Token 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/tokens

The body of the request consists of a Token Request Object. 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 ‘Y’ indicates that the field is required to create a token.
  • A value of ‘K’ indicates that the field is required for Keyed transactions.
  • A value of ‘C’ indicates that the field is Conditionally required; see the Description for details.
  • A value of ‘M’ indicates that the field is required for Mag-Stripe transactions.
  • If no indicator is provided, the field is not required in any case.
Field Name Format Req Description
card N Y 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.

card-type A Y Supported card types are:

  • VISA
  • MASTERCARD
  • DISCOVER
  • DINERS CLUB
  • AMERICAN EXPRESS
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’.
description A/N N An optional field that includes a short description of the card.
avs-address A/N Y Address, first line – used for Address Verification Service (AVS) requests.
avs-zip A/N Y AVS ZIP code.
encrypted-track-data A/N C,M (Required for encrypted card swipe transactions.) Includes track 1/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.

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

track-format A/N C,M (Required 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).

Token Request as Part of Transaction Request

Tokens can also be created by submitting a Sale or an Authorization request to the Clearent Payment Gateway. If the transaction is approved, the information of the newly created token will be returned in the response. If the transaction is not approved, the token will not be created.

The request must be submitted by 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 for a Sale or an Authorization transaction. The body must also include additional fields required to create a token. 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 ‘Y’ indicates that the field is required to create a token.
  • A value of ‘K’ indicates that the field is required for Keyed transactions.
  • A value of ‘C’ indicates that the field is Conditionally required; see the Description for details.
  • A value of ‘M’ indicates that the field is required for Mag-Stripe transactions.
  • If no indicator is provided, the field is not required in any case.
Field Name Format Req Description
type A/N Supported Transaction Types are:

  • SALE
  • AUTH

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 Configuration and Setup for details.

card A/N (Required for 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.

card-type A Supported card types are:

  • VISA
  • MASTERCARD
  • DISCOVER
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.

exp-date MMYY 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’.
amount N 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.

encrypted-track-data A/N C,M (Required for encrypted card swipe transactions.) Includes track 1/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.

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

track-format A/N C,M (Required 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).

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.