We're excited to announce a new addition to our developer resources. Our CardConnect Developer Guides provide additional information for integrating CardConnect products and services.

You can browse the whole library at https://developer.cardconnect.com/guides/home, or jump right to the CardPointe Gateway Developer Guides to make the most of your CardPointe Gateway API integration.

Overview

The CardPointe Gateway API allows you to securely accept a wide-range of credit, debit, and alternative payments.  

If you are interested in testing with our API, please contact us for a welcome kit which contains test credentials and additional information.

What's New?

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.

    REST Implementation

    The CardPointe Gateway API uses REST Web Services to implement create, replace, update, and delete (CRUD) functions. 

    • GET operations are used for inquiry requests (for example, the Inquire and Settlement Status services).
    • PUT and POST operations are used to make create or update requests (for example the Authorization and Void services).
    • DELETE operations are supported for the Profile service, to delete a stored profile.
    • The REST Service expects all properties encoded as US ASCII Strings.

    This web service uses the JSON (JavaScript Object Notation) method of encoding data for transmission via the HTTP network protocol. 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.

    The CardPointe Gateway API returns all response data in JSON. Updates to the API are backwards compatible, and CardConnect reserves the right to add new properties (key/value pairs) within the JSON response.

    It is a best practice to develop client applications that dynamically accept and parse all JSON response properties, rather than coding for the static position of specific properties within the response data.

    Developer Resources

    The following resources are available to simplify your integration.

    CardConnect Developer Guides

    Our CardConnect Developer Guides provide additional information for integrating CardConnect products and services.

    You can browse the whole library at https://developer.cardconnect.com/guides/home, or jump right to the CardPointe Gateway Developer Guides to make the most of your CardPointe Gateway API integration.

    Sample Postman Collection

    To help you get started with your integration, CardConnect provides a sample Postman Collection that includes a template of the CardPointe Gateway API service endpoints.

    The CardPointe Gateway API Integration collection also includes a sample Environment to help you get familiar with the API. 

    Click the Run in Postman button to download the CardPointe Gateway API Integration collection:

    Run in Postman

    See Running the API in Postman in the CardPointe Gateway Developer Guides for more information on using the Postman collection.

    Connecting to the Server

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

    For example:

    https://<site>.cardconnect.com/cardconnect/rest/

    This represents an HTTPS request to the REST web service base URL. The servlet name is fixed within the application; the host and port are assigned by CardConnect. 

    A username and password are required in the HTTP Authorization Header property in each API request. You can use either the site-level or MID-level API credentials that you received from CardConnect. 

    Basic Authorization is expected, using a Base64-encoded username and password string as the value. If this value is incorrect or not provided in the request header, an HTTP Exception "401:Unauthorized" is returned to the caller. 

    See the API Connectivity Guide for more information on connecting to the CardPointe Gateway and other CardConnect services.

    Testing Your API Credentials

    To test and validate site-level credentials, you can make a GET request with no body to the base URL. 

    For example:

    GET /cardconnect/rest/ 
    Host: <host>:<port>
    Authorization: Basic {base64 encoded site-level credentials}
    

    If the credentials are valid, the response returns the message "CardConnect REST Servlet." 

    To test and validate merchant-level credentials, you can make a PUT request, including the merchant ID in the body of the request, to the base URL. The Gateway verifies that the MID matches the credentials provided in the header.

    For example:

    PUT /cardconnect/rest/ 
    Host: <host>:<port>
    Authorization: Basic {base64 encoded mid-level credentials}
    Content-Type: application/json
    {
      "merchid": "496082673888"
    }

    If the credentials are valid, the response returns the message "CardConnect REST Servlet." 

    Inquire Merchant

    A GET request to the inquireMerchant endpoint returns information on the merchant account configuration. This can be 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.

    inquireMerchant Service URL

    MethodGET
    URLhttps://hostname:port/cardconnect/rest/inquireMerchant/<merchid>
    HeadersContent-Type: application/json
    Authorization: Basic

    inquireMerchant Request

    Fields in bold are required.

    FieldMax LengthTypeDescription
    merchid16NThe MID to validate against the site specified in the request URL.

    inquireMerchant Response

    The inquireMerchant response includes the status of the merchant account. 

    If the MID is valid, the response includes the following details:

    FieldMax LengthTypeDescription
    site12ANThe site that the MID is configured to use.
    cardproc4ANThe card processor that the MID is configured to use.
    enabled5ANWhether the MID is currently enabled for use. Either true or false.
    merchid16NThe MID specified in the request.

    If the MID is valid, but is not configured on the site specified in the request, the response returns the following message:

    {"message":"contact support - merchant not on site"}


    If the MID is not valid, the response returns the following message:

    {"message": "Invalid merchant"}

    Authorization

    Authorization is the initial step in accepting payment from a cardholder. This action "authorizes" or requests permission from the bank to transfer money from the cardholder to the merchant. 

    The authorization service supports a PUT or POST request that includes a JSON encoded list of fields defined for the service. The service responds with either an HTTP Exception, if there are errors, or a JSON-encoded response, if the request was successful.

    Within the response, the status of the transaction is described in the respstat value:

    • A - Approved 
    • B - Retry 
    • C - Declined

    Authorization and Capture

    Capture may take place during the authorization (see capture field in the request) or after the initial authorization is submitted. 

    If the capture request is delayed, note that authorizations usually expire after thirty days but remain on a cardholder's bank statement until they expire or are captured.

    If the request is successful, the transaction and associated line items are automatically captured for settlement.

    All fields defined for the Capture Service endpoint may be sent in the authorization request. They are only processed if the capture field is set to yes

    Additional Optional Fields

    User Fields

    You can include additional data in the authorization request for future retrieval by using optional userfields. The value of the userfields object is a series of name-value pairs that are meaningful to the merchant. 

    You can use an array or an object.

    The name and value field may be any string value and the total length of user defined fields, URL/JSON encoded is limited to 4000 bytes.

    FieldSizeTypeComments
    nameAnyANThe name of the field
    valueAnyANThe value of the field

    Example User Fields

    //object
     "userfields":
        {
            "udf0": "value0",
            "udf1": "value1",
            "udf2": "value2"
        }
    
    //array
    "userfields":
        [
            {"udf0": "value0"},
            {"udf1": "value1"},
            {"udf2": "value2"}, 
            {"custommerchant": "ABC Company"},
            {"customphone": "888-555-HELP"}
        ]

    Custom Descriptor Fields

    You can provide custom identifying information about a merchant (for example, business name or phone number) or a custom product name in an authorization request, 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.

    FieldSizeTypeComments
    custommerchant12ANMerchant name field
    customproduct12ANProduct name field
    customphone10NFormat must be ##########

    For Electronic Check (ACH) Users

    CardConnect can process electronic check transactions (ACH) through processing platforms that support it. The following fields in the authorization request are required for electronic check transactions:

    • bankaba: the routing and transit number of the check
    • account: the account number
    • ecomind: identify the Payment Origin as T: telephone or mail, R: recurring, E: ecommerce/internet

    For processors that support electronic check account verification, there are two additional fields for checking or savings account verification. Each of these fields can also be used within a Profile.

    FieldSizeTypeComments
    ssnl44NLast four digits of account social security number
    license15NDriver’s license state (two characters): number 

    For example: NY:12JKHQ123

    Example Electronic Check Request

    {
      "accttype": "ECHK",
      "merchid": "123456",
      "name": "Tyrion Lannister",
      "account": "12345678",
      "bankaba": "031000503",
      "amount" : "100",
      "capture" : "y"
    }

    Example Electronic Check Response

    {
        "amount": "100.00",
        "resptext": "Success",
        "cvvresp": "U",
        "batchid": "1000310402",
        "avsresp": "U",
        "respcode": "00",
        "merchid": "123456",
        "token": "9123456789115670",
        "authcode": "24XY8R",
        "respproc": "PSTR",
        "retref": "432101234567",
        "respstat": "A",
        "account": "9XXXXXXXXXXX5670"
    }

    For 3-D Secure Users

    Note: CardConnect supports 3-D Secure 1.0 only. 

    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.

    FieldSizeTypeComments
    secureflagAnyANECI Flag for 3DS processing
    securevalueAnyANECI Value returned from 3DS authentication
    securexidAnyANXID Value

    Authorization Service URL

    MethodPUT or POST
    URLhttps://hostname:port/cardconnect/rest/auth
    HeadersContent-Type: application/json
    Authorization: Basic

    Authorization Request

    Fields in bold are required. 

    Underlined fields can be saved to a profile, if "profile" : "y" in the request. See Profiles for more information. 

    Refer to the amount field (below) and CVV and AVS settings to execute CVV (Card Verification Value) and AVS (Address Verification System). 

    Field Max Length Type Comments
    merchid 16 N CardConnect merchant ID, required for all requests.
    amount 14 N Amount with decimal or without decimal in currency minor units (for example, USD Pennies or EUR Cents). 

    The value can be a positive or negative amount or 0, and is used to identify the type of authorization, as follows:
    • Positive - Authorization request.
    • Zero - Account Verification request. See AVS and CVV settings to enable. Account Verification is not supported for eCheck (ACH) authorizations.
    • Negative - Refund without reference (Forced Credit). Merchants must be configured to process forced credit transactions. To refund an existing authorization, use Refund.
    expiry 8 N Card Expiration in either MMYY or YYYYMMDD format. Not required for eCheck (ACH) requests.
    account 19 N Can be:
    • CardSecure Token - Retrieved from the Bolt API, CardSecure API, or the Hosted iFrame Tokenizer 
    • Clear text card number

      Note: Only PCI Level 1 and Level 2 compliant merchants should handle clear text card numbers in authorization requests. It is strongly recommended that you tokenize the clear text card data before passing it in an authorization
      request.


    • Bank Account Number - Account(s) must be entitled with electronic check capability. When using this field, the bankaba field is also required.

      See Processing ACH Payments in the CardPointe Gateway Developer Guides for more information on ACH transactions.
    Note: To use a CardConnect profile, omit the account property and supply the profile ID in the profile field instead. See Profiles for more information.
    currency3ANCurrency of merchant settlement (for example, USD for US dollars or CAD for Canadian Dollars). 
    bankaba 9 N Bank routing (ABA) number. Required for eCheck (ACH) authorizations when a bank account number is provided in the account field. bankaba is not required if a CardSecure token (generated from the account/bankaba pair) is provided in the account field.
    track 76 AN Payment card track data. Can be unencrypted Track 1 or Track 2 data, or encrypted swipe data (containing Track 1 and/or Track 2) data. See the PanPad Integration Guide (legacy) for information on capturing track data.
    receipt1AOptional, to return receipt data fields in the authorization response. 

    Specify Y to return additional merchant and authorization data to print on a receipt. 

    Defaults to if not provided.
    profile 24 AN Optional, to create an account profile or to use an existing profile.

    To create a profile using the account holder data provided in the request, specify Y.

    To use an existing profile for this authorization, omit the account parameter and instead use the profile parameter to supply the 20-digit profile id and 1-3-digit account id string in the format "<profile>/<account>".See Profiles for more information.
    capture 1 A Optional, specify Y to capture the transaction for settlement if approved.
    tokenize 1 A Optional, specify N or omit to return an account token in the account field in the response. If tokenize is Y the masked card or ACH account number is returned in the response.
    signature 6144 AN JSON escaped, Base64 encoded, Gzipped, BMP of signature data. If the authorization is using a token with associated signature data, then the signature from the token is used.
    cvv2 4 N CVV2/CVC/CID value
    name 30 AN Account name, optional for credit cards and electronic checks (ACH)
    address 30 AN Account street address (required for AVS)
    city 30 AN Account city
    postal 9 AN Account postal code, defaults to "55555". If country is "US", must be 5 or 9 digits. Otherwise any alphanumeric string is accepted.
    region 20 AN US State, Mexican State, Canadian Province
    country 2 AN Account country (2 char country code), defaults to "US". Required for all non-US addresses
    phone 15 AN Account phone
    email 128 AN Email address of the account holder
    orderid 19 AN Source system order number.

    Note: It is strongly recommended that you use a unique value to identify each sales order.
    authcode 6 AN Authorization code from original authorization (VoiceAuth). For Voice/Capture-Only, include valid authcode.
    taxexempt 1 A If taxexempt is set to 'N' for the transaction and a tax is not passed, the default configuration data is used. If taxexempt is set to 'Y', the taxamnt is $0.00. 
    termid 12 AN Terminal Device ID
    accttype 6 A One of PPAL, PAID, GIFT, PDEBIT. Otherwise, not required.
    ecomind 1 A Identifies the payment origin. Options are:
    • T - telephone or mail
    • R - recurring
    • E - ecommerce/Internet

    Authorization Response

    Field Content Max Length Comments
    respstat Status 1 Indicates the status of the authorization request. Can be one of the following values:
    • A - Approved
    • B - Retry
    • C - Declined
    retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
    account Account number 19 Either the masked payment card or eCheck (ACH) account if "tokenize” : “y” in the request OR the token generated for the account if “tokenize” : “n” or was omitted in the request.
    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 the authorization request
    respcode Response code - Alpha-numeric response code that represents the description of the response
    resptext Response text -Text description of response
    respproc Response processor4Abbreviation that represents the platform and the processor for the transaction
    bintypeType of BIN16Possible Values:
    • Corp
    • FSA+Prepaid
    • GSA+Purchase
    • Prepaid
    • Prepaid+Corp
    • Prepaid+Purchase
    • Purchase
    entrymodePOS Entry Mode25Only returned for merchants using the First Data North and RapidConnect front end platforms.

    Possible Values:
    • Keyed
    • Moto
    • ECommerce
    • Recurring
    • Swipe(Non EMV)
    • DigitalWallet
    • EMVContact
    • Contactless
    • Fallback to Swipe
    • Fallback to Keyed

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

    Field Content Max Length Comments
    avsresp AVS Response Code 2 Alpha-numeric AVS response.
    cvvresp CVV Response Code 1 Alpha-numeric CVV response.
    authcode Authorization Code 6 Authorization Code from the Issuer
    signature Signature Bitmap 6144 JSON escaped, Base64 encoded, Gzipped, BMP of signature data (via Ingenico ISC250). Returned if the authorization used a token that had associated signature data or track data with embedded signature data.
    commcard Commercial Card Flag 1 Y if a Corporate or Purchase Card
    emv Cryptogram - Authorization Response Cryptogram (ARPC). This is returned only when EMV data is present within the Track Parameter.
    emvTagDataReceipt/EMV Tag Data2000A string of receipt and EMV tag data (when applicable) returned from the processor.

    Note:
    This string is returned for both EMV and non-EMV transactions on the First Data RapidConnect (RPCT) front end platform.

    This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.

    Refer to EMV Tag Data Fields below for a list of the possible fields returned.
    receiptReceipt Data-An object that includes additional fields to be printed on a receipt.

    Refer to Receipt Data Fields below for a list of the possible fields returned.

    EMV Tag Data Fields

    The emvTagData included in the authorization response includes a string of the following fields. 

    This string is returned for both EMV non-EMV transactions on the First Data RapidConnect (RPCT) processor. 

    EMV Tag Data Array Objects

    Name Tag Details Source Format Max Length
    TVR (Terminal Verification Results) 95 Status of the different functions as seen from the terminal Terminal Binary 5
    ARC (Authorization Response Code) 8A Indicates the transaction disposition of the transaction received from the issuer for online authorizations. Issuer/Terminal String 2
    PIN (CVM Results) 9F34 Indicates the results of the last CVM performed. If PIN was entered, then "Verified by PIN" Terminal String 15
    Signature (CVM Results) 9F34 Indicates the results of the last CVM performed. If "true" then CVM supports signature and signature line may be applicable. However, card brands have moved away from requiring signature.

    Returns "unknown" if the signature requirement could not be determined.
    Terminal Binary 7
    Mode Identifies the mode used to authorize (or decline) the transaction.  Always "Issuer" CardConnect String 6
    TSI (Transaction Status Information) 9B Indicates the functions performed in a transaction Terminal Binary 2
    Application Preferred Name 9F12 Preferred mnemonic associated with the AID. If unavailable, use Application Label.  Card String 16
    Network LabelIdentifies the Authorizing Network Name, which should be printed on the receipt.IssuerString10
    AID (Application Identifier, Terminal) 9F06 Identifies the application as described in ISO/IEC 7816-5 Terminal Binary  16
    IAD (Issuer Application Data) 9F10 Contains proprietary application data for transmission to the issuer in an online transaction. Card Binary 32
    Entry method Indicator identifying how the card information was obtained.

    One of the following values:
    • Manual
    • Chip Read
    • Contactless Chip
    • Fallback Keyed
    Terminal String 11
    Application Label 50 Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use Application Preferred Name.  Card String (with the special character limited to space) 16

    Receipt Data Fields

    The receipt object provides additional merchant and authorization details for use in printing receipts. The receipt data array includes merchant account information, populated using the merchant properties configured for the MID, as well as additional transaction details from the authorization response. You can optionally include a custom order note (orderNote) and item details (items), by including a userFields object in the authorization request. 

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

    Receipt Data Array Objects

    A successful authorization response includes a receipt object with the following fields:

    FieldFormatDescription
    headerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
    footerANA customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement.
    dbaANThe merchant's Doing Business As (DBA) name.
    address1ANLine 1 of the merchant's address.
    address2ANLine 2 of the merchant's address.
    phoneNThe merchant's phone number.
    dateTimeNThe date and time of the transaction (YYYYMMDDHHMMSS).
    nameOnCardAThe Cardholder's name, if included in the authorization request.
    orderNoteANA custom order note, if included in the userFields in the authorization request.
    itemsANA custom item descriptor, if included in the userFields in the authorization request.


    Profiles

    CardConnect has the ability to store information about the account holder, called a profile. Setting the optional field profile to Y in the first authorization or account verification request creates 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 which is returned in the original authorization or profile create request. The fields stored in the profile are marked by the # in the Authorization Request fields table.

    Response Codes

    The status of the authorization is indicated by the response status (respstat) value in the authorization response

    respstatMeaning
    AApproved
    BRetry
    CDeclined

    Additional information is recorded in the other response-specific fields (respcode, respproc, etc.). For detailed information on these responses, refer to Gateway Response Codes

    Capture

    The capture service queues the transaction amount for settlement. Capture can occur within the authorization request or subsequently.

    If the amount to be captured is more than the authorized amount (such as a tip adjustment), ensure that the merchant is appropriately entitled with this capability.

    The service responds with either a JSON-encoded response or an HTTP error code.  

      Capture Service URL

      MethodPUT or POST
      URLhttps://hostname:port/cardconnect/rest/capture
      HeadersContent-Type: application/json
      Authorization: Basic

      Capture Request

      The capture request uses the Retrieval Reference Number (retref) from the original authorization request. When the amount is omitted, the original authorization amount is captured.

      Fields in bold are required. 

      Field Size Type Comments
      merchid 16 N Merchant ID, required for all requests. Must match merchid of transaction to be captured
      retref 14 N CardConnect retrieval reference number from authorization response
      authcode 6 AN Authorization code from original authorization request
      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 orderid from authorization request

      Capture Response

      Field Content Max Length Comments
      merchid Merchant ID 16 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 14 Copied from the capture request
      batchidBatch ID assigned to transaction
      12Automatically created and assigned unless otherwise specified
      setlstat Settlement status 40 One of the following values:
      • Txn not found - The retref was not found 
      • Authorized - Authorized 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 in the capture request and should be provided for corporate or purchase cards to qualify for improved interchange rates.

      Field Size Type Comments
      ponumber 36 AN Customer purchase order number
      taxamnt 12 N Tax amount either decimal or in currency minor units (for example USD Pennies or MXN Centavos). A taxamnt of zero indicates tax-exempt purchaser.

      NoteDo not send a non-zero tax amount for a tax exempt order.

      Many Level 2 protocols refer to a "Customer Code," which is described as "an identifier the customer would recognize." CardConnect populates this field with the ponumber. If the ponumber is not provided, then the orderid from the authorization request is used. If neither the ponumber or the orderid is available, the CardConnect-assigned Retrieval Reference Number ( retref) is used.

      The Level 2 protocol also requires certain merchant information, 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. These are 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 12 AN If country is "US", must be 5 or 9 digits

      Otherwise, any alphanumeric string is accepted
      shipfromzip 12 AN Same as above
      shiptocountry 2 A Ship To Country Code, default is US
      Items varies Array Array of Items

      Line Item Records

      Field Size Type Comments
      lineno 4 N Optional line number for each item. Line numbers do not need to be specified sequentially; however, if no lineno value is included, items are assigned sequential line numbers.
      material 12 AN Optional material code (also referred to as a Commodity Code) for each item. 
      description 26 AN An item description, required.
      upc 14 N Optional UPC code for each item. If upc is included, the value must not be all zeros.

      Some processors limit this value to 12 characters.
      quantity 12 N Quantity of the item purchased. Can be a whole amount or amount with up to three decimal places.
      uom 8 AN Unit of measure (for example, "each" or "ton").

      Some processors limit this value to 4 characters.
      unitcost 12 N Optional item cost, excluding tax as a decimal amount or in currency minor units (for example, USD Pennies or MXN Centavos formatted as 1.23 or 123 for $1.23).

      When omitted, this value is calculated as netamnt/quantity.
      netamnt 12 N Net total of unitcost x quantity, excluding tax and discount, as a decimal amount or in currency minor units.

      netamnt is always a positive value, even for refunds.

      Zero amounts are allowed for no-charge items, such as a manual, that are included in the order.
      taxamnt 12 N Tax amount for each item, as a decimal amount or in currency minor units. The sum total of taxamnt for all items equals the total tax amount for the order.

      The total of netamnt + taxamnt - discamnt equals the order amount.

      taxamnt must be zero or omitted if taxexempt is  and non-zero if taxexempt is Y.  
      taxexempt 1 true/false Indicates whether or not the order is tax exempt.

      taxexempt should be true if:
      • The payment card BIN type is GSA (government).

        Note: All GSA orders are set to taxexempt regardless of this setting. 
      • The merchant is a government agency.

        In this case, you must include taxexempt = true in the request for each order.
      taxexempt defaults to false.
      discamnt 12 N Optional discount amount for each item, as a decimal amount or in currency minor units.

      Void

      The void service cancels a transaction that is in either "Authorized" or "Queued for Capture" status.

      You can retrieve the status of a transaction using the inquire or inquireByOrderid endpoint. 

      The response includes a voidable field, which indicates whether or not the transaction can be voided.

      The specific transaction status is recorded in the setlstat response field. 

      The amount that can be voided depends on the settlement status of the transaction: 

      • "setlstat" : "Authorized"
        This status indicates the transaction has been authorized but not queued for capture. The entire amount or a partial amount can be voided.
      • "setlstat" : "Queued for Capture"
        Only the entire amount can be voided.

      Void Service URL

      MethodPUT or POST
      URLhttps://hostname:port/cardconnect/rest/void
      HeadersContent-Type: application/json
      Authorization: Basic

      Void Request

      Fields in bold are required.

      Field Size Type Comments
      merchid 16 N Merchant ID, required for all requests.
      Must match merchid of the transaction to be voided.
      retref14NCardConnect retrieval reference number from authorization response
      amount 12 N Optional, if omitted or equal to $0, the full amount is voided.

      If no capture has taken place (setlstat:Authorized), you can specify a partial amount to void to reduce the amount of the authorization.

      Void Response

      If the void is successful, the authcode will contain REVERS. If transaction is not found or an error occurs: 

      • respproc will contain PPS
      • respcode will contain an error code 
      • respstat will contain C indicating the transaction has declined
      • resptext will contain a relevant string
      Field Content Max Length Comments
      merchid Merchant ID 16 Retrieved from void request
      amount Amount 12 The final amount authorized after the void. 

      If the full amount was voided, the amount value in the response is 0.00.

      If a partial amount was voided, the amount value in the response is the difference between the original authorization amount and the amount voided.
      currency Currency 3 From the original authorization request
      retref Retrieval reference number 14 Retrieved from void request
      authcode Authorization code 6 Identifies if the void was successful. Can one of the following values: 
      • REVERS - Successful
      • Null - Unsuccessful. Refer to the respcode and resptext.
      respcode Response code 3 Alpha-numeric response code that represents the description of the response
      respproc Response processor 4 Abbreviation that represents the platform and the processor for the transaction
      respstat Response status 1 Indicates the status of the request. Can be one of the following values:
      • A - Approved
      • B - Retry
      • C - Declined
      resptext Response text 40 Text description of response

      Refund

      The refund service is used for transactions that are in a settled status.

      You can refund a specific transaction using the retrieval reference number (retref) provided in the authorization response. 

      You can retrieve the status of a transaction using the inquire or inquireByOrderid endpoint.

      The response includes a refundable field, which indicates whether or not the transaction can be refunded.

      The specific transaction status is recorded in the setlstat field.

      Some banks impose maximum time limits (for example, 6 months) to perform a refund using a retref

      If you do not have a retref for the transaction, you can return funds to an account by passing a negative amount (forced credit) in an authorization and subsequent capture request. 

      Refund Service URL

      MethodPUT or POST
      URLhttps://hostname:port/cardconnect/rest/refund
      HeadersContent-Type: application/json
      Authorization: Basic

      Refund Request

      Fields in bold are required.

      Field Size Type Comments
      merchid 16 N Merchant ID, required for all requests
      amount 12 N Positive amount with decimal or amount without decimal in currency minor units (for example, USD Pennies or MXN Centavos) for partial refunds.

      If no value is provided, the full amount of the transaction is refunded. 
      retref 14 N Retrieval Reference Number from original authorization

      Refund Response

      If the transaction is found, the response values (resproc, respcode, respstat, resptext) will contain the result of the request. If the transaction is not found or an error occurs:

      • respproc will contain PPS
      • respcode will contain an error code 
      • respstat will contain C indicating the transaction has declined
      • resptext will contain a description of the error 

      Refer to Response Codes for more information on these values. 

      Refunds are automatically approved by CardConnect and submitted in the settlement.

      Field Content Max Length Comments
      merchid Merchant ID 16 Copied from refund request
      amount Amount 12 Copied from refund request, contains the refund amount
      retref Retrieval reference number 14 New retref of refund transaction
      respcode Response code 3 Alpha-numeric response code that represents the description of the response
      respproc Response processor 4 Abbreviation that represents the platform and the processor for the transaction
      respstat Response status 1 A - Approved
      B - Retry
      C - Declined
      resptext Response text 40 Text description of the response

      Inquire 

      The inquire service returns information for an individual transaction, including its settlement status (setlstat) and the response codes from the initial authorization. 

      Inquire Service URL

      MethodGET
      URLhttps://hostname:port/cardconnect/rest/inquire/<retref>/<merchid>
      HeaderAuthorization: Basic

      Inquire Request

      Fields in bold  are required.

      FieldContentMax LengthComments
      merchidMerchant ID16From the original authorization
      retrefRetrieval Reference Number14From the original authorization

      Inquire Response

      Field Content Max Length Comments
      merchid Merchant ID 12 The Merchant ID, copied from the Inquire request
      account Account number 25 Copied from original authorization, masked in response
      amount Amount to capture 12 Copied from original authorization
      currency Currency of amount 3 Copied from original authorization
      retref Retrieval reference number 12 Copied from inquire request
      respcode Response code 4 Copied from original authorization response
      respproc Response processor 4 Copied from original authorization response
      respstat Response status 1 Copied from original authorization response
      resptext Response text 40 Copied from original authorization response
      batchid Batchid assigned to transaction 12 Present if transaction was captured
      setlstat Settlement Status 40 The settlement status of the transaction.

      Possible values are:
      • Authorized - Authorized but not captured
      • Queued for Capture – Queued for the processor 
      • Accepted - Accepted by the processor 
      • Rejected - Rejected by the processor
      • Zero Amount – Transaction was $0 
      • Voided – Transaction has been voided
      • Declined – Transaction had an error
      capturedateCapture date and time14YYYYMMDDHHMMSS
      settledateSettlement date and time14YYYYMMDDHHMMSS
      signature Signature Bitmap 6144 JSON escaped, Base64 encoded, Gzipped, BMP of signature data (via Ingenico ISC250). Returned if the authorization used a token that had associated signature data or track data with embedded signature data.
      token token varies Token copied from the original authorization request
      profileid20 digit profile ID20Primary identifier to access profiles. Present if transaction utilized a stored profileid. 
      acctid3 digit account ID3Account identifier within a profile. Present if transaction utilized a stored profileid. 
      entrymodePOS Entry Mode25The card number entry method used by the POS terminal. This data is only returned for merchants on the First Data North platform.

      Possible values are:
      • K - Keyed
      • T - Moto
      • E - ECommerce
      • R - Recurring
      • S - Swipe (Non EMV)
      • W - DigitalWallet
      • V - EMVContact
      • L - Contactless
      • F - Fallback to Swipe 
      • Y - Fallback to Keyed
      authdateAuthorization Date8YYYYMMDD
      lastfourLast four of token/card number4Last 4 digits of the token and card number. 
      nameAccount name30The account name, if returned in the track data.
      bintypeType of BIN16The type of card, based on the BIN.

      Possible values are:
      • Corp
      • FSA+Prepaid
      • GSA+Purchase
      • Prepaid
      • Prepaid+Corp
      • Prepaid+Purchase
      • Purchase
      emvTagDataEMV tag data2000A string of EMV data returned from the processor when an EMV card is used. This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.

      Refer to EMV Tag Data for a list of the possible fields returned
      receiptReceipt Data-An object that includes additional fields to be printed on a receipt.

      Refer to Receipt Data for a list of possible fields returned.

      See Printing Receipts Using Authorization Data for detailed information on customizing the receipt data fields and printing receipts.
      userfield [0..9]Custom Field20A valued passed by the merchant with the original authorization to further identify the transaction (see the userfields description under the Authorization Service).
      voidableVoid Indicator1Indicates whether the transaction can be voided in its current state.

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

      If Y, the transaction can be voided.

      If N, the transaction cannot be voided.
      refundableRefund Indicator1Indicates whether the transaction can be refunded in its current state.

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

      If Y, the transaction can be refunded.

      If N, the transaction cannot be refunded.

      Inquire By Order ID

      Similarly to the inquire endpoint, requests to the inquireByOrderid endpoint return information for an authorization; however, inquireByOrderid references the Order ID associated with the transaction instead of the retrieval reference number (retref). 

      This allows you to get information about a transaction if the original authorization was interrupted and no response was returned, including the retref (if one was generated).

      It is strongly recommended that you use a unique order ID for every transaction, if you are using order IDs. Doing so allows you to more easily and accurately retrieve data on all transactions.

      Inquire By Order ID Service URL

      MethodGET
      URLhttps://hostname:port/cardconnect/rest/inquireByOrderid/<orderid>/<merchid>/<set>
      HeaderAuthorization: Basic

      Inquire By Order ID Request

      This request returns all transactions for the specified merchant ID (MID), using the specified Order ID. 

      Specify 1 for the set parameter to restrict the inquiry to the specified MID. 

      If you have multiple MIDs and do not know which MID was used in the original transaction, you can omit the set parameter from the end of the request to optionally inquire on the order ID across all MIDs on the site.

      Fields in bold are required.

      FieldContentMax LengthComments
      merchidMerchant ID14From the original authorization
      orderidOrder ID19From the original authorization
      set1 or blank1set to 1 to restrict the inquiry to the merchant ID (MID) specified in the request. If you have multiple MIDs and want to search for the order ID across all MIDs, omit this parameter.

      Inquire By Order ID Response

      The inquireByOrderid response includes the following fields:

      If the specified Order ID was used in multiple authorization attempts (for example, to retry a declined transaction), then the InquireByOrderID response returns each transaction record for the Order ID.

      Field Content Max Length Comments
      amountAmount to capture12Copied from the original authorization
      resptextResponse text40Copied from the original authorization
      setlstatSettlement Status40Values are: 
      • Authorized – Authorized only, not captured 
      • Queued for Capture – Queued for the processor 
      • Accepted - Accepted by the processor 
      • Rejected - Rejected by the processor
      • Zero Amount – Transaction was $0 
      • Voided – Transaction has been voided
      • Declined – Transaction had an error
      respcodeResponse code4Copied from the original authorization
      merchidMerchant ID12Copied from the original authorization
      tokentokenvariesCopied from the original authorization
      respprocResponse processor4Copied from the original authorization
      authdateAuthorization Date8YYYYMMDD
      lastfourLast four of token/card number4Last 4 digits of the token and card number. 
      nameAccount name30Account name, if returned in the track data.
      currencyCurrency of amount3Copied from the original authorization
      retrefRetrieval reference number12Copied from the inquireByOrderId request
      respstatResponse status1Copied from the original authorization
      accountAccount number25Masked value, copied from the original authorization
      emvTagDataEMV tag data2000A string of EMV data returned from the processor when an EMV card is used. This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference.

      Refer to EMV Tag Data for a list of the possible fields returned
      receiptReceipt Data-An object that includes additional fields to be printed on a receipt.

      Refer to Receipt Data for a list of possible fields returned.

      See Printing Receipts Using Authorization Data for detailed information on customizing the receipt data fields and printing receipts.
      userfield [0..9]Custom Field20A valued passed by the merchant with the original authorization to further identify the transaction (see the userfields description under the Authorization Service).
      voidableVoid indicator1Indicates whether the transaction can be voided in its current state.

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

      If Y, the transaction can be voided.

      If N, the transaction cannot be voided.
      refundableRefund indicator1Indicates whether the transaction can be refunded in its current state.

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

      If Y, the transaction can be refunded.

      If N, the transaction cannot be refunded.

      Void By Order ID

      The voidByOrderId endpoint is used to look up and void a transaction record using the order ID supplied in the original authorization request. If the order ID supplied in a voidByOrderId request matches a transaction record for the specified merchant, the authorization is voided and a response is returned.

      voidByOrderId can be used in the event that no response is returned by an inquireByOrderId request, when you are unsure of a transaction's status. It's recommended to call voidByOrderId three times (3x) if no response was returned by either an inquireByOrderid request or the initial auth request.

      It is strongly recommended that you use a unique order ID for every transaction, if you are using order IDs. Doing so allows you to more easily and accurately retrieve data on all transactions.

      Void By Order ID Service URL

      MethodPUT or POST
      URLhttps://hostname:port/cardconnect/rest/voidByOrderId/
      HeadersContent-Type: application/json
      Authorization: Basic

      Void By Order ID Request

      Fields in bold are required.

      FieldContentMax LengthComments
      merchidMerchant ID14From the original authorization
      orderidOrder ID19From the original authorization

      Void By Order ID Response

      If the void is successful, the authcode will contain REVERS. If transaction is not found or an error occurs:

      • respproc will contain PPS
      • respcode will contain an error code
      • respstat will contain C indicating the transaction has declined
      • resptext will contain a relevant string
      FieldContentMax LengthComments
      merchidMerchant ID16Retrieved from void request
      amountAmount12The final amount authorized after the void.

      If the full amount was voided, the amount value in the response is 0.00.

      If a partial amount was voided, the amount value in the response is the difference between the original authorization amount and the amount voided.
      currencyCurrency3From the original authorization request
      retrefRetrieval reference number14Retrieved from void request
      authcodeAuthorization code6Identifies if the void was successful. Can one of the following values:
      • REVERS - Successful
      • Null - Unsuccessful. Refer to the respcode and resptext.
      respcodeResponse code3Alpha-numeric response code that represents the description of the response
      respprocResponse processor4Abbreviation that represents the platform and the processor for the transaction
      respstatResponse status1Indicates the status of the request. Can be one of the following values:
      • A - Approved
      • B - Retry
      • C - Declined
      resptextResponse text40Text description of response

      Settlement Status

      For the settlement status of an individual transaction that has not been settled, use the inquire service. 

      The settlement status service returns the status of transactions which have been submitted to the processor for settlement. The transaction’s setlstatus is updated appropriately when CardConnect’s receives a response from the processor. You can either specify a batchid to return a specific batch of transactions, or use a date to return all transactions settled for that date. 

      "Null Batches" is returned when no data is available for display. When passing the merchid as the only parameter,  only batches not previously requested are shown. If the merchid has previously been queried for batches, responses will contain only batches not previously returned.

      Settlement Service URL

      MethodGET
      URLhttps://hostname:port/cardconnect/rest/settlestat?
      Query Parameters
      • merchid=<merchid>&date=<MMDD>

        Queries all settled transactions by date.


      • merchid=<merchid>&batchid=<batchid>

        Queries all settled transactions by batch ID.
      HeaderAuthorization: Basic

      The merchid parameter is required in all instances.

      Settlement Response

      Field Content Max Length Comments
      batchid Batch ID 12 Copied from the capture request
      hoststat Batch settlement status 2 One of the values below:
      • Blank – Queued for the processor
      • BB – The batch was rejected by the processor.
      • EB - The batch was empty (contains no valid transactions).
      • GB – The batch was accepted by the processor.
      • MB – Some transactions were accepted and some were rejected.
      • RB - The batch was not processed.
      • SB - The batch was sent to the processor, but not yet confirmed.
      • ND - The batch was sent to the processor, but no confirmation was received during the applicable timeout window. This status can indicate a bad batch or a communication error.
      hostbatch Host batch ID 16 The batch identifier assigned by the payment processor.
      merchid Merchant ID 16 Merchant ID
      respproc Clearing House 4 CardConnect abbreviation for Clearing House
      txns Array of transactions -- Array of retref / setlstat pairs 

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

      Field Content Max Length Comments
      retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
      setlamountAmount Settled12The transaction amount settled for the authorization
      salesdoc Additional Field / Order ID 50 Optional additional field for Order ID or similar
      setlstat Settlement status 1 One of the values below: 

      A - Authorized
      D - Declined
      - Queued for Capture
      - Accepted
      - Rejected
      - Zero Amount
      - Voided
      - Token Decrypt
      - Format Error
      - Amount Under Review
      - Pin Debit

      Refer to Settlement Status Response Values for more information. 

      Settlement Status Response Values

      The setlstat field can contain one of the following responses: 

      ValueRepresentsDescription
      AAuthorizedThe authorization was approved but has not been captured.
      DDeclinedThe authorization was rejected, but the order cannot be captured.
      RQueued for captureThe authorization was approved and captured but has not been sent to settlement.
      YAcceptedThe batch was sent, and the transaction has been accepted for overnight processing.
      NRejectedThe batch was sent, but the transaction was rejected.

      Contact Support if you encounter this status.
      ZZero amountUsually returned for a $0 validation.
      VVoidedThe authorization was voided.
      TToken DecryptThe batch process was unable to decrypt the token.

      Contact Support if you encounter this status.
      FFormat errorThe batch process was unable to format the request.

      Contact Support if you encounter this status.
      WAmount under reviewFirst Data North/Rapid Connect batch response. Usually approves the next day.
      PPin DebitVantiv Pin debit was not sent in the batch to avoid duplicate charge.

      Funding

      The funding endpoint provides merchant funding information supported by supplemental transaction and funding adjustment detail. This information is provided by the host payment processing platform (for example, First Data Omaha). All data within response is provided to CardConnect 1-2 days following the merchant's activity.

      The funding service can be queried by merchant ID and Date which returns all matching funding data in an array of funding, transaction (txn) and adjustment records each with a structure containing funding data.

      The 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 Service URL

      MethodGET
      URLhttps://hostname:port/cardconnect/rest/funding?
      Query Parametersmerchid=<merchid>&date=<MMDD>
      HeaderAuthorization: Basic

      Funding Response

      Each funding service request returns three JSON arrays (txns, fundings, and adjustments) along with other fields that help identify information about the funding.

      Funding data is only available for merchants with the "funding" service configured and enabled in the CardConnect production environment.

      The following table describes each property/node in the object provided in the Funding response.

      Field Size Type Comments
      fundings varies Data Array This array represents information about the deposit executed.

      See fundings Node for more information.
      txns varies Data Array This array represents all the transactions funded for the given date provided.

      See txns Node for more information.
      adjustments varies Data Array Amounts credited to or deducted from account to resolve processing or billing discrepancies.

      See adjustments Node for more information.
      chargebacksvariesData ArrayThis array represents all the chargebacks for the given date provided. The chargebacks node is only available for merchants configured to obtain this data.

      See chargebacks Node for more information.
      fundingdate 8 Funding Date YYYY-MM-DD The date of the bank funding event.
      merchid 16 N The merchant account ID related to the funding event.
      datechanged 8 Date YYYY-MM-DD The date the record was last updated.
      fundingmasterid 22 Funding Master ID Unique key for an aggregated merchant's daily funding.

      fundings Node

      Field Content Max Length Comments
      fundingmasterid Funding Master ID 22 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. 

      Refer to the Response Appendix (Currency Codes) for possible field values. 
      ddanumber DDA Number 20 Masked demand deposit account number
      abanumber ABA Number 20 American Bankers Association (ABA) that identifies the bank
      fundingid N 22 Unique key identifier for merchants with daily funding activity
      datechanged Date YYYY-MM-DD 8 The date when the record was last updated
      dateadded Date YYYY-MM-DD 8 The date when the transaction was created
      deposittrancodeDeposit Transaction Code10
      depositachtracenumberDeposit ACH Trace Number20

      txns Node

      Field Content Max Length Comments
      fundingtxnid Transaction ID 22 The fundingmasterid associated with the transaction
      retref Gateway ID 30 Gateway retrieval 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

      Refer to the Response Appendix (Card Type) for possible field values. 
      cardbrand Card Brand 30 The brand associated to the card

      Refer to the Response Appendix (Card Brand) for possible field values. 
      amount Amount 12 The transaction amount
      currency Currency Code 10 Three character currency code associated to transaction 

      Refer to the Response Appendix (Currency Codes) for possible field values. 
      date Date 8 Date the transaction occurred
      type Type 25 Type of transaction Processed

      Refer to the Response Appendix (Transaction Type) for possible field values. 
      status Type 100 Status of transaction Funding

      Refer to the Response Appendix (Transaction Status) for possible field values. 
      userfield [0..9] Custom Field 20 A valued passed by the merchant with the original authorization to further identify the transaction (see "userfields" within the Authorization Service).
      fundingid Funding Identifier 22 CardConnect unique key identifier for merchant transaction funding activity.
      plancode10
      downgradereasoncodesDowngrade Reason Codes100
      invoicenumberInvoice NumberNum
      sourcetransactionidSource Transaction ID100
      terminalnumberTerminal Number10
      achreturncodeACH Return Code5
      parentretrefParent Retrieval Reference Number30

      adjustments Node

      FieldContentMax LengthComments
      fundingadjustmentidFunding Adjustment ID22CardConnect unique system identifier for adjustment
      fundingmasteridFunding Master ID22Unique key for an aggregated merchant's daily funding
      merchidMID25Merchant identifier assigned by host
      categoryAdjustment Group100Category of deposit adjustment 

      Refer to the Response Appendix (Adjustment Group) for possible field values. 
      typeAdjustment Group Description100Type of deposit adjustment
      descriptionAdjustment Description200Detailed description of adjustment
      amountAdjustment Amount12Amount of adjustment
      currencyCurrency Code10Three digit code identifying the funded currency

      Refer to the Response Appendix (Currency Code) for possible field values. 
      datechangedDate YYYY-MM-DD8The date when the record was last updated
      dateaddedDate YYYY-MM-DD8The date when the transaction was created

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

      chargebacks Node

      Chargeback data is only applicable to specific clients that have been configured appropriately.

      FieldContentMax Length
      depositdateDate YYYY-MM-DD8
      amountThe Chargeback amount20, 2 dec
      transactiondateDate YYYY-MM-DD8
      reasondescriptionChargeback description200
      reasoncodeChargeback reason code4
      datechangedDate Changed YYYY-MM-DD8
      sourcetransactionidSource Transaction ID100
      transactionamountThe Transaction amount20, 2 dec
      chargebackdateDate of Chargeback YYYY-MM-DD8
      sequencenumberChargeback Sequence Number30
      dateaddedDate Added YYYY-MM-DD8
      merchidMerchant ID30
      authcodeAuthorization code8
      fundingmasteridFunding Master ID22
      fundingchargebackidFunding Chargeback ID
      casenumberChargeback Case Number30
      acquirereferencenumberAcquirer Reference Number30
      cardnumberMasked Card Number30
      retrefRetrieval Reference Number, CardConnect Transaction ID30
      invoicenumberTransaction Invoice Number

      Response Appendix

      Card Type Responses

      See below for a legend of possible return values for the cardtype field. 

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

      Card Brand Responses

      See below for a legend of possible return values for the cardbrand field. 

      Card BrandDescription
      MCMasterCard
      VISAVisa
      DSCVDiscover
      UNKNUnknown
      AMEXAmerican Express
      WEXWright Express
      VYGRVoyager
      TELTelecheck
      DNRDiners
      JCBJapan Credit Bureau
      BMLBill Me Later
      RMRevolution Money

      Currency Code Responses

      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.

      Transaction Type Responses

      See below for a legend of possible return values for the type field. 

      Transaction TypeDescription
      SALESale or ticket-only sale.
      REFUNDCredit back of a sale due to a return or refund.
      CASH ADVANCECash Advance
      VOID SALEVoid a sale or ticket-only sale or a cash advance.
      VOID REFUNDVoid a return or refund.
      AUTH REQUESTAuthorization request.
      ACCOUNT VERIFYAccount verification.
      UNKNOWNSource data transaction type not mapped.

      Transaction Status Responses

      See below for a legend of possible return values for the status field. 

      Transaction StatusDescription
      AuthThe credit card authorization request was processed successfully.
      CapturedThe credit card authorization was captured, and the request was processed successfully by the payment processor.
      VoidedA deletion of the transaction information.
      FailureThe credit card (authorization, capture, or credit) or check (debit or credit) request failed.
      RejectedA rejection of the transaction information due to duplicate transaction or fraud protection.
      DeclinedA response from the card issuer denying the use of the card for the attempted transaction.
      SettledThe check debit or credit request was processed successfully.
      UnknownTransaction status not supplied.

      Adjustment Group Responses

      See below for a legend of possible returns for the category field.

      Adjustment GroupAdjustment Group Detail
      ADJUSTMENTSDEPOSIT ADJUSTMENTS
      ADJUSTMENTSFINANCIAL ADJUSTMENTS
      ADJUSTMENTSAGENT BANK
      ADJUSTMENTSCASH ADVANCE ADJUSTMENT
      ADJUSTMENTSCOST OF FUNDS
      ADJUSTMENTSDEPOSIT ADJUSTMENTS
      FEESFEES
      FEESADDRESS VERIFICATION
      FEESAUTHORIZATIONS
      FEESACCOUNT MANAGEMENT FEES
      FEESWS INFO. MGR.
      FEESCHARGEBACK TRANSACTION PROCESSING
      FEESDEBIT
      FEESDATA CAPTURE
      FEESCES IMAGE
      FEESEQUIPMENT
      FEESCOMMUNICATION
      FEESCASH ADVANCE
      FEESCES LINK
      FEESCHECK SERVICES
      FEESFUNDS TRANSFER
      FEESSUPPLIES
      FEESFOREIGN HANDLING
      FEESREPORT
      FEESCES TRANSLINK
      FEESUSAVE
      INTERCHANGE CHARGESINTERCHANGE CHARGES
      INTERCHANGE CHARGESINTERCHANGE
      INTERCHANGE CHARGESASSESSMENT
      INTERCHANGE CHARGESNON-QUAL TRANSACTIONS
      INTERCHANGE CHARGESAGENT INTERCHANGE
      INTERCHANGE CHARGESINTERCHANGE/ASSESSMENT ADJ.
      INTERCHANGE CHARGESDEBIT
      REVERSALCHARGEBACKS/CHARGEBACK REVERSALS
      REVERSALDEBIT ADJUSTMENTS
      REVERSALDEBIT ADJUSTMENT REVERSAL
      SERVICE CHARGESSERVICE CHARGES
      SERVICE CHARGESSERVICE CHARGE ADJUSTMENTS
      SERVICE CHARGESDEBIT SERVICE CHARGE
      THIRD PARTYTHIRD PARTY ADJUSTMENTS
      OTHER ADJUSTMENTOTHER ADJUSTMENT

      Profile

      A profile can consist of multiple sets of profile account data. Each set is assigned an account ID, which can be used in conjunction with the profile ID to access a specific account. The format is <profile ID>/<account ID> 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 account ID 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 profile ID and optional account ID. One account ID in each profile can be marked as the default account. The default account will be used for all authorization requests when only the profile ID is supplied. If an account ID is present the service retrieves the existing profile and updates it, or returns profile not found.

      A profile can be associated with a maximum of 998 payment records (active/inactive).

      Profile Service URLs

      The profile service provides three methods.

      MethodURLHeaders
      PUT or POST
      (Create/Update)

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

      Refer to Create/Update Profile Request.
      Content-Type: application/json
      Authorization: Basic
      GEThttps://<hostname>:<port>/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>

      If the account ID is omitted, then all accounts in the profile are returned.

      Refer to Get Profile Request.
      Authorization:Basic
      DELETEhttps://<hostname>:<port>/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>

      If the account ID is omitted, then all accounts in the profile are deleted.

      Refer to Delete Profile Request.
      Content-Type: application/json
      Authorization: Basic

      Create/Update Profile Request

      A PUT or POST call to the profile endpoint creates a new profile or adds a new account to an existing profile. 

      The service tokenizes the account property and creates the profile with a token and profile ID and optional account ID. If the profile includes multiple accounts, one account ID in the profile can be marked as the default account by setting the defaultacct parameter to "Y." The default account will be used for all authorization requests when only the profile ID is supplied. 

      In addition to creating a new profile, you can use this service to do the following:

      • To update a profile, include an existing profile ID in the request. The service retrieves the existing profile and updates it with the values in the request. 
      • To update an account, include an existing profile ID and account ID pair in the request. The service retrieves the existing account data and updates it with the values in the request.
      • To add an account to an existing profile, include an existing profile ID and the new payment account data in the request. The service retrieves the existing profile and adds a new acctid containing the values in the request.

      Create/Update Profile Request URL

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

      Fields marked with an asterisk (*) are copied from the Authorization request.

      Field Size Type Comments
      profile 20+ N 20-digit profile ID and (optional) 3-digit account ID string in the format <profile id>/<account id>
      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
      auoptout 1 A Specifies whether or not the profile is set to opt out of the CardPointe Account Updater service.
      • Y = Yes (updates are not retrieved for this profile)
      • N = No (updates are retrieved for this profile)
      accttype 6 A One of PPAL, PAID, GIFT, PDEBIT, otherwise not required
      merchid* 16 N Merchant ID, required for all requests
      account* 19 N Can be:
      • CardSecure Token - Retrieved from the authorization response, Bolt API, CardSecure API, or the Hosted iFrame Tokenizer 
      • Clear-text card number
      • Bank Account Number - Account(s) must be entitled with electronic check capability. When using this field, the bankaba field is also required.
      bankaba 9 N Bank routing (ABA) number, ECHK only
      expiry 8 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 3 AN Account country (2 character country code)
      phone 15 AN Account phone (required for ECHK, SAV)
      postal 10 AN Account postal code
      if country is "US", must be 5 or 9 digits
      otherwise any alphanumeric string is accepted
      company128ANCompany name associated with the account
      email 128 AN E-Mail address of the account holder
      license 16 N Driver’s license state (2 characters) and number in the format <state>:<number>.
      For example, NY:12JKHQ123

      Create/Update Profile Response

      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
      token 19 AN The token included in the request. If a card number or bank account number was included in the request, returns a new token generated for that account. 
      respcode 3 A Alpha-numeric response code that represents the description of the response
      resptext 40 A Text description of response
      respproc 4 A Abbreviation that represents the platform and the processor for the transaction
      accttype 6 A The value supplied in account creation; VISA, MC, DISC, ECHK.
      expiry 8 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 3 AN Account country (2 character country code)
      phone 15 AN Account phone (required for ECHK, SAV)
      postal 10 AN Account postal code
      - if country is "US", must be 5 or 9 digits
      - otherwise any alphanumeric string is accepted
      email 128 AN Email address of the account holder
      company128ANCompany name associated with the account
      defaultacct 1 A Y marks the default account referenced when a profile ID is used without an associated account ID
      license 16 N Driver’s license state (2 characters) and number in the format <state>:<number>.
      For example, NY:12JKHQ123
      gsacard 1 A Identifies if the card is a government issued card
      auoptout 1 A Identifies whether or not the profile is set to opt out of the CardPointe Account Updater service.
      • Y = Yes (updates are not retrieved for this profile)
      • N = No (updates are retrieved for this profile)

      Get Profile Request

      A GET request to the profile endpoint returns the stored data for the specified profile ID. 

      If the profile includes more than one account, you can specify an account ID to retrieve data for a specific account. If you do not include an account ID, then data for all accounts in the profile is returned in the response.

      Get Profile Request URL

      https://<hostname>:<port>/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>

      Fields in bold are required.

      Field Size Type Comments
      profile ID 20 N Primary identifier to access profiles
      account ID 3 N Account identifier within a profile
      merchid 16 N CardConnect merchant ID (MID) required in all requests.

      Get Profile Response

      Field Size Type Comments
      profileid 20 N Primary identifier to access profiles
      acctid 3 N Account identifier within a profile
      accttype 6 A The value supplied in account creation; VISA, MC, DISC, ECHK.
      token19NThe token associated with the account.
      expiry 8 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 3 AN Account country (2 character country code)
      postal 10 AN Account postal code
      - if country is "US", must be 5 or 9 digits
      - otherwise any alphanumeric string is accepted
      company128ANCompany name associated with the account
      defaultacct 1 A Y marks the default account referenced when a profile ID is used without an associated account ID
      license 16 N Driver’s license state (2 characters) and number in the format <state>:<number>.
      For example, NY:12JKHQ123
      auoptout 1 A Identifies whether or not the profile is set to opt out of the CardPointe Account Updater service.
      • Y = Yes (updates are not retrieved for this profile)
      • N = No (updates are retrieved for this profile)
      gsacard 1 A Identifies whether the card is government issued.

      Delete Profile Request

      A DELETE request to the profile endpoint deletes the stored data for the specified profile ID. 

      If the profile includes more than one account, you can specify an account ID to delete data for a specific account. If you do not include an account ID, then data for all accounts in the profile is deleted.

      Delete Profile Request URL

      https://<hostname>:<port>/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>

      Fields in bold are required.

      Field Size Type Comments
      profile ID 20 N Primary identifier to access profiles
      account ID 3 N Account identifier within a profile
      merchid 16 N CardConnect merchant ID (MID) required in all requests.

      Delete Profile Response

      Field Size Type Comments
      resptext 20 A Profile delete request status
      respcode 6 N Response code assigned by CardConnect on the delete request
      respproc 6 A Response processor - Always PPS for a profile delete request
      respstat 1 A Response status:
      A = Approved
      C = Not found

      Signature Capture

      This signature capture service augments an existing authorization record with the provided signature data. The signature can then be retrieved via the inquire service.

      Signature Capture Service URL

      MethodPUT or POST
      URLhttps://hostname:port/cardconnect/rest/sigcap
      HeadersContent-Type: application/json
      Authorization: Basic

      Signature Capture Request

      Fields in bold are required.

      Field Size Type Comments
      merchid 12 N Merchant ID, required for all requests
      retref 12 N CardConnect retrieval reference number from authorization response
      signature 6146 AN JSON Encoded, Base64 Encoded, GZipped, BMP (200x100px) image. Omit to erase an associated signature.

      Signature Capture Response

      Field Type Comments
      resptext AN Response text
      respcode N Response code (02 - success, 03 - failure)
      retref N Provided retref
      merchid N Provided merchid

      Bin

      The Bin service allows you to use a CardConnect token to determine what type of payment card is being used. The first six (6) digits of a credit card are known as the Bank Identifier Number (BIN), also known as a Issuer Identification Number (IIN). The bin service provides this detail using a merchant’s ID and the CardConnect token. This service currently supports Visa, Mastercard, and Discover card brands.

      The REST verb GET is used for this service, which returns a JSON response containing the issuer information for the card submitted.

      Bin Service URL

      MethodGET
      URLhttps://hostname:port/cardconnect/rest/bin/<merchid>/<token>
      HeaderAuthorization: Basic

      Bin Response

      Field Type Comments
      country A Issuer country of origin
      product A Card type, one of the following:
      • A = Amex
      • D = Discover
      • M = Mastercard
      • N = Not Valid
      • V = Visa
      cardusestring A General usage type, one of the following:
      • Credit Hybrid (meaning it has pin capability also)
      • PIN Only Debit with Electronic Benefit Transfer
      • Debit Hybrid (PIN and Signature)
      • USA Commercial Debit, Signature Only, No PIN Access
      • USA Commercial Debit, PIN Capable
      • Non USA Consumer Debit, No PIN Access
      • Non USA Commercial Debit, No PIN Access
      • Non USA Consumer Debit, PIN Capable
      • Non USA Commercial Debit, PIN Capable
      • PIN Only Debit without Electronic Benefit Transfer
      • Private Label Credit (MasterCard)
      • Signature only Debit, No PIN Access
      • True credit, No PIN/Signature capability
      gsa boolean True
      False
      corporate boolean True
      False
      fsa boolean True
      False
      subtype A Detailed subtype of card, blank if not available.
      purchase boolean True
      False
      prepaid boolean True
      False
      binlo N The low end of the BIN range that includes the card’s BIN value. Masked after the first six (6) digits.
      issuer A Card issuing bank/institution
      binhi N The high end of the BIN range that includes the card’s BIN value. Masked after the first six (6) digits.

      Bin Missing or Error Response

      Field Type Comments
      success boolean True = successful request, but no BIN information available.
      False = an error occurred during the request
      errormsg A Reason for error