API Introduction

The CardConnect API allows you to securely accept a wide-range of credit, debit and alternative payments. Instead of a high flat rate, we’ll cut your processing costs with interchange plus pricing. If you are interested in accessing CardConnect’s complete repository of API documentation, please contact us here. Below, you will find documentation for our REST implementation.

REST Implementation

REST Web Services utilize the HTTP Verbs GET, POST, PUT and DELETE to implement CRUD (Create / Replace / Update / Delete) functions. Unless otherwise specified PUT operations are required for each service. GET operations are used for inquiry requests, specifically the Inquire, Settlement Status, and Deposit services. The POST and DELETE Rest verbs are not utilized or implemented by CardConnect. The next section discusses the mapping of payment processes to these verbs.

This Web Service utilizes the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. JSON is a rich but lightweight data definition language, considerable simpler than XML but with similar functionality (i.e. nested data structures and arrays). Most programming languages have libraries to convert an arbitrary object to and from a JSON data transfer encoding. CardConnect provides a sample client application in the JAVA language implementing all functions described herein.

Connecting to the Server

The CardConnect REST Web Service base URL includes a protocol, host, port and servlet specification, such as:

https://url.goeshere.com:6443/cardconnect/rest

This represents an HTTPS request to host over port 6443 to the REST web service base URL. The servlet name is fixed within the application; the host and port are assigned by CardConnect. A GET or PUT request with no arguments to the address above will return a simple text/html “CardConnect REST Servlet” response if proper credentials are provided.

A username and password are required in the HTTP Authorization Header property in each web service request. Authorization type “Basic” is expected, followed by a combined “username:password” string Base64 encoded. If not provided or not correct an HTTP Exception “401:Unauthorized” is returned to the caller. An example is below:

Authorization: Basic QWxhZGluOnNlc2FtIG9wZW4=

Service Endpoints

Each service defined has an endpoint as shown in the table below. The endpoint name is appended to the base URL. Details about the REST implementation for each service follow.

Service	Resource Name
Authorization	auth
Capture	capture
Void	void
Refund	refund
Inquire	inquire
Settlement Status	settlestat
Deposit	deposit
Profile	profile
Funding	funding

CardConnect validates various parameters of an authorization request prior to sending it to a Payment Card Processor. If the request fails these checks the card processor field will contain “PPS” and the response code identifying the error.

If the request passes the CardConnect checks the Payment Processor is selected based on the merchant id in the request and forwarded. Generally a processor response code of “0” or “00” is a successful authorization request; any other code is a decline. If the request was successful the authorization code is populated, otherwise it is not present.

CardConnect provides a response status, or “respstat”, field as a simpler representation of response codes, and a response text that provides a readable description of the processor response code. An “A” response status means the authorization request was approved, a “C” means the request was declined, and a “B” means a short term error occurred and the request may be resent. This could result from either missing data or a communications error.

In the case of invalid message format or missing data, the message may be resent. However, most errors indicate a persistent problem and will require operator action to correct. Client retries should be limited in number and have a short delay between attempts.

Authorization Service

This service supports a PUT of a JSON String encoded list of the fields defined for the service. The service responds with either an HTTP Exception or a JSON encoded response.

Authorization Request

Example Authorization Request

{
  "merchid": "000000927996",
  "accttype": "VISA",
  "orderid": "AB-11-9876",
  "account": "4111111111111111",
  "expiry": "1212",
  "amount": "0",
  "currency": "USD",
  "name": "TOM JONES",
  "address": "123 MAIN STREET",
  "city": "anytown",
  "region": "NY",
  "country": "US",
  "postal": "55555",
  "ecomind": "E",
  "cvv2": "123",
  "track": null,
  "tokenize": "Y"
}

/**
* Authorize Transaction REST Example
* @return
*/
public static String authTransaction() {
  Console.WriteLine("\nAuthorization Request");

  // Create Authorization Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Card Type
  request.Add("accttype", "VI");
  // Card Number
  request.Add("account", "4444333322221111");
  // Card Expiry
  request.Add("expiry", "0914");
  // Card CCV2
  request.Add("cvv2", "776");
  // Transaction amount
  request.Add("amount", "100");
  // Transaction currency
  request.Add("currency", "USD");
  // Order ID
  request.Add("orderid", "12345");
  // Cardholder Name
  request.Add("name", "Test User");
  // Cardholder Address
  request.Add("Street", "123 Test St");
  // Cardholder City
  request.Add("city", "TestCity");
  // Cardholder State
  request.Add("region", "TestState");
  // Cardholder Country
  request.Add("country", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");
  // Return a token for this card number
  request.Add("tokenize", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JObject response = client.authorizeTransaction(request);

  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }

  return (String)response.GetValue("retref");
}

/**
 * Authorize Transaction REST Example
 * @return
 */
public static String authTransaction() {
  System.out.println("\nAuthorization Request");

  // Create Authorization Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Card Type
  request.put("accttype", "VI");
  // Card Number
  request.put("account", "4444333322221111");
  // Card Expiry
  request.put("expiry", "0914");
  // Card CCV2
  request.put("cvv2", "776");
  // Transaction amount
  request.put("amount", "100");
  // Transaction currency
  request.put("currency", "USD");
  // Order ID
  request.put("orderid", "12345");
  // Cardholder Name
  request.put("name", "Test User");
  // Cardholder Address
  request.put("Street", "123 Test St");
  // Cardholder City
  request.put("city", "TestCity");
  // Cardholder State
  request.put("region", "TestState");
  // Cardholder Country
  request.put("country", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");
  // Return a token for this card number
  request.put("tokenize", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JSONObject response = client.authorizeTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));

  return (String)response.get("retref");
}

<?php
// Authorize Transaction example
function authTransaction() {
  global $url, $user, $password;
  echo "\nAuthorization Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid'   => "496400000840",
    'accttyppe' => "VISA",
    'account'   => "4444333322221111",
    'expiry'    => "0914",
    'cvv2'      => "123",
    'amount'    => "100",
    'currency'  => "USD",
    'orderid'   => "12345",
    'name'      => "Test User",
    'street'    => "123 Test St",
    'city'      => "Testville",
    'region'    => "Test State",
    'country'   => "US",
    'postal'    => "11111",
    'tokenize'  => "Y",
  );

  $response = $client->authorizeTransaction($request);
  print var_dump($response);
  return $response["retref"];
}
?>

The value in the amount field identifies the authorization transaction type. A negative amount indicates a Refund request, a positive amount indicates an Authorization request, and an amount of “0” indicates an Account Verification request.

Field	Size	Type	Comments
merchid*	12	N	Merchant Id, required for all requests
accttype#	6	A	One of PPAL, PAID, GIFT, PDEBIT, otherwise not required.
account*#	19	N	Clear or Tokenized card number for payment card Bank account number for ECheck Masked in response
expiry*#	4	N	Card Expiration in either MMYY or YYYYMMDD format, not required for ECHK
amount*	12	N	Amount with decimal or without decimal in currency minor units (i.e. USD Pennies, EUR Cents), Positive, Negative or Zero
currency*	3	AN	USD for US dollars, CAD for Canadian Dollars, CAD Canadian Dollars, etc. Currency of merchant settlement.
name#	30	AN	Account name; CCard optional, ECheck required
address#	30	AN	Account street address (required for AVS)
city#	30	AN	Account city
region#	20	AN	US State, Mexican State, Canadian Province
country#	2	AN	Account country (2 char country code), defaults to “US” (2)
phone#	15	AN	Account phone
postal#	9	AN	Account postal code, defaults to “99999”. If country is “US”, must be 5 or 9 digits, otherwise any alphanumeric string is accepted.
email#	30	AN	E-Mail address of the account holder
ecomind	1	A	T telephone or mail, R recurring, E ecommerce/Internet
cvv2	4	N	CVV2/CVC/CID value
orderid	19	AN	Source system order number (1)
track	76	AN	Track1/track2 swipe data
bankaba#	9	N	Bank routing (ABA) number, Check only
tokenize	1	A	Optional, Y to return an account token in token response field
termid	30	AN	Terminal Device ID
capture	1	A	Optional, Y to capture the transaction for settlement if approved

* - Required for all authorization requests
# - Utilized for profile create requests and stored in the profile vault.
1 - Customers are strongly encouraged to populate this field with a unique value that can identify the sales order.
2 - Country parameter is required for all non-US addresses.

Authorization Response

Example Authorization Response

{
  "respstat": "A",
  "account": "41XXXXXXXXXX1111",
  "token": "9419786452781111",
  "retref": "343005123105",
  "amount": "111",
  "merchid": "020594000000",
  "respcode": "00",
  "resptext": "Approved",
  "avsresp": "9",
  "cvvresp": "M",
  "authcode": "046221",
  "respproc": "FNOR"
}

Field	Content	Max Len	Comments
respstat	Status	1	A - Approved B - Retry C - Declined
retref	Retrieval Reference Number	12	Unique identifying transaction number, used as merchant reference number.
account	Account Number	19	Copied from request, masked
token (if requested)	Token	19	A token that replaces the card number in capture and settlement requests if requested
amount	Amount	12	Authorized amount. Same as the request amount for most approvals. The amount remaining on the card for prepaid/gift cards if partial authorization is enabled.  Not relevant for declines.
merchid	Merchant id	12	Copied from request
respcode	Response Code	3	Alpha-numeric response code. See the tables in the PROCESSOR SPECIFIC responses. PPS – 2 Numeric FNOR – 2 Alphanumeric
resptext	Response text	32	Text description of response
respproc	Response Processor	4	PPS - CardConnect internal response FNOR - First Data North

If the Authorization request was successful the following fields are returned.

Field	Content	Max Len	Comments
avsresp	AVS response code	2	Alpha-numeric AVS response. See the tables in the PROCESSOR SPECIFIC responses.
cvvresp	CVV response code	1	See the tables in the PROCESSOR SPECIFIC RESPONSES section.
authcode	Authorization code	6	Authorization Code from the Issuer
commcard	Commercial Card Flag	1	Y if a Corporate or Purchase Card

Electronic Check

CardConnect can process electronic check transactions through those payment gateways that support it. The bankaba field in the request must contain the Routing and Transit number; the account field must contain the account number. The ecomind field is used to identify the Payment Origin. CardConnect identifies Check transactions as from individual accounts.

For processors that support ECheck account verification there are two additional fields for Checking or Savings account verification with identification requests.

Field	Size	Type	Comments
ssnl4#	4	N	Last four digits of account social security number
license#	15	N	Driver’s license state (two Characters) + : + number, For example NY:12JKHQ123

Profiles

/**
 * Authorize Transaction with Profile REST Example
 * @return
 */
