CardPointe Gateway API

The following entries describe changes to the CardPointe Gateway API and documentation.

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

UAT-Only Changes

The following enhancements were deployed to the UAT environment on 3/10/2020.

Amount-Driven Response Codes

The amount-driven response codes feature will be enabled for the following UAT emulators:

  • First Data North (FNOR)
  • Chase Paymentech (PMT)
  • Paymentech Tampa (PTAM)
  • TSYS (VPS)
This feature was previously enabled for the First Data Rapid Connect (RPCT) UAT emulator.

When testing your integration in the UAT environment, you can use amount-driven response codes to emulate processor-specific authorization responses that you might encounter in the production environment.

See Testing with Amount-Driven Response Codes for detailed information on this feature.

JSON Response Randomization

CardConnect has developed an enhancement to the UAT (non-production) environment that randomizes the response data returned to your client application. Response fields are now returned in a random order, and responses include additional randomly-generated fields, objects, and arrays containing dummy data.

The following example illustrates the modified UAT authorization response:

{
  "avsresp":"Y",
  "expiry":"1220",
  "respstat":"A",
  "resptext":"Partial Approval",
  "nNBcv":{},
  "lyUy":"GKmUM",
  "authcode":"-",
  "account":"9415809626691111",
  "commcard":"A ",
  "yrpkQmS":{"EMuB":"hrLGci"},
  "cvvresp":"P",
  "batchid":"270",
  "respcode":"10",
  "kePFkt":["RnaRUuCz","EVPFm","ddXcoXnc","JIVtH"],
  "BQVhs":"KZyqBI",
  "merchid":"871555880001",
  "respproc":"VANT",
  "retref":"350001238933",
  "amount":"4.00",
  "token":"9415809626691111"
 }

This change will require your application to parse and accept JSON response properties dynamically, rather than coding for the static position of specific properties within the response data; otherwise, your test cases in the UAT environment may encounter errors or other failures.

This change is intended to help clients identify potential failure points and to ensure that your applications are designed for backwards compatibility. CardConnect intends all changes to the CardPointe Gateway API to be backwards-compatible, assuming that client applications are designed to dynamically handle response data. 

For more information on backwards compatibility, see the API Basics and Best Practices Guide.

Date Updated: 3/3/2020

The following updates were deployed to the UAT environment on 3/04/2020 and the production environment on 3/07/2020.

expiry Field Added to inquire and inquireByOrderid Responses

The inquire and inquireByOrderid responses now include the expiry field in the format MMYY.

Changed commcard Field Values

To simplify the use of the commcard field returned in the auth response, the supported values have been changed to Y and N to simply indicate whether or not the card is a Corporate or Purchase Card. 

If you previously used the commcard value to try to determine the card type, you can instead include "bin":"y" in the auth request to retrieve BIN lookup data in the response. The bin object in the auth response provides information that you can use to determine the type of card and other relevant details. 

Date Updated: 1/19/2020

The following updates were deployed to the Production environment on 1/19/2020.

Note: Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

Updated Cardholder Signature Requirements

The CardPointe Gateway now uses the amount value to determine whether or not a cardholder signature is required, based on the guidelines for each card brand.

The EMV tag data returned in the auth response includes a Cardholder Verification Method (CVM) indicator that determines if a PIN or signature is required.

Note: The CVM value is not used by Bolt terminals. In a Bolt transaction, the cardholder signature prompt is instead driven by the includeSignature parameter in the request or a separate request to the readSignature endpoint.

When the CVM response returned to the CardPointe Gateway includes signature:"true", the Gateway checks the amount and adjusts the signature value as follows:

  • For Visa transactions
    • if the amount is less than $25, then signature:"false".
    • if the amount is greater than or equal to $25, then signature:"true".
  • For Mastercard, Discover, and Amex transactions
    • if the amount is less than $50, then signature:"false".
    • if the amount is greater than or equal to $50, then signature:"true".

bin Field Added to the Authorization and Bin Response

The BIN service now returns the exact bank identification number (BIN) in the bin field in the following responses:

DPS Response Code Changes

The following DPS Payment Express (DPS) response codes have been added:

respprocrespcoderespstatresptext
DPSAQC"Amex not enabled"
DPSD4C"User blocked"
DPSD9C"Invalid merchant or password"

The following DPS response code has been removed:

respprocrespcoderespstatresptext
DPSD5C"Invalid password"

See Gateway Response Codes for a comprehensive list of response codes.

UAT Emulator Updates