public static String authTransactionWithProfile() {
  Console.WriteLine("\nAuthorization With Profile Request");

  // Create Authorization Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Card Type
  request.Add("accttype", "VI");
  // Card Number
  request.Add("account", "4444333322221111");
  // Card Expiry
  request.Add("expiry", "0914");
  // Card CCV2
  request.Add("cvv2", "776");
  // Transaction amount
  request.Add("amount", "100");
  // Transaction currency
  request.Add("currency", "USD");
  // Order ID
  request.Add("orderid", "12345");
  // Cardholder Name
  request.Add("name", "Test User");
  // Cardholder Address
  request.Add("Street", "123 Test St");
  // Cardholder City
  request.Add("city", "TestCity");
  // Cardholder State
  request.Add("region", "TestState");
  // Cardholder Country
  request.Add("country", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");
  // Return a token for this card number
  request.Add("tokenize", "Y");
  // Create Profile
  request.Add("profile", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JObject response = client.authorizeTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }

  return (String)response.GetValue("profileid");
}

/**
 * Authorize Transaction with Profile REST Example
 * @return
 */
public static String authTransactionWithProfile() {
  System.out.println("\nAuthorization With Profile Request");

  // Create Authorization Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Card Type
  request.put("accttype", "VI");
  // Card Number
  request.put("account", "4444333322221111");
  // Card Expiry
  request.put("expiry", "0914");
  // Card CCV2
  request.put("cvv2", "776");
  // Transaction amount
  request.put("amount", "100");
  // Transaction currency
  request.put("currency", "USD");
  // Order ID
  request.put("orderid", "12345");
  // Cardholder Name
  request.put("name", "Test User");
  // Cardholder Address
  request.put("Street", "123 Test St");
  // Cardholder City
  request.put("city", "TestCity");
  // Cardholder State
  request.put("region", "TestState");
  // Cardholder Country
  request.put("country", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");
  // Return a token for this card number
  request.put("tokenize", "Y");
  // Create Profile
  request.put("profile", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JSONObject response = client.authorizeTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));

  return (String)response.get("profileid");
}

<?php
// Authorize transaction with user profile example
function authTransactionWithProfile() {
  global $url, $user, $password;
  echo "\nAuthorization With Profile Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid'   => "496400000840",
    'accttyppe' => "VISA",
    'account'   => "4444333322221111",
    'expiry'    => "0914",
    'cvv2'      => "123",
    'amount'    => "100",
    'currency'  => "USD",
    'orderid'   => "12345",
    'name'      => "Test User",
    'street'    => "123 Test St",
    'city'      => "Testville",
    'region'    => "Test State",
    'country'   => "US",
    'postal'    => "11111",
    'tokenize'  => "Y",
    'profile'   => "Y",
  );

  $response = $client->authorizeTransaction($request);
  print var_dump($response);
  return $response["profileid"];
}
?>

CardConnect has the ability to store information about the account holder, called a profile. Setting the optional property profile to “Y” in the first authorization or account verification request will create a new profile using the information in the request. The profile feature requires that the account number be converted to a token. Subsequent authorization requests access the stored profile by setting the profile property to the profileid value returned in the original authorization request or profile create request. The fields stored in the profile are marked by the ‘#’ in the Authorization Request fields table.

Field	Size	Type	Comments
profile	1 or 16	AN	Optional, Y to create an account profile, 20 digit numeric profileid / optional acctid to utilize a profile

Authorization Capture

/**
 * Authorize Transaction With Capture REST Example
 * @return
 */
public static String authTransactionWithCapture() {
  Console.WriteLine("\nAuthorization With Capture Request");

  // Create Authorization Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Card Type
  request.Add("accttype", "VI");
  // Card Number
  request.Add("account", "4444333322221111");
  // Card Expiry
  request.Add("expiry", "0914");
  // Card CCV2
  request.Add("cvv2", "776");
  // Transaction amount
  request.Add("amount", "100");
  // Transaction currency
  request.Add("currency", "USD");
  // Order ID
  request.Add("orderid", "12345");
  // Cardholder Name
  request.Add("name", "Test User");
  // Cardholder Address
  request.Add("Street", "123 Test St");
  // Cardholder City
  request.Add("city", "TestCity");
  // Cardholder State
  request.Add("region", "TestState");
  // Cardholder Country
  request.Add("country", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");
  // Return a token for this card number
  request.Add("tokenize", "Y");
  // Capture auth
  request.Add("capture", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JObject response = client.authorizeTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }

  return (String)response.GetValue("retref");
}

/**
 * Authorize Transaction With Capture REST Example
 * @return
 */
public static String authTransactionWithCapture() {
  System.out.println("\nAuthorization With Capture Request");

  // Create Authorization Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Card Type
  request.put("accttype", "VI");
  // Card Number
  request.put("account", "4444333322221111");
  // Card Expiry
  request.put("expiry", "0914");
  // Card CCV2
  request.put("cvv2", "776");
  // Transaction amount
  request.put("amount", "100");
  // Transaction currency
  request.put("currency", "USD");
  // Order ID
  request.put("orderid", "12345");
  // Cardholder Name
  request.put("name", "Test User");
  // Cardholder Address
  request.put("Street", "123 Test St");
  // Cardholder City
  request.put("city", "TestCity");
  // Cardholder State
  request.put("region", "TestState");
  // Cardholder Country
  request.put("country", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");
  // Return a token for this card number
  request.put("tokenize", "Y");
  // Capture auth
  request.put("capture", "Y");

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JSONObject response = client.authorizeTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));

  return (String)response.get("retref");
}

<?php
// Authorize transaction with capture example
function authTransactionWithCapture() {
  global $url, $user, $password;
  echo "\nAuthorization With Capture Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid'   => "496400000840",
    'accttyppe' => "VISA",
    'account'   => "4444333322221111",
    'expiry'    => "0914",
    'cvv2'      => "123",
    'amount'    => "100",
    'currency'  => "USD",
    'orderid'   => "12345",
    'name'      => "Test User",
    'street'    => "123 Test St",
    'city'      => "Testville",
    'region'    => "Test State",
    'country'   => "US",
    'postal'    => "11111",
    'tokenize'  => "Y",
    'capture'   => "Y",
  );

  $response = $client->authorizeTransaction($request);
  print var_dump($response);
  return $response["retref"];
}
?>

Accounts Receivable transactions may want to Authorize and Capture and provide line item detail all in a single request. CardConnect supports an optional items field in the authorization request to support this feature. The capture flag must be set to “Y”, and if the authorization request is successful the transaction and associated line items are automatically captured for settlement.

All fields defined in the Capture Service section may be sent in the Authorization request. They are only processed if the capture flag is set. Please refer to the Capture request, Level 2 and Level 3 data features for more information.

User Fields

Example User Fields

"userfields": [
  {
    "name0": "value0"
  },
  {
    "name1": "value1"
  }
]

/**
* Authorize Transaction with User Fields REST Example
* @return
*/
public static String authTransactionWithUserFields() {
  Console.WriteLine("\nAuthorization With User Fields Request");

  // Create Authorization Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Card Type
  request.Add("accttype", "VI");
  // Card Number
  request.Add("account", "4444333322221111");
  // Card Expiry
  request.Add("expiry", "0914");
  // Card CCV2
  request.Add("cvv2", "776");
  // Transaction amount
  request.Add("amount", "100");
  // Transaction currency
  request.Add("currency", "USD");
  // Order ID
  request.Add("orderid", "12345");
  // Cardholder Name
  request.Add("name", "Test User");
  // Cardholder Address
  request.Add("Street", "123 Test St");
  // Cardholder City
  request.Add("city", "TestCity");
  // Cardholder State
  request.Add("region", "TestState");
  // Cardholder Country
  request.Add("country", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");
  // Return a token for this card number
  request.Add("tokenize", "Y");

  // Create user fields
  JArray fields = new JArray();
  JObject field = new JObject();
  field.Add("Field1", "Value1");
  fields.Add(field);
  request.Add("userfields", fields);

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JObject response = client.authorizeTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }

  return (String)response.GetValue("retref");
}

/**
 * Authorize Transaction with User Fields REST Example
 * @return
 */
public static String authTransactionWithUserFields() {
  System.out.println("\nAuthorization With User Fields Request");

  // Create Authorization Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Card Type
  request.put("accttype", "VI");
  // Card Number
  request.put("account", "4444333322221111");
  // Card Expiry
  request.put("expiry", "0914");
  // Card CCV2
  request.put("cvv2", "776");
  // Transaction amount
  request.put("amount", "100");
  // Transaction currency
  request.put("currency", "USD");
  // Order ID
  request.put("orderid", "12345");
  // Cardholder Name
  request.put("name", "Test User");
  // Cardholder Address
  request.put("Street", "123 Test St");
  // Cardholder City
  request.put("city", "TestCity");
  // Cardholder State
  request.put("region", "TestState");
  // Cardholder Country
  request.put("country", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");
  // Return a token for this card number
  request.put("tokenize", "Y");

  // Create user fields
  JSONArray fields = new JSONArray();
  JSONObject field = new JSONObject();
  field.put("Field1", "Value1");
  fields.add(field);
  request.put("userfields", fields);

  // Create the REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an AuthTransaction request
  JSONObject response = client.authorizeTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));

  return (String)response.get("retref");
}

<?php
// Authorize transaction with user fields example
function authTransactionWithUserFields() {
  global $url, $user, $password;
  echo "\nAuthorization With User Fields Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid'   => "496400000840",
    'accttyppe' => "VISA",
    'account'   => "4444333322221111",
    'expiry'    => "0914",
    'cvv2'      => "123",
    'amount'    => "100",
    'currency'  => "USD",
    'orderid'   => "12345",
    'name'      => "Test User",
    'street'    => "123 Test St",
    'city'      => "Testville",
    'region'    => "Test State",
    'country'   => "US",
    'postal'    => "11111",
    'tokenize'  => "Y",
  );

  // Create user fields
  $field = array("Field1" => "Value1");
  $fields = array($field);
  $authdata["userfields"] = $fields;

  $response = $client->authorizeTransaction($request);
  print var_dump($response);
}
?>

Some merchants may wish to include additional data with the authorization for future retrieval. This is provided through the use of an optional “userfields” property in the Authorization Request. The value of the userfields object is a series of name-value pairs that are meaningful to the merchant. The name and value field may be any String value. The only restriction is a total length of user defined fields plus JSON encoding is 4000 bytes.

Field	Size	Type	Comments
userfields		Object	Optional, a series of name/value pairs

UserField Entry

Field	Size	Type	Comments
name	Any	AN	The name of the field
value	Any	AN	The value of the field

Each UserField entry is a name/value pair.

Custom Descriptor Fields

CardConnect offers customers the ability to provide custom identifying information about a merchant, e.g. business name, phone number, city and/or state, which appears on buyers’ credit/debit card statements. See your sales person for feature availability and merchant configuration. Once configured add UserField entries for each piece of custom data to be replaced.

Field	Size	Type	Comments
custommerchant	12	AN	Merchant name field
customproduct	12	AN	Product name field
customstate	2	A	2 digit state abbreviation
customphone	10	N	Format must be ##########
custompostal	5	N	5 digit postal

Card Present

CardConnect supports card present transactions if “track” data is provided from the magnetic stripe. In this case the AVS (Address Verification Fields) and the CVV2 are not required. Populate the “track” field with Track1 if it is available, otherwise Track 2. The “sentinel” characters are required for each format.

3D Secure

CardConnect supports 3DSecure processing. After verification is done with a 3DS provider the following values can be passed with the authorization request to qualify the merchant for reduced interchange rate and charge back mitigation.

Field	Size	Type	Comments
secureflag	Any	AN	ECI Flag for 3DS processing
securevalue	Any	AN	ECI Value returned from 3DS authentication
securexid	Any	AN	XID Value

Capture Service

The URL for the CardConnect REST Capture service is:

https://<hostname>:<port>/cardconnect/rest/capture

The service requires a JSON encoded structure.

A JSON response containing the response fields is returned if no errors. An HTTP response code 400 (Bad Method) is returned if the request is unreadable, and an HTTP response code 500 is returned if an exception occurs.

Capture Request

Example Capture Request

{
  "retref": "288002073633",
  "shiptozip": "11111-1111",
  "shipfromzip": "99999-9999",
  "amount": "596.00",
  "items": [
    {
      "discamnt": "0",
      "unitcost": "900",
      "uom": "CS",
      "lineno": "1",
      "description": "DESCRIPTION-1",
      "taxamnt": "117",
      "quantity": "1000",
      "upc": "UPC-1",
      "netamnt": "150",
      "material": "MATERIAL-1"
    },
    {
      "discamnt": "0",
      "unitcost": "450",
      "uom": "CS",
      "lineno": "2",
      "description": "DESCRIPTION-2",
      "taxamnt": "117",
      "quantity": "2000",
      "upc": "UPC-1",
      "netamnt": "300",
      "material": "MATERIAL-2"
    }
  ],
  "taxamount": "40.00",
  "merchid": "000000927996",
  "account": "4111111111111111",
  "ponumber": "PO-0736332"
}

/**
 * Capture Transaction REST Example
 * @param retref
 */
public static void captureTransaction(String retref) {
  Console.WriteLine("\nCapture Transaction Request");

  // Create Authorization Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Transaction amount
  request.Add("amount", "100");
  // Transaction currency
  request.Add("currency", "USD");
  // Order ID
  request.Add("retref", retref);
  // Purchase Order Number
  request.Add("ponumber", "12345");
  // Tax Amount
  request.Add("taxamnt", "007");
  // Ship From ZipCode
  request.Add("shipfromzip", "11111");
  // Ship To Zip
  request.Add("shiptozip", "11111");
  // Ship to County
  request.Add("shiptocountry", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");

  // Line item details
  JArray items = new JArray();
  // Singe line item
  JObject item = new JObject();
  item.Add("lineno", "1");
  item.Add("material", "12345");
  item.Add("description", "Item Description");
  item.Add("upc", "0001122334455");
  item.Add("quantity", "5");
  item.Add("uom", "each");
  item.Add("unitcost", "020");
  items.Add(item);
  // Add items to request
  request.Add("items", items);

  // Authorization Code from auth response
  request.Add("authcode", "0001234");
  // Invoice ID
  request.Add("invoiceid", "0123456789");
  // Order Date
  request.Add("orderdate", "20140131");
  // Total Order Freight Amount
  request.Add("frtamnt", "1");
  // Total Duty Amount
  request.Add("dutyamnt", "1");

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send a captureTransaction request
  JObject response = client.captureTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }
}

/**
 * Capture Transaction REST Example
 * @param retref
 */
public static void captureTransaction(String retref) {
  System.out.println("\nCapture Transaction Request");

  // Create Authorization Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Transaction amount
  request.put("amount", "100");
  // Transaction currency
  request.put("currency", "USD");
  // Order ID
  request.put("retref", retref);
  // Purchase Order Number
  request.put("ponumber", "12345");
  // Tax Amount
  request.put("taxamnt", "007");
  // Ship From ZipCode
  request.put("shipfromzip", "11111");
  // Ship To Zip
  request.put("shiptozip", "11111");
  // Ship to County
  request.put("shiptocountry", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");

  // Line item details
  JSONArray items = new JSONArray();
  // Singe line item
  JSONObject item = new JSONObject();
  item.put("lineno", "1");
  item.put("material", "12345");
  item.put("description", "Item Description");
  item.put("upc", "0001122334455");
  item.put("quantity", "5");
  item.put("uom", "each");
  item.put("unitcost", "020");
  items.add(item);
  // Add items to request
  request.put("items", items);

  // Authorization Code from auth response
  request.put("authcode", "0001234");
  // Invoice ID
  request.put("invoiceid", "0123456789");
  // Order Date
  request.put("orderdate", "20140131");
  // Total Order Freight Amount
  request.put("frtamnt", "1");
  // Total Duty Amount
  request.put("dutyamnt", "1");

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send a captureTransaction request
  JSONObject response = client.captureTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));
}

<?php
// Capture transaction example
function captureTransaction($retref) {
  global $url, $user, $password;
  echo "\nCapture Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid' => "496400000840",
    'amount' => "100",
    'currency' => "USD",
    'retref' => $retref,
    'ponumber' => "12345",
    'taxamnt' => "007",
    'shipfromzip' => "11111",
    'shiptozip' => "11111",
    'shiptocountry' => "US",
    'postal' => "11111",
    'authcode' => "0001234",
    'invoiceid' => "0123456789",
    'orderdate' => "20140131",
    'frtamnt' => "1",
    'dutyamnt' => "1",
  );

  // Line item details
  // Singe line item
  $item = array (
    'lineno' => "1",
    'material' => "12345",
    'description' => "Item Description",
    'upc' => "0001122334455",
    'quantity' => "5",
    'uom' => "each",
    'unitcost' => "020"
  );
  $items = array($item);

  $request["items"] = $items;

  $response = $client->captureTransaction($request);
  print var_dump($response);
}
?>

The capture request leverages the information already stored in CardConnect by utilizing the Retrieval Reference and Authorization Code from the original request. When the amount is omitted the original authorization amount is captured.

Field	Size	Type	Comments
merchid*	12	N	Merchant Id, required for all requests must match merchid of transaction to be captured.
retref*	12	N	CardConnect Retrieval Reference Number from Authorization
authcode	6	AN	Authorization Code from original Authorization
amount	12	N	Capture Amount in decimal or in currency minor units (i.e. USD Pennies, MXN Centavos)
invoiceid	12	AN	Invoice Id, optional, defaults to Order Id from Auth

For Voice/Capture-Only exclude retref and include valid authcode.

Capture Response

Example Capture Response

{
  "amount": "596.00",
  "setlstat": "Pending",
  "retref": "288002073633",
  "merchid": "000000927996",
  "account": "41XXXXXXXXXX4113"
}

Field	Content	Max Len	Comments
merchid	Merchant Id	12	Copied from the Capture Request
account	Account Number Masked	19	Masked Account Number
amount	Amount to Capture	12	Amount echoed from Capture Request
retref	Retrieval Reference Number	12	Copied from the Capture Request
setlstat	Settlement Status	8	One of the values below: Txn not found – The Retref was not found Authorized – Auth only, not captured Queued for Capture – Queued for the Processor Zero Amount – Capture (and Auth) were Voided Accepted – Accepted by the Processor Rejected – Rejected by the Processor

Capture Level 2 Data

If available the Level 2 fields can be provided on the capture request, and should be provided for any corporate or purchase cards to qualify for improved interchange rates.

Field	Size	Type	Comments
ponumber*	12	AN	Customer Purchase Order Number
taxamnt	12	N	Tax Amount either decimal or in currency minor units (i.e. USD Pennies, MXN Centavos), taxamnt=0 indicates tax-exempt purchaser

Many Level 2 protocols refer to a “Customer Code” Field. This is further described as “an identifier the customer would recognize”. CardConnect populates this field with the Purchase Order number if specified above, otherwise with the orderid from the Authorization Request, otherwise with the CardConnect Assigned retref (Retrieval Reference) number.

The Level 2 protocol also requires certain fields about the merchant, such as Postal Code and Tax Identification Number. These fields are filled from the configuration table created during the merchant boarding process.

Capture Level 3 Data

If available Level 3 line item data can be sent with the capture request, particularly for any commercial or corporate payment cards. To qualify for Level 3 Interchange rates Level 2 data (described above) must also be provided.

Level 3 data includes additional “Order Level” items such as freight and discount amount, as well as information from each line item of the order, stored as an array in the items field.

Field	Size	Type	Comments
frtamnt	12	N	Total order freight amount, default 0
dutyamnt	12	N	Total order duty amount, default 0
orderdate	8	N	YYYYMMDD, For most industries this is the delivery date for the order, defaults to System Date when captured
shiptozip	9	AN	if country is “US”, must be 5 or 9 digits, otherwise any alphanumeric string is accepted
shipfromzip	9	AN	Same as above
shiptocountry	2	A	Ship To Country Code, default is US
Items		Array	Array of Items

Line Item Records

Field	Size	Type	Comments
lineno	4	N	Order Line Number
material	16	AN	Material Number (AKA Visa Commodity Code)
description	32	AN	Material Description
upc	14	N	Material UPC Code
quantity	12	N	Quantity of material purchased, decimal or whole units
uom	8	AN	Unit of Measure such as Quart, Ton, Each
unitcost	12	N	Amount with decimal or in Currency minor units
netamnt	12	N	Amount with decimal or in Currency minor units
taxamnt	12	N	Amount with decimal or in Currency minor units
discamnt	12	N	Amount with decimal or in Currency minor units

Void Service

A Capture Void is used to cancel a previous Capture request and to completely reverse the associated authorization. Once captured, authorizations cannot be partially reversed. Where appropriate CardConnect automatically generates partial reversals during the settlement process to align the authorization and capture amounts to eliminate misuse fees.

The response to a Void request is the same Capture Response as defined above. A successful Void request will return an authcode field of “REVERS”. The other statuses represent the reason why the Void request failed.

For a partial void or reversal merchid id and retref are required. The amount sent is the amount to be voided, or the amount to reduce the original authorized amount. A zero or omitted amount is a full reversal.

If the transaction is found, the response values will contain the result from the void request to the Clearing House. If the transaction is not found or an error occurs, the Response Processor will contain “PPS”, the Response Code will contain an error code, the Response Status will contain “C” and the Response Text will contain a relevant text message.

Void Request

Example Void Request

{
  "retref": "288013185633",
  "merchid": "000000927996",
  "amount": "101"
}

/**
 * Void Transaction REST Example
 * @param retref
 */
public static void voidTransaction(String retref) {
  Console.WriteLine("\nVoid Transaction Request");

  // Create Update Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Transaction amount
  request.Add("amount", "0");
  // Transaction currency
  request.Add("currency", "USD");
  // Return Reference code from authorization request
  request.Add("retref", retref);

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send a voidTransaction request
  JObject response = client.voidTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }
}

/**
 * Void Transaction REST Example
 * @param retref
 */
public static void voidTransaction(String retref) {
  System.out.println("\nVoid Transaction Request");

  // Create Update Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Transaction amount
  request.put("amount", "0");
  // Transaction currency
  request.put("currency", "USD");
  // Return Reference code from authorization request
  request.put("retref", retref);

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send a voidTransaction request
  JSONObject response = client.voidTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));
}

<?php
// Void transaction example
function voidTransaction($retref) {
  global $url, $user, $password;
  echo "\nVoid Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid' => "496400000840",
    'amount' => "0",
    'currency' => "USD",
    'retref' => $retref,
  );

  $response = $client->voidTransaction($request);
  print var_dump($response);
}
?>

Field	Size	Type	Comments
merchid*	12	N	Merchant Id, required for all requests must match merchid of transaction to be voided.
amount	12	N	Void Amount with decimal or Void Amount without decimal in currency minor units (i.e. USD Pennies, MXN Centavos), Positive or Zero. Use for partial voids.
retref*	12	N	Retrieval Reference Number from original Authorization

* Required

Void Response

Example Void Response