The following updates have been made to better align the UAT emulators with the processor host responses received in the production environment:

  • The First Data Rapid Connect emulator now returns the emvTagData array in the auth response when an EMV test card is used.
  • The Paymentech emulator has been updated to support voids for Amex authorizations.

Date Updated: 1/9/2020

The following update was deployed to the UAT environment on 1/9/2020.

Note: This update, as well as the updates released on 12/3/19, were deployed to the Production environment on 1/19/2020. Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

Updated Cardholder Signature Requirements

The CardPointe Gateway now uses the amount value to determine whether or not a cardholder signature is required, based on the guidelines for each card brand.

The EMV tag data returned in the auth response includes a Cardholder Verification Method (CVM) indicator that determines if a PIN or signature is required. 

Note: The CVM value is not used by Bolt terminals. In a Bolt transaction, the cardholder signature prompt is instead driven by the includeSignature parameter in the request or a separate request to the readSignature endpoint. 

When the CVM response returned to the CardPointe Gateway includes signature:"true", the Gateway checks the amount and adjusts the signature value as follows:

  • For Visa transactions
    • if the amount is less than $25, then signature:"false".
    • if the amount is greater than or equal to $25, then signature:"true".
  • For Mastercard, Discover, and Amex transactions
    • if the amount is less than $50, then signature:"false".
    • if the amount is greater than or equal to $50, then signature:"true".

Date Updated: 12/3/2019

The following updates were deployed to the UAT environment on 12/3/2019.

Note: These updates will not be deployed to the production environment until after January 1st 2020.

Visit status.cardconnect.com and click subscribe to updates to receive important release and status notifications.

bin Field Added to the Authorization and Bin Response

The BIN service now returns the exact bank identification number (BIN) in the bin field in the following responses:

DPS Response Code Changes

The following DPS Payment Express (DPS) response codes have been added:

respprocrespcoderespstatresptext
DPSAQC"Amex not enabled"
DPSD4C"User blocked"
DPSD9C"Invalid merchant or password"

The following DPS response code has been removed:

respprocrespcoderespstatresptext
DPSD5C"Invalid password"

See Gateway Response Codes for a comprehensive list of response codes.

UAT Emulator Updates

The following updates have been made to better align the UAT emulators with the processor host responses received in the production environment:

  • The First Data Rapid Connect emulator now returns the emvTagData array in the auth response when an EMV test card is used.
  • The Paymentech emulator has been updated to support voids for Amex authorizations.

Date Updated: 10/23/2019

This release includes the following updates:

Auth Response Changes

The authorization response includes the following changes:

New Response Fields

  • The response now includes the expiry value (MMYY) provided in the request.
  • Declined authorizations can return avsresp and cvvresp.

    Note: This feature must be enabled for the merchant account. Declined authorizations do not return the avsresp and cvvresp values by default.

Changed Response Fields

  • Declined authorizations no longer return profileid or acctid.
  • For merchants with CVV verification enabled (but AVS verification not enabled), $0 authorizations are declined by the CardPointe Gateway, when cvv is not included in the auth request.

    The auth response returns "respproc" : "PPS" and "resptext" : "CVV is required".

orderId Included in inquire, inquirebyOrderid, void, and voidbyOrderId Response

The inquire, inquireByOrderid, void, and voidByOrderId responses now include the orderId included in the original auth request. 

Note:

  • "orderId" : "", If no order ID was provided in the original auth request and "receipt" : "y".
  • orderId is not returned in the response if no order ID was provided in the original auth request and "receipt" : "n".

BIN Response cardusestring Value Change

The cardusestring value for credit hybrid cards now returns "Credit Hybrid (PIN and Signature)" in the BIN response. This is also returned in the auth response when the request includes "bin" : "y".

API Basics and Best Practices Developer Guide

To make the most of your integration, and to ensure that you develop an application that maintains backwards compatibility with the CardPointe Gateway, see our new API Basics and Best Practices Developer Guide

You can find additional helpful information for integrating the CardPointe Gateway API in the CardPointe Gateway Developer Guides.

Date Updated: 9/16/2019

This release includes the following updates:

New API URLs

To better facilitate our partners' API testing and release validation efforts, we are enhancing the CardPointe Gateway release process. To take advantage of these enhancements, your application should no longer target port 6443 when sending requests to the UAT environment. Instead, ensure that your application targets the UAT and PROD environments using the following URLs:

  • UAT: https://<site>-uat.cardconnect.com
  • PROD: https://<site>.cardconnect.com

See the CardPointe Gateway Release Update notification for more information on this change.

See the API Connectivity Guide for general information on connecting to the CardPointe Gateway and other CardConnect services using our APIs.