{
  "amount": "1.01",
  "resptext": "Approval",
  "authcode": "REVERS",
  "respcode": "00",
  "retref": "288013185633",
  "merchid": "000000927996",
  "cvvresp": "P",
  "account": "41XXXXXXXXXX4113",
  "avsresp": " ",
  "respproc": "FNOR",
  "respstat": "A"
}

Field	Content	Max Len	Comments
merchid	Merchant Id	12	Copied from Request
amount	Amount	12	Copied from Request, contains the replacement amount
currency	Currency	3	From original transaction
retref	Retrieval Reference Number	12	Copied from Request
authcode	Authorization code	6	“REVERS” on success
respcode	Response Code	3	Response Code
respproc	Response Processor	4	Response Processor
respstat	Response Status	1	Response Status
resptext	Capture Status	40	Response Text

Refund Service

The URL for the CardConnect REST Refund function is:

https://<hostname>:<port>/cardconnect/rest/refund

The Refund service is used for a “Refund with Reference” transaction, where some or the entire amount of a previously authorized and captured transaction is to be refunded to the card holder. The amount field is the amount to be refunded. Refund requests are automatically captured. If no amount is supplied a refund for the full original amount is issued.

Refund Request

Example Refund Request

{
  "retref": "288009185241",
  "merchid": "000000927996",
  "amount": "59.60"
}

/**
 * Refund Transaction REST Example
 * @param retref
 */
public static void refundTransaction(String retref) {
  Console.WriteLine("\nRefund Transaction Request");

  // Create Update Transaction request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Transaction amount
  request.Add("amount","-100");
  // Transaction currency
  request.Add("currency", "USD");
  // Return Reference code from authorization request
  request.Add("retref", retref);

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an refundTransaction request
  JObject response = client.refundTransaction(request);

  // Handle response
  foreach (var x in response) {
    String key = x.Key;
    JToken value = x.Value;
    Console.WriteLine(key + ": " + value.ToString());
  }
}

/**
 * Refund Transaction REST Example
 * @param retref
 */
public static void refundTransaction(String retref) {
  System.out.println("\nRefund Transaction Request");

  // Create Update Transaction request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Transaction amount
  request.put("amount","-100");
  // Transaction currency
  request.put("currency", "USD");
  // Return Reference code from authorization request
  request.put("retref", retref);

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an refundTransaction request
  JSONObject response = client.refundTransaction(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));
}

<?php
// Refund Service example
function refundTransaction($retref) {
  global $url, $user, $password;
  echo "\nRefund Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $request = array(
    'merchid' => "496400000840",
    'amount' => "0",
    'currency' => "USD",
    'retref' => $retref,
  );

  $response = $client->refundTransaction($request);
  print var_dump($response);
}
?>

Field	Size	Type	Comments
merchid*	12	N	Merchant Id, required for all requests
amount	12	N	Positive amount with decimal or amount without decimal in currency minor units (i.e. USD Pennies, MXN Centavos). Use for partial refunds
retref*	12	N	Retrieval Reference Number from original authorization

Refund Response

Example Refund Response

{
  "amount": "59.60",
  "resptext": "Approval",
  "authcode": "REFUND",
  "respcode": "00",
  "retref": "288010185242",
  "merchid": "000000927996",
  "cvvresp": "M",
  "account": "41XXXXXXXXXX4113",
  "avsresp": "Z",
  "respproc": "PPS",
  "respstat": "A"
}

If the transaction is found, the response values will contain the result from the refund request to the Clearing House. If the transaction is not found or an error occurs, the Response Processor will contain “PPS”, the Response Code will contain an error code, the Response Status will contain “C” and the Response Text will describe the error. Refunds are automatically approved by CardConnect and submitted in the settlement.

Field	Content	Max Len	Comments
merchid	Merchant Id	12	Copied from Request
amount	Amount	12	Copied from Request, contains the refund amount
retref	Retrieval Reference Number	12	New retref of refund transaction
respcode	Response Code	3	Response Code
respproc	Response Processor	4	Response Processor
respstat	Response Status	1	Response Status
resptext	Capture Status	40	Response Text

Inquire Service

/**
 * Inquire Transaction REST Example
 * @param retref
 */
public static void inquireTransaction(String retref) {
  Console.WriteLine("\nInquire Transaction Request");
  String merchid = "496400000840";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an inquire Transaction request
  JObject response = client.inquireTransaction(merchid, retref);

  // Handle response
  if (response != null) {
    foreach (var x in response) {
      String key = x.Key;
      JToken value = x.Value;
      Console.WriteLine(key + ": " + value.ToString());
    }
  }
}

/**
 * Inquire Transaction REST Example
 * @param retref
 */
public static void inquireTransaction(String retref) {
  System.out.println("\nInquire Transaction Request");
  String merchid = "496400000840";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Send an inquire Transaction request
  JSONObject response = client.inquireTransaction(merchid, retref);

  // Handle response
  if (response != null) {
    Set<String> keys = response.keySet();
    for (String key : keys) 
      System.out.println(key + ": " + response.get(key));
  }
}

<?php
// Inquire Service example
function inquireTransaction($retref) {
  global $url, $user, $password;
  echo "\nInquire Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";

  $response = $client->inquireTransaction($merchid, $retref);
  print var_dump($response);
}
?>

CardConnect provides an Inquire Service returning the Authorization and Capture status of the transaction identified by the Retrieval Reference Number provided and the Merchants ID.

The URL for the CardConnect REST Inquire service with path parameters is:

https://<hostname>:<port>/cardconnect/rest/inquire/<retref>/<merchid>

The REST verb GET is used for this service, which returns an authorization response.

If the transaction is found, the response values will contain the response fields returned on the original authorization. If the transaction is not found or an error occurs, the Response Processor will contain “PPS”, the Response Code will contain an error number, the Response Status will contain “C” and the Response Text will contain a relevant text message.

Inquire Response

Example Inquire Response

{
  "amount": "596.00",
  "resptext": "Approval",
  "setlstat": "NOTCAPTURED",
  "authcode": "PPS272",
  "respcode": "00",
  "retref": "288015190411",
  "merchid": "000000927996",
  "cvvresp": "M",
  "account": "41XXXXXXXXXX4113",
  "avsresp": "Z",
  "respproc": "FNOR",
  "respstat": "A"
}

Field	Content	Max Len	Comments
merchid	Merchant Id	12	Copied from Request
account	Account Number	25	Masked from original Transaction
amount	Amount to Capture	12	From original transaction
currency	Currency of Amount	3	From original transaction
retref	Retrieval Reference Number	12	Copied from Request
respcode	Response Code	4	From original response
respproc	Response Processor	4	From original response
respstat	Response Status	1	From original response
resptext	Capture Status	40	From original response
setlstat	Settlement Status	40	Values are: Authorized – Txn has not been Captured Queued for Capture – Txn is in flight to Clearing House Accepted – Txn was accepted for Settlement Rejected – Txn was not accepted Zero Amount – Txn was $0 Voided – Txn has been voided Declined – Txn had an error

Settlement Status Service

/**
 * Settlement Status REST Example
 */
public static void settlementStatusTransaction() {
  Console.WriteLine("\nSettlement Status Transaction Request");
  // Merchant ID
  String merchid = "496400000840";
  String date = "0401";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JArray responses = client.settlementStatus(merchid, date);
  //JSONArray responses = client.settlementStatus(null, null);

  // Handle response
  if (responses != null) {
    foreach (JObject response in responses) { 
      foreach (var x in response) {
        String key = x.Key;
        JToken value = x.Value;
        if ("txns".Equals(key)) {
          Console.WriteLine("transactions: ");
          foreach (JObject txn in value) {
            Console.WriteLine("  ===");
            foreach (var t in txn) {
              String tkey = t.Key;
              JToken tvalue = t.Value;
              Console.WriteLine("  " + tkey + ": " + tvalue.ToString());
            }
          }
        } else {
          Console.WriteLine(key + ": " + response.GetValue(key));
        }
      }
    }
  }
}

/**
 * Settlement Status REST Example
 */
public static void settlementStatusTransaction() {
  System.out.println("\nSettlement Status Transaction Request");
  // Merchant ID
  String merchid = "496400000840";
  String date = "0404";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JSONArray responses = client.settlementStatus(merchid, date);
  //JSONArray responses = client.settlementStatus(null, null);

  // Handle response
  if (responses != null) {
    for (int i=0; i<responses.size(); i++) {
      JSONObject response = (JSONObject)responses.get(i);
      Set<String> keys = response.keySet();
      for (String key : keys) {
        if ("txns".equals(key)) {
          System.out.println("transactions: ");
          JSONArray txns = (JSONArray) response.get(key);
          for (int j=0; j<txns.size(); j++) {
            System.out.println("  ===");
            JSONObject txn = (JSONObject)txns.get(j);
            Set<String> txnkeys = txn.keySet();
            for (String txnkey : txnkeys) 
              System.out.println("  " + txnkey + ": " + txn.get(txnkey));
          }
        } else {
          System.out.println(key + ": " + response.get(key));
        }
      }
    }
  }
}

<?php
// Settlement Status example
function settlementStatusTransaction() {
  global $url, $user, $password;
  echo "\nSettlement Status Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";
  $date = "0401";

  $response = $client->settlementStatus($merchid, $date);
  print var_dump($response);
}
?>

The URL for the CardConnect REST Settlement Status service is:

https://<hostname>:<port>/cardconnect/rest/settlestat?merchid=<merchid>&date=<date>

Using the GET HTTP verb where <merchid> is the merchant ID and <date> is the date in MMDD format of the transactions to retrieve.

The Settlement Status service provides a number of options for retrieving information about settlement batches. A request to the service with a merchant id and date will return an array of settlement status responses (defined below) for all batches from the specified date. This is designed to be called a few hours after the last capture of a business day has been sent so as to update the source system with the results. CardConnect generally receives a per transaction response from the Clearinghouse for each transaction whether it has been accepted or rejected for inclusion in the nightly submission to the card brands.

A request returns an array of settlement batch responses; each batch contains an array of txns containing the settlement status of each transaction. An array containing a single batch and its transactions is shown below.

Other query options to the Settlement Status service include batchid which restricts the return to only settlements in the specified batch. An empty array indicates no matches were found.

Settlement Response

Example Settlement Status Response

[
  {
    "txns": [
      {
        "setlstat": "N",
        "retref": "179001161341"
      },
      {
        "setlstat": "Y",
        "retref": "179002161341"
      }
    ],
    "batchid": "71742042",
    "hoststat": "GB",
    "hostbatch": "71742041"
  }
]

Field	Content	Max Len	Comments
batchid	Batch Id	12	Copied from the Capture Request
hoststat	Settlement Status	2	One of the values below: Blank – Queued for the Processor GB – Accepted by the Processor MB – Some Txns Accepted/Some Rejected BB – Rejected by the Processor
hostbatch	Host Batch Id	16	Clearinghouse assigned batch identifier
merchid	Merchant Id	12	Merchant ID
respproc	Clearing House	4	CardConnect abbreviation for Clearing House
txns	Array of Transactions		Array of retref / Status pairs that indicate which items were Rejected

Each transaction response in the “txns” array contains the fields shown below.

Field	Content	Max Len	Comments
retref	Retrieval Reference Number	12	Merchant reference number assigned at Authorization
setlstat	Settlement Status	1	Y - Accepted N - Rejected for clearing

Deposit Service

/** 
 * Deposit Transaction REST Example
 */
public static void depositTransaction() {
  Console.WriteLine("\nDeposit Transaction Request");
  // Merchant ID
  String merchid = "496400000840";
  // Date
  String date = "20140131";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JObject response = client.depositStatus(merchid, date);

  // Handle response
  if (response != null) {
    foreach (var x in response) {
      String key = x.Key;
      JToken value = x.Value;
      if ("txns".Equals(key)) {
        Console.WriteLine("transactions: ");
        foreach (JObject txn in value) {
          Console.WriteLine("  ===");
          foreach (var t in txn) {
            String tkey = t.Key;
            JToken tvalue = t.Value;
            Console.WriteLine("  " + tkey + ": " + tvalue.ToString());
          }
        }
      } else {
        Console.WriteLine(key + ": " + response.GetValue(key));
      }
    }
  }
}

/** 
 * Deposit Transaction REST Example
 */
public static void depositTransaction() {
  System.out.println("\nDeposit Transaction Request");
  // Merchant ID
  String merchid = "496400000840";
  // Date
  String date = "20140131";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JSONObject response = client.depositStatus(merchid, date);

  // Handle response
  if (response != null) {
    Set<String> keys = response.keySet();
    for (String key : keys) {
      if ("txns".equals(key)) {
        System.out.println("transactions: ");
        JSONArray txns = (JSONArray) response.get(key);
        for (int i=0; i<txns.size(); i++) {
          System.out.println("  ===");
          JSONObject txn = (JSONObject)txns.get(i);
          Set<String> txnkeys = txn.keySet();
          for (String txnkey : txnkeys) 
            System.out.println("  " + txnkey + ": " + txn.get(txnkey));
        }
      } else {
        System.out.println(key + ": " + response.get(key));
      }
    }
  }
}

<?php
// Deposit Status example
function depositStatusTransaction() {
  global $url, $user, $password;
  echo "\nDeposit Transaction Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";
  $date = "0401";

  $response = $client->depositStatus($merchid, $date);
  print var_dump($response);
}
?>

The URL for the CardConnect REST Deposit service is:

https://<hostname>:<port>/cardconnect/rest/deposit?merch=<merchid>&date=<date>

Using the GET HTTP verb where <merchid> is the merchant ID and <date> is the date in MMDD format.

Each day, for payment card clearinghouses’ that provide it, CardConnect polls for information regarding the ACH deposit transactions issued by the clearinghouse on behalf of the merchant, typically one deposit per card brand with transactions. If information about the transactions comprising the deposit is available, these are included in an array of “items” on the deposit response.

The deposit service tracks whether a deposit has been queried by the merchant systems. A request to the deposit service with no parameters is a request for all deposits received since the last request. This is designed to support a daily process (usually morning) that retrieves the deposits from the prior nights ACH transactions. Typically a merchant supports multiple card brands, so an array of card deposits is returned each containing an array of transaction details. An empty response body means no new deposits are available for retrieval, thus calling the service until and empty batch is returned ensures all deposits have been received.

The service can also be queried by Merchant Id and Date, returning all matching deposits in an array of Deposit records each with an array of transaction detail records.

Deposit Response

Example Deposit Response

[
  {
    "cardtype": "VI",
    "postdate": "20121009",
    "cbakamnt": "0.00",
    "feeamnt": "0.55",
    "currency": "USD",
    "amount": "11.00",
    "txns": [
      {
        "merchbatch": 92821429,
        "retref": "282005142924",
        "hostbatch": "1429",
        "feeamnt": "0.00",
        "action": "DEB",
        "depamnt": "11.00"
      }
    ],
    "resptext": "",
    "depositid": 7,
    "merchid": "000000927996",
    "action": "DEB",
    "actdate": "20121008",
    "cardproc": "FNOR"
  },
  {
    "cardtype": "MC",
    "postdate": "20121009",
    "cbakamnt": "0.00",
    "feeamnt": "0.55",
    "currency": "USD",
    "amount": "11.00",
    "txns": [
      {
        "merchbatch": 92821429,
        "retref": "282006142924",
        "hostbatch": "1429",
        "feeamnt": "0.00",
        "action": "DEB",
        "depamnt": "11.00"
      }
    ],
    "resptext": "",
    "depositid": 7,
    "merchid": "000000927996",
    "action": "DEB",
    "actdate": "20121008",
    "cardproc": "FNOR"
  }
]

Field	Content	Max Len	Comments
depositid	Deposit Id	12	CardConnect Deposit Identifierd by Merchant Id and Date an array of card deposits are returned each containing an array of trans
merchid	Merchant Id	12	Copied from Request
respproc	Card Processor Code	4	CardConnect Card Processor identifier
accttype	Card Brand	6	Vi, MC, AX, DI
action	Deposit or Refund	8	Deposit to Merchant or Refund from Merchant
actdate	Activity Date	8	Settlement Date (YYYYMMDD)
postdate	Posting Date	8	Posting Date (YYYYMMDD)
currency	Currency	3	Currency of Deposit
amount	Net Amount	12	Net amount of the ACH Transaction
feeamnt	Fee Amount	12	Fee amount deducted from deposit
cbakamnt	ChargeBack amount	12	ChargeBack amount deducted from deposit
resptext	Capture Status	40	Response Text if any provided
txns	Array		Array of Transaction Details

For each Transaction in the “txns” array the detail fields shown below are returned.

Field	Content	Max Len	Comments
retref	Retrieval Reference Number	12	Retrieval Reference Number of the Transaction for this deposit detail
action	Deposit or Refund	8	Deposit to Merchant or Refund from Merchant
depamnt	Amount	12	Amount for this transaction
feeamnt	Fee Amount	12	Fees charged for this transaction
status	Status	1	Y success, N Txn was rejected
hostbatch	Host Batch Id	16	Processor Batch Id
merchbatch	Merchant Batch Id	12	CardConnect Batch Identifier

Funding Service

/** 
 * Funding Transaction REST Example
 */
public static void fundingRequest() {
  Console.WriteLine("\Funding Transaction Request");
  // Merchant ID
  String merchid = "496400000840";
  // Date
  String date = "0131";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JObject response = client.fundingRequest(merchid, date);

  // Handle response
  if (response != null) {
    foreach (var x in response) {
      String key = x.Key;
      JToken value = x.Value;
      if ("txns".Equals(key)) {
        Console.WriteLine("transactions: ");
        foreach (JObject txn in value) {
          Console.WriteLine("  ===");
          foreach (var t in txn) {
            String tkey = t.Key;
            JToken tvalue = t.Value;
            Console.WriteLine("  " + tkey + ": " + tvalue.ToString());
          }
        }
      } else {
        Console.WriteLine(key + ": " + response.GetValue(key));
      }
    }
  }
}

/** 
 * Funding Request REST Example
 */
public static void fundingRequest() {
  System.out.println("\nFunding Request");
  // Merchant ID
  String merchid = "496400000840";
  // Date
  String date = "0131";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  JSONObject response = client.fundingRequest(merchid, date);

  // Handle response
  if (response != null) {
    Set<String> keys = response.keySet();
    for (String key : keys) {
      if ("txns".equals(key)) {
        System.out.println("transactions: ");
        JSONArray txns = (JSONArray) response.get(key);
        for (int i=0; i<txns.size(); i++) {
          System.out.println("  ===");
          JSONObject txn = (JSONObject)txns.get(i);
          Set<String> txnkeys = txn.keySet();
          for (String txnkey : txnkeys) 
            System.out.println("  " + txnkey + ": " + txn.get(txnkey));
        }
      } else {
        System.out.println(key + ": " + response.get(key));
      }
    }
  }
}

<?php
// Funding Request example
function fundingRequest() {
  global $url, $user, $password;
  echo "\nFunding Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";
  $date = "0401";

  $response = $client->fundingRequest($merchid, $date);
  print var_dump($response);
}
?>

The URL for the CardConnect REST Funding service is:

https://<hostname>:<port>/cardconnect/rest/funding?merchid=<merchid>&date=<date>

Using the GET HTTP verb where <merchid> is the merchant ID and <date> is the date in MMDD format.

The Funding Data API provides merchant funding information supported by supplemental transaction and funding adjustment detail. This information is provided by the host payment processing platform (i.e. First Data Omaha). All data within The Funding Data API’s scope is provided to CardConnect 1-2 days following the merchant’s activity.

The Funding service can be queried by Merchant Id and Date, returning all matching funding data in an array of funding, transaction (txn) and adjustment records each with a structure containing funding data.

Merchant id is required. If the date field is null, the service will check for any funding data that has not already been retrieved. Otherwise, status information will be returned for batches matching the two parameters. If no batches are found or are ready to return the service returns an empty vector.

Funding Response

Example Funding Response

{
   "txns":    [
            {
         "cardtype": "Credit",
         "status": "Processed",
         "retref": null,
         "interchangeunitfee": null,
         "cardnumber": "44XXXXXXXXXX4329",
         "type": "Sale",
         "fundingid": 13899,
         "interchangepercentfee": null,
         "date": "2014-03-31",
         "currency": "USD",
         "cardbrand": "Visa",
         "amount": 995,
         "fundingtxnid": 25
      },
            {
         "cardtype": "Credit",
         "status": "Processed",
         "retref": null,
         "interchangeunitfee": null,
         "cardnumber": "37XXXXXXXXXX003",
         "type": "Sale",
         "fundingid": 13900,
         "interchangepercentfee": null,
         "date": "2014-03-31",
         "currency": "USD",
         "cardbrand": "American Express",
         "amount": 1495,
         "fundingtxnid": 25
      },
            {
         "cardtype": "Credit",
         "status": "Processed",
         "retref": null,
         "interchangeunitfee": null,
         "cardnumber": "52XXXXXXXXXX7030",
         "type": "Sale",
         "fundingid": 13907,
         "interchangepercentfee": null,
         "date": "2014-03-31",
         "currency": "USD",
         "cardbrand": "Mastercard",
         "amount": 1145,
         "fundingtxnid": 25
      },
            {
         "cardtype": "Credit",
         "status": "Processed",
         "retref": null,
         "interchangeunitfee": null,
         "cardnumber": "45XXXXXXXXXX1081",
         "type": "Sale",
         "fundingid": 13909,
         "interchangepercentfee": null,
         "date": "2014-03-31",
         "currency": "USD",
         "cardbrand": "Visa",
         "amount": 1495,
         "fundingtxnid": 25
      }
   ],
   "fundingdate": "2014-03-31",
   "merchid": "496400000840",
   "datechanged": null,
   "fundings": [   {
      "totalfunding": 3635,
      "ddanumber": "5XXXXX1756",
      "datechanged": "2014-04-11",
      "interchangefee": 0,
      "fundingid": 405,
      "fundingmasterid": 25,
      "servicecharge": 0,
      "currency": "USD",
      "fee": 0,
      "dateadded": "2014-04-11",
      "adjustment": 0,
      "netsales": 5130,
      "thirdparty": -1495,
      "otheradjustment": 0,
      "reversal": 0,
      "abanumber": "054000030"
   }],
   "fundingmasterid": 25,
   "adjustments": [   {
      "amount": -1495,
      "category": "THIRD PARTY",
      "dateadded": "2014-04-11",
      "description": "THIRD PARTY ADJUSTMENTS",
      "merchid": "496202840880",
      "datechanged": "2014-04-11",
      "type": "THIRD PARTY ADJUSTMENTS",
      "fundingmasterid": 25,
      "fundingadjustmentid": 1081,
      "currency": "USD"
   }]
}