Auth Request BIN Data Retrieval

The auth request supports a new bin parameter to retrieve BIN data for the card used in an authorization attempt. The BIN service allows you to use a CardConnect token to determine what type of payment card is being used.

Include "bin" : "y" in the authorization request to retrieve BIN data. 

The authorization response includes a binInfo array that includes the BIN response data.

New BIN Response Field

Note: This change was rolled back on 10/2/2019.

The BIN response includes a new bin field that returns the exact BIN value.

Gateway Timeout Testing

Merchants boarded to the First Data North and Rapid Connect platforms can now test CardPointe Gateway timeout responses in the UAT environment. 

See Testing CardPointe Gateway Timeouts in the new Testing your Integration topic in the CardPointe Gateway Developer Guide.

Date Updated: 7/10/2019

This release includes the following updates:

New Voidable and Refundable Transaction Indicators

The inquire and inquireByOrderid responses include two new fields, voidable and refundable. You can use these new fields to more easily determine whether or not a transaction can be voided or refunded in its current state.

New response values include:

ValueDescription
"voidable":"Y"The transaction can be voided.
"voidable":"N"The transaction cannot be voided.
"refundable":"Y"The transaction can be refunded.
"refundable":"N"The transaction cannot be refunded.

The voidable value is determined by the status of the batch at the time of inquiry.

The refundable value is determined by the status of the batch at the time of the inquiry, as well as the MID configuration. If the MID is enabled to refund for unsettled authorizations, then refundable always returns Y.

entrymode Field Now Included in Decline Response

For First Data North (FNOR) merchants, the authorization response now includes the entrymode field for declined authorizations. Previously, entrymode was only returned for approvals.

    Date Updated: 5/30/2019

    This release includes the following updates:

    RapidConnect Auth Response Updates

    Authorization responses from the RapidConnect front end processor now include the entrymode and bintype fields. See the authorization response description for more information.

    Additional emvTagData Field

    The emvTagData included in the authorization response data includes a new Network Label field, which identifies the Authorizing Network Name, which should be printed on the receipt.

    Date Updated: 5/13/2019

    This release includes the following updates:

    Additional Receipt Data Fields

    The authorization request now includes a receipt parameter, used to return additional receipt data fields in the authorization response. When you specify "receipt" : "y" in the authorization request, the receipt array is included in the authorization response data as well as any subsequent inquire or inquireByOrderid requests for that authorization record.

    See Printing Receipts Using Authorization Data for detailed information on customizing the receipt data fields and printing receipts.

    Date Updated: 4/29/2019

    This release includes the following updates:

    Support for POST Requests

    The CardPointe Gateway API now supports HTTP POST requests for all service endpoints that support PUT requests. You can now use either PUT or POST operations to create and update resources.

    New inquireMerchant Endpoint

    The new inquireMerchant endpoint allows you to validate CardConnect merchant account configurations. This is helpful for partners who need to validate their CardConnect merchant IDs or for businesses with merchants operating in multiple locations, to ensure that the merchant ID is boarded to the correct site.

    Date Updated: 2/22/2019

    This release includes the following updates:

    Developer Documentation Improvements

    The CardPointe Gateway API developer documentation has been updated with numerous improvements, including:

    • A new Postman Collection, to help you test and experiment with the CardPointe Gateway API.
    • Revised content throughout.

    New inquireByOrderid Endpoint

    The new inquireByOrderid endpoint allows you to inquire on a transaction using the order ID included in the original request. This is helpful when the request timed out or did not return a retref, and you want to check on the status of the transaction.

    New voidByOrderId Endpoint

    The new voidByOrderId endpoint allows you to void a transaction using the order ID included in the original request. This is helpful when the original request did not return a response, and a subsequent inquireByOrderid call does not return a response. In this case, it is recommended that you call voidByOrderId three times (3x) to ensure that the transaction is voided.

    Updated CardPointe Gateway Response Codes

    The Gateway Response Codes page now includes a downloadable text file that provides a comprehensive list of all possible response codes that can be returned from the Gateway and from all supported processing hosts. This page also includes a new topic, Testing With Amount-Driven Response Codes, that provides information for emulating response codes for testing purposes. Note that this feature is currently limited to merchants using the RapidConnect processor.

    Deprecated openBatch and CloseBatch Endpoints

    The openBatch and closeBatch endpoints have been removed from the CardPointe Gateway API documentation, but are still available for use if required for your business. The CardPointe Gateway automatically manages batches; however, if you need to integrate these manual batch management features, see Manually Managing Gateway Batches in the CardPointe Gateway Developer Guides