Field	Size	Type	Comments
fundingid	12	N	Unique key identifier for merchants with daily funding activity
fundingmasterid	12	N	Unique key for an aggregated merchant’s daily funding
netsales	12	N	Total sales processed by merchant
thirdparty	12	N	Transactions that are passed directly to a third party service provider for processing and/or funding
adjustment	12	N	Amounts credited to or deducted from account to resolve processing or billing discrepancies
interchangefee	12	N	Variable amounts established by the Card Associations for processing transactions
servicecharge	12	N	Amounts charged to authorize process and settle card transactions
fee			A range of transaction-based and/or fixed amounts for specific card processing services
reversal	12	N	Transactions that are challenged or disputed by a cardholder or card-issuing bank. A Chargeback is the amount that is disputed by the cardholder or card-issuing bank. A Reversal is the amount that was previously resolved against the merchant but now is resolved in favor of the merchant
otheradjustment	12	N	General adjustment classification. Adjustment type not provided by host.
totalfunding	12	N	Total Amount of the bank deposit made by the host
currency	10	AN	Three digit code identifying the funded currency Funding Appendix C: Currency Code
ddanumber	20	AN	Demand Deposit Account number
abanumber	20	AN	Unique number assigned by the American Bankers Association (ABA) that identifies a specific federal or state chartered bank or savings institution
dateadded	8	DATE YYYYMMDD	Date record created
datechanged	8	DATE YYYYMMDD	Date record was last updated

Funding Node

Field	Content	Max Len	Comments
fundingmasterid	Funding Master ID	12	Unique key for an aggregated merchant’s daily funding
merchid	Merchant Id	25	Merchant identifier assigned by host
netsales	Net Sales	12	Total sales processed by merchant
thirdparty	Third Party	12	Transactions that are passed directly to a third party service provider for processing and/or funding
adjustment	Adjustment	12	Amounts credited to or deducted from account to resolve processing or billing discrepancies
interchangefee	Interchange Fees	12	Variable amounts established by the Card Associations for processing transactions
servicecharge	Service Charges	12	Amounts charged to authorize process and settle card transactions
fee	Fees	12	A range of transaction-based and/or fixed amounts for specific card processing services
reversal	Reversals	12	Transactions that are challenged or disputed by a cardholder or card-issuing bank.
otheradjustment	Other Adjustment	12	General adjustment classification. Adjustment type not provided by host.
totalfunding	Funding Amount	12	Total amount of debit or credit event
fundingdate	Funding Date	8	The date of the bank funding event
currency	Currency Code	3	Three digit code identifying the funded currency Funding Appendix C: Currency Code
ddanumber	DDA Number	20	Masked demand deposit account number
abanumber	ABA Number	20	American Bankers Association (ABA) that identifies the bank

Txn Node

Field	Content	Max Len	Comments
fundingtxnid	Transaction ID	12	CardConnect id for each record
retref	Gateway ID	30	CardConnect gateway reference number (aka RetRef)
interchangeunitfee	Interchange unit fee	12	Unit based fee charged for acceptance of card transaction
interchangepercentfee	Interchange percent fee	12	Percentage based fee charged for acceptance of card transaction
date	Transaction Date	8	Date the transaction occurred
cardnumber	Card Number	25	Masked card number used for transaction
cardtype	Card Type	20	Type of card used for transaction Funding Appendix A: Card Type
cardbrand	Card Brand	30	The brand associated to the card Funding Appendix B: Card Brand
amount	Amount	12	The transaction amount
currency	Currency Code	10	Three character currency code associated to transaction Funding Appendix C: Currency Code
date	Date	8	Date the transaction occurred
type	Type	25	Type of transaction Processed Funding Appendix D: Transaction Type
status	Type	100	Status of transaction Funding Appendix E: Transaction Status

Adjustment Node

Field	Content	Max Len	Comments
fundingadjustmentid	Funding Adjustment ID	12	CardConnect unique system identifier for adjustment
fundingmasterid	Funding Master ID	12	Unique key for an aggregated merchant’s daily funding
merchid	MID	25	Merchant identifier assigned by host Funding Appendix F: Adjustment Group
category	Adjustment Group	100	Category of deposit adjustment Funding Appendix F: Adjustment Group
type	Adjustment Group Description	100	Type of deposit adjustment
description	Adjustment Description	200	Detailed description of adjustment
amount	Adjustment Amount	12	Amount of adjustment
currency	Currency Code	10	Three digit code identifying the funded currency Funding Appendix C: Currency Code

If no adjustment detail is listed by the host, any offset to the funding amount will be listed as other adjustment in this record.

Funding Appendix A: Card Type

Card Type	Description
Credit	Payment card issued by a bank, business, etc., allowing the holder to purchase goods or services on credit.
Debit	Payment card issued by a bank allowing the holder to transfer money electronically to another bank account when making a purchase.
EBT	Electronic Benefit Transfer is an electronic system that allows state welfare departments to issue benefits via a magnetically encoded payment card.

Funding Appendix B: Card Brand

Card Brand	Description
MC	MasterCard
VISA	Visa
DSCV	Discover
UNKN	Unknown
AMEX	American Express
WEX	Wright Express
VYGR	Voyager
TEL	Telecheck
DNR	Diners
JCB	Japan Credit Bureau
BML	Bill Me Later
RM	Revolution Money

Funding Appendix C: Currency Code

CardConnect adheres to the ISO 4217 standards for currency code identification as set forth by the International Organization for Standards (ISO) . Please refer to http://www.iso.org/iso/currency_codes for a comprehensive mapping of alphabetic codes.

Funding Appendix D: Transaction Type

Transaction Type	Description
SALE	Sale or ticket-only sale.
REFUND	Credit back of a sale due to a return or refund.
CASH ADVANCE	Cash Advance
VOID SALE	Void a sale or ticket-only sale or a cash advance.
VOID REFUND	Void a return or refund.
AUTH REQUEST	Authorization request.
ACCOUNT VERIFY	Account verification.
UNKNOWN	Source data transaction type not mapped.

Funding Appendix E: Transaction Status

Transaction Status	Description
Auth	The credit card authorization request was processed successfully.
Captured	The credit card authorization was captured, and the request was processed successfully by the payment processor.
Voided	A deletion of the transaction information.
Failure	The credit card (authorization, capture, or credit) or check (debit or credit) request failed.
Rejected	A rejection of the transaction information due to duplicate transaction or fraud protection.
Declined	A response from the card issuer denying the use of the card for the attempted transaction.
Settled	The check debit or credit request was processed successfully.
Unknown	Transaction status not supplied.

Funding Appendix F: Adjustment Group

Adjustment Group	Adjustment Group Detail
ADJUSTMENTS	DEPOSIT ADJUSTMENTS
ADJUSTMENTS	FINANCIAL ADJUSTMENTS
ADJUSTMENTS	AGENT BANK
ADJUSTMENTS	CASH ADVANCE ADJUSTMENT
ADJUSTMENTS	COST OF FUNDS
ADJUSTMENTS	DEPOSIT ADJUSTMENTS
FEES	FEES
FEES	ADDRESS VERIFICATION
FEES	AUTHORIZATIONS
FEES	ACCOUNT MANAGEMENT FEES
FEES	WS INFO. MGR.
FEES	CHARGEBACK TRANSACTION PROCESSING
FEES	DEBIT
FEES	DATA CAPTURE
FEES	CES IMAGE
FEES	EQUIPMENT
FEES	COMMUNICATION
FEES	CASH ADVANCE
FEES	CES LINK
FEES	CHECK SERVICES
FEES	FUNDS TRANSFER
FEES	SUPPLIES
FEES	FOREIGN HANDLING
FEES	REPORT
FEES	CES TRANSLINK
FEES	USAVE
INTERCHANGE CHARGES	INTERCHANGE CHARGES
INTERCHANGE CHARGES	INTERCHANGE
INTERCHANGE CHARGES	ASSESSMENT
INTERCHANGE CHARGES	NON-QUAL TRANSACTIONS
INTERCHANGE CHARGES	AGENT INTERCHANGE
INTERCHANGE CHARGES	INTERCHANGE/ASSESSMENT ADJ.
INTERCHANGE CHARGES	DEBIT
REVERSAL	CHARGEBACKS/CHARGEBACK REVERSALS
REVERSAL	DEBIT ADJUSTMENTS
REVERSAL	DEBIT ADJUSTMENT REVERSAL
SERVICE CHARGES	SERVICE CHARGES
SERVICE CHARGES	SERVICE CHARGE ADJUSTMENTS
SERVICE CHARGES	DEBIT SERVICE CHARGE
THIRD PARTY	THIRD PARTY ADJUSTMENTS
OTHER ADJUSTMENT	OTHER ADJUSTMENT

Profile Service

The URL for the CardConnect REST Profile service is:

https://<hostname>:<port>/cardconnect/rest/profile

A profile can consist of multiple sets of profile account data. Each set is assigned an acctid which can be used in conjunction with the profileid to access a specific account. The format is (profileid/acctid) for use in each request’s profile field. One account in each profile will be marked as the default account and will be referenced when no acctid is supplied.

In addition to the profile create and use features of the authorization service, the Profile services provides an independent method to create, update/replace, retrieve and delete a profile.

A create or update request is made including the fields below (the same fields marked with asterisk in the authorization request). The service tokenizes the account property and creates the profile with a token, and profileid/acctid. One acctid in each profile can be mark as the default account. The default account will be used for all authorization requests when only the profileid is supplied. If an acctid is present the service retrieves the existing profile and updates it, or returns profile not found.

Profile Get

Example Profile Get

[
  {
    "region": "AK",
    "phone": "7778789999",
    "postal": "19090",
    "address": "123 MAIN STREET",
    "accttype": "VISA",
    "token": "9440670166031111",
    "ssnl4": "3655",
    "name": "TOM JONES",
    "license": "123451254",
    "country": "US",
    "city": "ANYTOWN",
    "expiry": "0214",
    "profileid": "12345678901234567890",
    "acctid": "1"
  }
]

/**
 * Get Profile REST Example
 * @param profileid
 */
private static void getProfile(String profileid) {
  Console.WriteLine("\nGet Profile Request");
  // Merchant ID
  String merchid = "496400000840";
  // Account ID
  String accountid = "1";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Retrieve profile from Profile Service
  JArray response = client.profileGet(profileid, accountid, merchid);

  // Handle response
  if (response != null)
  {
    foreach (JObject obj in response)
    {
      foreach (var x in obj)
      {
        String xkey = x.Key;
        JToken xvalue = x.Value;
        Console.WriteLine(xkey + ": " + xvalue.ToString());
      }
    }
  }
}

/**
 * Get Profile REST Example
 * @param profileid
 */
private static void getProfile(String profileid) {
  System.out.println("\nGet Profile Request");
  // Merchant ID
  String merchid = "496400000840";
  // Account ID
  String accountid = "1";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Retrieve profile from Profile Service
  JSONArray response = client.profileGet(profileid, accountid, merchid);

  // Handle response
  if (response != null) {
    for (int i=0; i<response.size(); i++) {
      JSONObject object = (JSONObject)response.get(i);
      Set<String> keys = object.keySet();
      for (String key : keys) 
        System.out.println(key + ": " + object.get(key));
    }
  }
}

<?php
// Profile Service get Profile example
function getProfile($profileid, $accountid = "") {
  global $url, $user, $password;
  echo "\nGet Profile Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";

  $response = $client->profileGet($profileid, $accountid, $merchid);
  print var_dump($response);
}
?>

The REST verb GET is used to retrieve a stored profile using the following path parameter format.

https://<hostname>:<port>/cardconnect/rest/profile/{profileid}/{acctid:./}/{merchid}

Where {profile} is the profileid for the Profile vault data and {merchid} is the associate merchant identifier. Supply the optional acctid parameter to retrieve a specific account within a profile. The profile data will be returned as a JSONArray of JSONObjects.

Field	Size	Type	Comments
profileid	20	N	Primary identifier to access profiles
acctid	3	N	Account identifier within a profile
respstat	1	A	A - Approved B - Retry C - Declined
account	19	AN	Copied from request, masked
respcode	3	A	Alpha-numeric response code. See the tables in the PROCESSOR SPECIFIC responses. PPS – 2 Numeric FNOR – 2 Alphanumeric
resptext	32	A	Text description of response
respproc	4	A	PPS - CardConnect internal response FNOR - First Data North
accttype	6	A	The value supplied in account creation; VISA, MC, DISC, ECHK.
expiry	4	N	Card Expiration in either MMYY or YYYYMMDD format
name	30	AN	Account name; CCard optional, ECheck required
address	30	AN	Account street address
city	30	AN	Account city
region	20	AN	US State, Mexican State, Canadian Province
country	2	AN	Account country (2 character country code)
phone	15	AN	Account phone (required for ECHK, SAV)
postal	9	AN	Account postal code - if country is “US”, must be 5 or 9 digits - otherwise any alphanumeric string is accepted
ssnl4	4	N	Last four digits of account social security number
email	30	AN	E-Mail address of the account holder
defaultacct	1	A	Y marks the default account referenced when profileid is used without an acctid specified
license	15	N	Driver’s license state (two Characters) + : + number, For example NY:12JKHQ123

Profile Delete

/**
 * Delete Profile REST Example
 * @param profileid
 */
private static void deleteProfile(String profileid) {
  Console.WriteLine("\nDelete Profile Request");
  // Merchant ID
  String merchid = "496400000840";
  String accountid = "";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Delete profile using Profile Service
  JObject response = client.profileDelete(profileid, accountid, merchid);

  // Handle response
  if (response != null) {
    foreach (var x in response)
    {
      String xkey = x.Key;
      JToken xvalue = x.Value;
      Console.WriteLine(xkey + ": " + xvalue.ToString());
    }
  }
}

/**
 * Delete Profile REST Example
 * @param profileid
 */
private static void deleteProfile(String profileid) {
  System.out.println("\nDelete Profile Request");
  // Merchant ID
  String merchid = "496400000840";
  String accountid = "";

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Delete profile using Profile Service
  JSONObject response = client.profileDelete(profileid, accountid, merchid);

  // Handle response
  if (response != null) {
    Set<String> keys = response.keySet();
    for (String key : keys) 
      System.out.println(key + ": " + response.get(key));
  }
}

<?php
// Profile Service delete Profile example
function deleteProfile($profileid, $accountid = "") {
  global $url, $user, $password;
  echo "\nDelete Profile Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  $merchid = "496400000840";

  $response = $client->profileDelete($profileid, $accountid, $merchid);
  print var_dump($response);
}
?>

Example Profile Delete Response

{
  "resptext": "Profile Deleted",
  "respcode": "08",
  "profileid": "12345678901234567890",
  "acctid": "1",
  "respproc": "PPS",
  "respstat": "A"
}

To delete a profile use the REST verb DELETE with the following format with profileid/ (optional) acctid and merchid provided.

https://<hostname>:<port>/cardconnect/rest/profile/{profileid}/{acctid:./}/{merchid}

Supply the merchid profileid to delete the entire profile and all accounts. Supply the optional acctid to delete a specific account within a profile.

Example Delete Entire Profile and all Accts

https://url.goeshere.com:6443/cardconnect/rest/profile/12345678901234567890//496400000840

Profile Create/Update

The REST verb PUT is used to create or update a stored profile using the following format.

https://<hostname>:<port>/cardconnect/rest/profile

Profile Create/Update Request

Example Profile Create/Update Request

{
  "region": "AK",
  "phone": "7778789999",
  "accttype": "VISA",
  "postal": "19090",
  "ssnl4": "3655",
  "expiry": "0214",
  "city": "ANYTOWN",
  "country": "US",
  "address": "123 MAIN STREET",
  "merchid": "496400000840",
  "name": "TOM JONES",
  "account": "4444333322221111",
  "license": "123451254",
  "defaultacct": "N",
  "profileupdate": "Y"
}

/**
 * Add Profile REST Example
 */
private static void addProfile() {
  Console.WriteLine("\nAdd Profile Request");

  // Create Profile Request
  JObject request = new JObject();
  // Merchant ID
  request.Add("merchid", "496400000840");
  // Default account
  request.Add("defaultacct", "Y");
  // Card Number
  request.Add("account", "4444333322221111");
  // Card Expiry
  request.Add("expiry", "0914");
  // Cardholder Name
  request.Add("name", "Test User");
  // Cardholder Address
  request.Add("address", "123 Test St");
  // Cardholder City
  request.Add("city", "TestCity");
  // Cardholder State
  request.Add("region", "TestState");
  // Cardholder Country
  request.Add("country", "US");
  // Cardholder Zip-Code
  request.Add("postal", "11111");

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Create profile using Profile Service
  JObject response = client.profileCreate(request);

  // Handle response
  foreach (var x in response)
  {
    String xkey = x.Key;
    JToken xvalue = x.Value;
    Console.WriteLine(xkey + ": " + xvalue.ToString());
  }
}

/**
 * Add Profile REST Example
 */
private static void addProfile() {
  System.out.println("\nAdd Profile Request");

  // Create Profile Request
  JSONObject request = new JSONObject();
  // Merchant ID
  request.put("merchid", "496400000840");
  // Default account
  request.put("defaultacct", "Y");
  // Card Number
  request.put("account", "4444333322221111");
  // Card Expiry
  request.put("expiry", "0914");
  // Cardholder Name
  request.put("name", "Test User");
  // Cardholder Address
  request.put("address", "123 Test St");
  // Cardholder City
  request.put("city", "TestCity");
  // Cardholder State
  request.put("region", "TestState");
  // Cardholder Country
  request.put("country", "US");
  // Cardholder Zip-Code
  request.put("postal", "11111");

  // Create the CardConnect REST client
  CardConnectRestClient client = new CardConnectRestClient(ENDPOINT, USERNAME, PASSWORD);

  // Create profile using Profile Service
  JSONObject response = client.profileCreate(request);

  // Handle response
  Set<String> keys = response.keySet();
  for (String key : keys) 
    System.out.println(key + ": " + response.get(key));
}

<?php
// Profile Service create Profile example
function createProfile() {
  global $url, $user, $password;
  echo "\nCreate Profile Request\n";
  $client = new CardConnectRestClient($url, $user, $password);

  // Merchant ID
  $request = array(
    'merchid' => "496400000840",
    'defaultacct' => "Y",
    'account' => "4444333322221111",
    'expiry' => "0914",
    'name' => "Test User",
    'address' => "123 Test St",
    'city' => "TestCity",
    'region' => "TestState",
    'country' => "US",
    'postal' => "11111",
  );

  $response = $client->profileCreate($request);
  print var_dump($response);
}
?>

Field	Size	Type	Comments
profile	20+	N	20 digit profileid/(optional) 3 digit acctid
defaultacct	1	A	“Y” to assign as default account
profileupdate	1	A	“Y” to update profile data with non-empty request data only as opposed to full profile replacement including empty values
accttype	6	A	One of PPAL, PAID, GIFT, PDEBIT, otherwise not required
merchid*	12	N	Merchant Id, required for all requests
account*	19	N	Tokenized card number for payment card Bank account number for ECheck Masked in response
bankaba	9	N	Bank routing (ABA) number, ECHK only
expiry	4	N	Card Expiration in either MMYY or YYYYMMDD format
name	30	AN	Account name; CCard optional, ECheck required
street	30	AN	Account street address
city	30	AN	Account city
region	20	AN	US State, Mexican State, Canadian Province
country	2	AN	Account country (2 character country code)
phone	15	AN	Account phone (required for ECHK, SAV)
postal	9	AN	Account postal code if country is “US”, must be 5 or 9 digits otherwise any alphanumeric string is accepted
ssnl4	4	N	Last four digits of account social security number
email	30	AN	E-Mail address of the account holder
license	15	N	Driver’s license state (two Characters) + : + number, For example NY:12JKHQ123

If a valid CardSecure issued token was not provided one will be returned as a token field in the response.

Profile Create/Update Response

Example Profile Create/Update Response

{
  "region": "AK",
  "phone": "7778789999",
  "accttype": "VISA",
  "postal": "19090",
  "ssnl4": "3655",
  "respproc": "PPS",
  "expiry": "0214",
  "city": "ANYTOWN",
  "country": "US",
  "resptext": "Profile Saved",
  "token": "9440670166031111",
  "respcode": "09",
  "address": "123 MAIN STREET",
  "name": "TOM JONES",
  "license": "123451254",
  "respstat": "A",
  "profileid": "12345678901234567890",
  "acctid": "1"
}

Field	Size	Type	Comments
profileid	20	N	Primary identifier to access profiles
acctid	3	N	Account identifier within a profile
respstat	1	A	A - Approved B - Retry C - Declined
account	19	AN	Copied from request, masked
respcode	3	A	Alpha-numeric response code. See the tables in the PROCESSOR SPECIFIC responses. PPS – 2 Numeric FNOR – 2 Alphanumeric
resptext	32	A	Text description of response
respproc	4	A	PPS - CardConnect internal response FNOR - First Data North
accttype	6	A	The value supplied in account creation; VISA, MC, DISC, ECHK.
expiry	4	N	Card Expiration in either MMYY or YYYYMMDD format
name	30	AN	Account name; CCard optional, ECheck required
address	30	AN	Account street address
city	30	AN	Account city
region	20	AN	US State, Mexican State, Canadian Province
country	2	AN	Account country (2 character country code)
phone	15	AN	Account phone (required for ECHK, SAV)
postal	9	AN	Account postal code - if country is “US”, must be 5 or 9 digits - otherwise any alphanumeric string is accepted
ssnl4	4	N	Last four digits of account social security number
email	30	AN	E-Mail address of the account holder
defaultacct	1	A	Y marks the default account referenced when profileid is used without an acctid specified
license	15	N	Driver’s license state (two Characters) + : + number, For example NY:12JKHQ123

Response Codes

The following subsections list various processor specific response codes. The first subsection lists the response codes that are returned by CardConnect internally. If any of these responses occurs, the authorization was not transmitted to the clearinghouse host.

The remaining subsections contain 3 tables each:

• Authorization response codes: the actual 2-3 character code and the short text description that is returned to the on-line authorization module
• Address Verification (AVS) response codes
• Card Validation (CVV) response codes

Amex declines any transactions with a CVV mismatch… Discover approves the transaction with a separate CVV response. Most Visa and MasterCard banks decline on a CVV mismatch; some approve with a negative CVV response.

The 1-character Status Response has the following values in the tables:

• A = Approval
• B = Retry: Some network or system is unavailable, retry with the same data
• C = Decline: The Clearinghouse responded with a decline

The responses from some issuers are specifically vague, thus some of the text descriptions may not accurately reflect the underlying problem. For example, a response of “expired card” may actually mean “wrong expiration date”.

A response of “Call” means that the authorization cannot be obtained electronically. The cardholder must give you the phone on the back of the card for you to call and get a “voice” authorization which is manually recorded. This is only possible for a Call Center, not a Web site.

The Authorization response codes are in an editable authResp.dat file. This permits on-site changes to the file if new codes are added, or the text or status value is incorrect. The messages file is a comma delimited text file with 3 columns, optionally followed by a comment:

• Response code, which can be numeric or alphanumeric depending on the clearinghouse
• Status code, which is one of the status values above
• Text description of the response code

CardConnect

The following table shows the response codes that can be generated by CardConnect internally. Additional comments enclosed in brackets are not part of the response text.

Response Code	Status Response
00 = Approval	A = Approved
11 = Invalid card	C = Bad Card Data
12 = Invalid track	C = Bad Track Data
13 = Bad card check digit	C = Failed Luhn
14 = Non-numeric CVV	C = CVV not numeric
15 = Non-numeric expiry	C = Expiration not numeric
16 = Card expired	C = Expiration in the past
17 = Invalid zip	C = US zip code not 5 or 9 digits
21 = Invalid merchant	C = Merchant Id Not Found
22 = No auth route	C = CardConnect configuration error
23 = No auth queue	B = Retry [CardConnect error]
24 = Reversal not supported	C = Cannot Void
25 = No matching auth for reversal	C = Cannot Void
26 = Txn Settled	A = Already Captured
27 = Txn Batched	C = Cannot Void
28 = Txn not settled	C = Cannot Refund
29 = Txn not found	C = Bad Retref
31 = Invalid currency	C = Bad Currency
32 = Wrong currency for merch	C = Bad Currency for Merchant configuration
33 = Unknown card type	C = Bad card
34 = Invalid field	C = Bad Data
35 = No postal code	C = No Postal
36 = Duplicate sequence	C = Duplicate Txn
37 = CVV mismatch	C = Proc approved but CVV mismatch
41 = Below min amount	C = Bad amount
42 = Above max amount	C = Bad amount
43 = Invalid amount	C = Bad amount
44 = Prepaid not supported	C = Not configured for Prepaid BINs
61 = Line down	B = Retry [connection to processor down]
62 = Timed out	B = Retry [no issuer response]
63 = Bad resp format	C = Error parsing issuer response
64 = Bad HTTP Header	C = Error parsing issuer response
65 = Socket close error	C = Network Error
66 = Response mismatch	C = Network Error
91 = No TokenSecure	B = Retry [CardConnect error]
92 = No Merchant table	C = Bad Data
93 = No Database	B = Retry [CardConnect error]
94 = No action	C = Bad Data
95 = Missing config	C = Missing Config
96 = No Profile	C = Profile Not Found

First Data North

Code	Suggested Text	Meaning
00	Approval	Approved for capture in batch
00	New Account Information	Applies to Recurring Authorizations Only These are examples of what may have occurred: Card has expired, Account was upgraded, Portfolio sale, Conversion
09	Profile Saved	Profile data was saved successfully, pass token in profile field to access profile data during a transaction
01	Referral	Referral
03	Invld Mer ID	Invalid Merchant number or Subscriber doesn’t exist or is inactive
03	Declined	Invalid Merchant number or Subscriber doesn’t exist or is inactive
05	Declined	Declined
05	DOB Error	Date of Birth Error for Check Processing
10	Apprv Lesser Amt	Approved for a lesser amount than what was requested (i.e. partial approval)
12	Inv tran	Invalid Transaction
12	Inv State Code	Invalid State Code for Check Processing
12	Referral-Inv TR1	More than 76 characters in Track 1 or Track 1 not formatted correctly
13	Inv Amt	Invalid amount
14	Inv Acct Num	Account Number not on file or Checking Account Number
14	New Account Information	Applies to Recurring Authorizations Only These are examples of what may have occurred: Card has expired, Account was upgraded, Portfolio sale, Conversion
14	Do not try again	Applies to Recurring Authorizations Only The account number is invalid
25	Inv Terminal	Terminal Not Found
28	Please Retry	File is temporarily unavailable
51	Declined	Declined
51	Inv Acct Num	Invalid Checking Acct Num
51	Do not honor	Applies to Recurring Authorizations Only Declined: Association‘s payment cancellation advice code provided
51	Do not try again	Applies to Recurring Authorizations Only Declined: Association‘s payment cancellation advice code provided
51	New Account Information available	Applies to Recurring Authorizations Only Declined: Association‘s payment cancellation advice code provided
51	Try again later	Applies to Recurring Authorizations Only Declined: Association‘s payment cancellation advice code provided
54	Do not try again	Applies to Recurring Authorizations Only The card has expired
54	New Account Information	Applies to Recurring Authorizations Only The card has expired
54	Try again later	Applies to Recurring Authorizations Only The card has expired. Get the new expiration date and try again
54	Expired Card	Expired Card
55	Incorrect Pin	Incorrect Pin
57	Tran Not Allowed	Transaction Not Allowed
60	Hold-Call Ctr	Capture Card – Call Center
61	Amt Exceeds Lmt	Amount Exceeds Limit
63	Serv Not Allowed	Service Not Allowed
63	Declined	For American Express transactions if the CID from the transaction doesn’t match the one on file then decline transaction, transaction not permitted to acquirer or terminal
63	Do not try again	Applies to Recurring Authorizations Only There was security violation
69	Host Key Error	Host Key Error
75	Pin Retry Max	Allowable number of PIN tries exceeded
75	Pin Try Exceeded	Allowable number of PIN tries exceeded
76	Approval	Approved (non captured)
85	AVS Accepted	AVS Request Accepted
89	Invalid Term ID	Invalid Term ID
89	Declined	Term record not found on First Data system
91	Service error	Reasons for this error are one of the following: Format Error Unable to route transaction Switch or issuer unavailable System Busy Timeout
94	Duplicate Tran	Duplicate Transaction
C2	CVV2 Declined	Association indicated the transaction was not approved due to mismatch of the CVV2 value, but it would have been approved had the CVV2 value matched
CE	System Problem	System Problem
N3	Invld Acct2	Invalid account/date or sales date in future
N3	Declined	Invalid Effective Date
NG	Rev Rejected	Reversal Rejected cannot parse 400 message
NH	Enter Lesser Amt	Enter lesser amount
NI	Pin Xlate Error	Host Security module could not decrypt the PIN block. Master Session: The master key is missing or incorrect in the PIN pad, or the merchant record set-up incorrectly at First Data Host. DUKPT: The Base Derivation key is missing or incorrect in the PIN pad, or is set-up incorrectly in the Host Security Module.
NJ	Inv Cashback Amt	Cash Back amount greater than total Transaction amount (bit 4)
NK	Crypto Box Unav	Crypto box is offline
NL	Dbt Switch Unavl	Communications link to debit/EBT network gateway is down or responded with a “System Malfunction (96)” message
NL	DBT T.O. Retry	Communications link to debit/EBT network gateway is down or responded with a “System Malfunction (96)” message
NM	Issuer Unav	Debit/EBT network gateway cannot get through to the ISSUER
NN	Undefined Card	Debit/EBT network gateway cannot route card based on Merchant Entitlement
NP	Dbtsw inv merid	Network Response indicates that Merchant ID / SE is invalid
NQ	Tran Ct Excd Lmt	Debit/EBT transaction count exceeds pre-determined limit in specified time/ Withdrawal limit exceeded
NR	Resub Excds Lmt	Resubmission of transaction violates debit/EBT network frequency
NS	Dbtsw Pin Xl Err	The authorizing network has a problem decrypting the cryptogram in the request
NU	Declined	Insufficient funds
RW	Rev Outside Win	Reversal Outside Window. Reversal transaction was received, but the original matching authorization request was processed more than 25 minutes ago and is no longer eligible to be reversed. (Applicable to Credit Host Capture only.) If the POS has received a RW response (25 minutes after the original Authorization), the transaction cannot be reversed (voided). The Merchant must issue a refund.

Address Verification System

Brands implement different sets of AVS Response codes, indicated by the initial columns of (V) Visa, (MC) Mastercard, (AX) Amex, and (DI) Discover. Avs refers to the avs response code field returned.

V	MC	AX	DI	Avs	Description
			D	A	Address matches, five-digit ZIP Code matches
	M	A		A	Address Matches ZIP Does Not Match
V				B	Street addresses match. Postal code not verified due to incompatible formats. (Acquirer sent both street address and postal code.)
V				C	Street address and postal code not verified due to incompatible formats. (Acquirer sent both street address and postal code.)
		A		D	Cardmember Name incorrect, Billing Postal Code matches
V				D	Street addresses and postal codes match
		A		E	Cardmember Name incorrect, Billing Address and Postal Code match
		A		F	Cardmember Name incorrect, Billing Address matches
V				F	Street addresses and postal codes match. U.K. only
V			D	G	Address information not verified for international transaction
V				I	Address information not verified
		A		K	Cardmember Name matches
		A		L	Cardmember Name and Billing Postal Code match
V		A		M	Cardmember Name, Billing Address and Postal Code match
V	M	A	D	N	Address and ZIP Do Not Match, DI Nothing Matches
		A		O	Cardmember Name and Billing Address match
V				P	Postal code match. Acquirer sent both postal code and street address, but street address not verified due to incompatible formats
	M	A		R	System Unavailable; retry
	M	A	D	S	Issuer Does Not Support Address Verification
			D	T	Nine - digit ZIP Code matches, address does not
	M	A	D	U	Address Information Is Unavailable
			D	W	No data from Issuer/Authorization system
		A		W	No, Cardmember Name, Billing Address and Postal Code are all incorrect
	M			W	Whole Zip: 9-digit ZIP Matches, Address Does Not Match
			D	X	All digits match (9-digit Zip Code)
	M			X	Exact: Address and 9-digit ZIP Match; Outside U.S., postal code matches, address does not
			D	Y	Address matches, ZIP Code does not
V	M	A		Y	Address and ZIP Match
			D	Z	5-digit Zip matches, address does not
V	M	A		Z	9 or 5 digit ZIP Matches, Address Does Not Match

Card Verification Value 2

Value	Description	Card Types
M	CVV2/CVC2/CID Match	Visa, MasterCard, Amex, and Discover (JCB (US Domestic only), and Diners)
N	CVV2/CVC2/CID No Match	Visa, MasterCard, Amex, and Discover (JCB (US Domestic only), and Diners)
P	Not Processed	Visa, MasterCard, Amex, and Discover (JCB (US Domestic only), and Diners)
S	CVV2 should be on the card, but merchant indicated that it was not	Visa, and Discover (JCB (US Domestic only), and Diners)
U	Unknown/Issuer does not participate	Visa, MasterCard, and Discover (JCB (US Domestic only), and Diners)
X	Server provider did not respond (Default)	Visa, MasterCard, Amex, and Discover (JCB (US Domestic only), and Diners)

Release Notes

---

Sign up for the CardConnect API