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.

REST Implementation

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

  • GET operations are used for inquiry requests, specifically the Inquire and Settlement Status services.
  • The POST and DELETE verbs are not used or implemented by CardConnect.
  • Unless otherwise specified, PUT operations are required for each service.
  • 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.

Connecting to the Server

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

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

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

A GET or PUT request with no arguments to the address above returns a simple text/html "CardConnect REST Servlet" response if proper credentials are provided.

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

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 of a JSON encoded list of the response fields defined for the service. The service responds with either an HTTP Exception if there are errors or a JSON-encoded response if it was 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 in an authorization request (for example, business name, phone number, city and/or state) which appears on buyers’ credit/debit card statements. 

See your sales person for feature availability and merchant configuration. Once configured add UserField entries for each piece of custom data to be replaced.

FieldSizeTypeComments
custommerchant12ANMerchant name field
customproduct12ANProduct name field
customstate2A2 digit state abbreviation
customphone10NFormat must be ##########
custompostal5N5 digit postal

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 3D Secure Users

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

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

Authorization Service URL

MethodURLHeaders
PUThttps://hostname:port/cardconnect/rest/authContent-Type: application/json
Authorization: Basic

Authorization Request

Fields in bold are required. 

Fields with a # indicate these fields can be used as part of a profile. Refer to Profiles

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

Field Size Type Comments
merchid 12 N Merchant ID, required for all requests
amount 12 N Amount with decimal or without decimal in currency minor units (i.e. USD Pennies, EUR Cents),

This value identifies the authorization type: 

Positive
- Authorization request

Zero
Account Verification request. See AVS and CVV settings to enable. Account Verification is not available for ECHK transaction types

Negative
Refund without reference (Forced Credit). Merchants must be enabled for forced credit. When referencing an existing authorization, use Refund.
expiry# 4 N Card Expiration in either MMYY or YYYYMMDD format, not required for ECHK
account# 19 N Can be:

CardSecure Token
Retrieved from the 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.

Note: To use a CardConnect profile, omit the account property and supply the profileid. See Profiles.
currency3ANCurrency of merchant settlement
(USD for US dollars, CAD for Canadian Dollars, etc.) 
bankaba 9 N Bank routing (ABA) number, Required for eChecks.
track 76 AN Unencrypted Track1 OR unencrypted Track2 OR encrypted swipe data (containing Track1 and/or Track2) data. Refer to legacy Authorization with Ingenico Track Data
profile 1 or 16 AN Optional, Y to create an account profile upon initial authorization. 20 digit numeric profileid / acctid (optional) to utilize a profile when account account is omitted. See Profiles.
acctid 3 N Account identifier within a profile, specifies unique token
capture 1 A Optional, Y to capture the transaction for settlement if approved
tokenize 1 A Optional, Y to return an account token in token response field
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# 30 AN E-Mail address of the account holder
orderid 19 AN Source system order number. Strongly encouraged to populate this field with a unique value that can identify the 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 default tax rate is used.
termid 30 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 Len Comments
respstat Status 1 A - Approved
B - Retry
C - Declined
retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
account Account number 19 Copied from request, masked
token (if requested) Token 19 A token that replaces the card number in capture and settlement requests if requested
amount Amount 12 Authorized amount. Same as the request amount for most approvals. The amount remaining on the card for prepaid/gift cards if partial authorization is enabled. Not relevant for declines.
merchid Merchant ID 12 Copied from request
respcode Response code - 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 on the First Data North/RapidConnect platform.
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 Len 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 authorization used a token which had associated signature data or track 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.
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 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. 

EMV Tag Data Array Objects

Name Tag Details Source Format Max Len
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 authorisations. Issuer/Terminal an 2 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. Terminal Boolean 5
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 b 2
Application Preferred Name 9F12 Preferred mnemonic associated with the AID. If unavailable, use Application Label.  Card ans 1-16
AID (Application Identifier, Terminal) 9F06 Identifies the application as described in ISO/IEC 7816-5 Terminal binary 40-128 5-16
IAD (Issuer Application Data) 9F10 Contains proprietary application data for transmission to the issuer in an online transaction. Card binary 0-32
Entry Method Indicator identifying how the card information was obtained. Terminal String 11
Application Label 50 Mnemonic associated with the AID according to ISO/IEC 7816-5. If unavailable, use Application Preferred Name.  Card ans with the special character limited to space 1-16

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 and 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

    MethodURLHeaders
    PUThttps://hostname:port/cardconnect/rest/captureContent-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 Len 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 values below:

    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 (i.e. USD Pennies, MXN Centavos), 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" 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 ponumberor the orderid is available, the CardConnect-assigned Retrieval Reference Number ( retref) is used.

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

    Capture Level 3 Data

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

    Level 3 data includes additional Order Level items such as freight and discount amount, as well as information from each line item of the order. 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 Order line number
    material 16 AN Material number (also referred to as Visa Commodity Code)
    description 32 AN Material description
    upc 14 N Material UPC code
    quantity 12 N Quantity of material purchased, decimal or whole units
    uom 8 AN Unit of measure (such as quart, ton)
    unitcost 12 N Amount with decimal or in currency minor units
    netamnt 12 N Amount with decimal or in currency minor units
    taxamnt 12 N Tax Amount either decimal or in currency minor units (i.e. USD Pennies, MXN Centavos)

    taxamnt of zero indicates tax-exempt purchaser 

    Note: Do not send a non-zero tax amount for a tax exempt order
    discamnt 12 N Amount with decimal 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 service. The 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

    MethodURLHeaders
    PUThttps://hostname:port/cardconnect/rest/voidContent-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.
    Can be used to reduce the authorized amount if no capture event has taken place. 

    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 Len Comments
    merchid Merchant ID 16 Retrieved from void request
    amount Amount 12 Retrieved from void request
    currency Currency 3 From the original authorization request
    retref Retrieval reference number 14 Retrieved from void request
    authcode Authorization code 6 This value identifies if the void was successful: 

    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 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. 

    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 returns funds to an account by passing a negative amount (forced credit) in an authorization and subsequent capture request. 

    Refund Service URL

    MethodURLHeaders
    PUThttps://hostname:port/cardconnect/rest/refundContent-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 (i.e. USD Pennies, 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 describe 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 Len 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

    MethodURLHeaders
    GEThttps://hostname:port/cardconnect/rest/inquire/retref/merchidContent-Type: application/json 
    Authorization: Basic

    Inquire Request

    Fields in bold  are required.

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

    Inquire Response

    Field Content Max Len Comments
    merchid Merchant ID 12 Copied from inquire request
    account Account number 25 Masked from original authorization
    amount Amount to capture 12 From original authorization
    currency Currency of amount 3 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 Values 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 – Txn was $0
    Voided – Transaction has been voided
    Declined – Transaction had an error
    settledateSettlement Date14YYYYMMDDHHMMSS
    signature Signature Bitmap 6144 JSON escaped, Base64 encoded, Gzipped, BMP of signature data (via Ingenico ISC250). Returned if authorization used a token which had associated signature data or track 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 cardconnect profileid. 
    acctid3 digit account ID3Account identifier within a profile. Present if transaction utilized a stored cardconnect profileid. 
    entrymodePOS Entry Mode25Only returned for merchants on the First Data North platform.
    Possible Values:

    Keyed: "K"
    Moto: "T"
    ECommerce: "E"
    Recurring: "R"
    Swipe = "S" (Non EMV)
    DigitalWallet =    "W"
    EMVContact = "V"
    Contactless = "L"
    Fallback to Swipe = "F" 
    Fallback to Keyed="Y"
    authdateAuthorization Date8YYYYMMDD
    lastfourLast four of token/card number4Last 4 digits of the token and card number. 
    bintypeType of BIN16Possible Values:
    Corp
    FSA+Prepaid
    GSA+Purchase
    Prepaid
    Prepaid+Corp
    Prepaid+Purchase
    Purchase

    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 Status Response Values

    The setlstat field can contain one of the following responses: 

    ValueRepresentsDescription
    AAuthorizedAuthorization approved but has not been captured.
    DDeclinedAuthorization rejected, order can't be captured
    RQueued for captureApproved authorization has been captured  but has not been sent to settlement
    YAcceptedBatch sent and transaction has been accepted for overnight processing
    NRejectedBatch sent but the transaction was rejected
    ZZero amountUsually $0 validation
    VVoidedAuthorization was voided
    TToken DecryptThe batch process was unable to decrypt token
    FFormat errorThe batch process unable to format request
    WAmount under reviewFirst Data North/Rapid Connect batch response. Usually approves the next day.
    PPin DebitVantiv Pin debit not sent in batch to avoid duplicate charge

    Settlement Service URL

    MethodReturnsURLHeaders
    GETAll settled transactions for a specified datehttps://hostname:port/cardconnect/rest/settlestat?merchid=<merchid>&date=<MMDD>Content-Type: application/json
    Authorization: Basic
    GETAll settled transactions for specified batchhttps://hostname:port/cardconnect/rest/settlestat?merchid=<merchid>&batchid=<batchid>Content-Type: application/json
    Authorization: Basic

    The merchid parameter is required in all instances.

    Settlement Response

    Field Content Max Len Comments
    batchid Batch ID 12 Copied from the capture request
    hoststat Settlement status 2 One of the values below:

    Blank – Queued for the processor
    GB – Accepted by the processor
    MB – Some transactions accepted/some rejected
    BB – Rejected by the processor
    EB - Empty batch. The batch contains no valid transactions.
    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 Len Comments
    retref Retrieval reference number 12 CardConnect retrieval reference number from authorization response
    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 Fields

    Field Content Max Len Comments
    setlamount Amount Settled 12 The transaction amount settled for the authorization
    salesdoc Additional Field / Order ID 50 Optional additional field for Order ID or similar

    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 (i.e. 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.

    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

    MethodURLHeaders
    GEThttps://hostname:port/cardconnect/rest/funding?merchid=<merchid>&date=<MMDD>Content-Type: application/json
    Authorization: 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.
    txns varies Data Array This array represents all the transactions funded for the given date provided.
    adjustments varies Data Array Amounts credited to or deducted from account to resolve processing or billing discrepancies.
    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 Len 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 Len Comments
    fundingtxnid Transaction ID 22 CardConnect ID for each record
    retref Gateway ID 30 CardConnect gateway reference number (aka RetRef)
    interchangeunitfee Interchange unit fee 12 Unit based fee charged for acceptance of card transaction
    interchangepercentfee Interchange percent fee 12 Percentage based fee charged for acceptance of card transaction
    date Transaction Date 8 Date the transaction occurred
    cardnumber Card Number 25 Masked card number used for transaction
    cardtype Card Type 20 Type of card used for transaction

    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

    Field Content Max Len Comments
    fundingadjustmentid Funding Adjustment ID 22 CardConnect unique system identifier for adjustment
    fundingmasterid Funding Master ID 22 Unique key for an aggregated merchant's daily funding
    merchid MID 25 Merchant identifier assigned by host

    Refer to the Response Appendix (Adjustment Group) for possible field values. 
    category Adjustment Group 100 Category of deposit adjustment

    Refer to the Response Appendix (Adjustment Group) for possible field values. 
    type Adjustment Group Description 100 Type of deposit adjustment
    description Adjustment Description 200 Detailed description of adjustment
    amount Adjustment Amount 12 Amount of adjustment
    currency Currency Code 10 Three digit code identifying the funded currency

    Refer to the Response Appendix (Currency Code) for possible field values. 
    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

    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 Len
    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 acctid which can be used in conjunction with the profileid to access a specific account. The format is (profileid/acctid) for use in each request’s profile field. One account in each profile will be marked as the default account and will be referenced when no acctid is supplied.

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

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

    Profile Service URLs

    The profile service provides three methods.

    MethodURLHeaders
    PUT
    (Create/Update)

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

    Refer to Profile Create/Update.
    Content-Type: application/json
    Authorization: Basic
    GEThttps://hostname:port/cardconnect/rest/profile/profileid/acctid/merchid

    If acctid is omitted, then all accounts will be returned.

    Refer to Profile Get.
    Content-Type: application/json
    Authorization:Basic
    DELETEhttps://hostname:port/cardconnect/rest/profile/profileid/acctid/merchid

    If acctid is omitted, then all accounts will be deleted.

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

    Profile Create/Update Request

    Field Size Type Comments
    profile 20+ N 20 digit profileid/(optional) 3 digit acctid
    defaultacct 1 A "Y" to assign as default account
    profileupdate 1 A "Y" to update profile data with non-empty request data only as opposed to full profile replacement including empty values
    accttype 6 A One of PPAL, PAID, GIFT, PDEBIT, otherwise not required
    merchid* 16 N Merchant ID, required for all requests
    account* 19 N Tokenized card number for payment card
    Bank account number for ECheck
    Masked in response
    bankaba 9 N Bank routing (ABA) number, ECHK only
    expiry 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
    ssnl4 4 N Last four digits of account social security number
    email 128 AN E-Mail address of the account holder
    license 16 N Driver’s license state (two Characters) + : + number,
    For example NY:12JKHQ123

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

    Profile Create/Update Response

    Field Size Type Comments
    profileid 20 N Primary identifier to access profiles
    acctid 3 N Account identifier within a profile
    respstat 1 A A - Approved
    B - Retry
    C - Declined
    account 19 AN Copied from request, masked
    respcode 3 A Alpha-numeric response code 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
    ssnl4 4 N Last four digits of account social security number
    email 128 AN E-Mail address of the account holder
    defaultacct 1 A Y marks the default account referenced when profileid is used without an acctid specified
    license 16 N Driver’s license state (two Characters) + : + number,
    For example NY:12JKHQ123
    gsacard 1 A Identifies if the card is a government issued card
    auoptout 1 A Account Updater Opt Out. Disables the Card Account Updater service.
    Y = Yes
    N = No

    Profile Get Request

    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.
    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
    defaultacct 1 A Y marks the default account referenced when profileid is used without an acctid specified
    license 16 N Driver’s license state (two Characters) + : + number,
    For example NY:12JKHQ123
    auoptout 1 A Account Updater Opt Out. Disables the Card Account Updater service.
    Y = Yes
    N = No
    gsacard 1 A Identifies whether the card is government issued.

    Profile Delete 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

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

    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

    MethodURLHeaders
    PUThttps://hostname:port/cardconnect/rest/sigcapContent-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

    Open Batch

    The openBatch service opens a new batch associated the supplied merchid. The batchsource value is intended to allow merchants to supply a client cross-merchid batch identifier to logically link multiple CardConnect batches together. A CardConnect batch contains one merchid. Use caution when attempting to use batchsource to link batches together. CardConnect does not validate or use the value and it is possible for more batches to be grouped if the same batchsource is used by mistake. A batchsource sent in openBatch must match that sent in the Capture service for a transaction to be placed into that batch manually.

    The REST verb GET is used for this service, which returns a JSON response containing the batchid for a new open batch.

    Open Batch Service URL

    MethodURLHeaders
    GEThttps://hostname:port/cardconnect/rest/openbatch/merchid/batchsourceContent-Type: application/json
    Authorization: Basic

    openBatch Response

    Field Type Comments
    respcode AN A success or fail response. If the batch is successfully opened, the value "success" is returned. If the request was not successfully processed, the value "noBatch" is returned.
    batchsource AN References the batchid of a third-party system. A CardConnect batch ID contains one Merchant ID. Use caution when attempting to use batchsource to link batches together. CardConnect does not validate the value and it is possible for more batches to be grouped if the same batchsource is used accidentally. A batchsource sent in openBatch must match that sent in the Capture service.

    Close Batch

    The closeBatch service attempts to close the batch identified by the merchid and batchid. Optionally provide the batchid to attempt to close a specific batch. If no batchid is supplied, the open batch with the lowest batchid is closed.

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

    Close Batch Service URL

    MethodURLHeaders
    GEThttps://hostname:port/cardconnect/rest/closebatch/merchid/batchidContent-Type: application/json
    Authorization: Basic

    closeBatch Response

    Field Type Comments
    respcode AN A success/fail response. If the batch is successfully closed, the value "success" is returned. If the request was not successfully processed, the value "noBatch" is returned. This may mean the request batch does not exist or is already closed.
    batchid AN The Batch ID of the closed batch. If the value "null" is returned, the request was not successfully processed.

    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 know 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

    MethodURLHeaders
    GEThttps://hostname:port/cardconnect/rest/bin/merchid/tokenContent-Type: application/json
    Authorization: Basic

    Bin Response

    Field Type Comments
    country A Issuer country of origin
    product A Card Type:

      ‘V’ = Visa
      ‘M’ = Mastercard
      ‘D’ = Discover
    cardusestring A General usage type, one of the following:

      Debit, no EBT
      Debit with EBT
      Credit hybrid
      Debit hybrid
      Signature only
      True credit
      Debit Comm, no PIN
      Debit Comm with PIN
      MC private label
    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 Masked card value showing first six (6) digits of the account.
    issuer A Card issuing bank/institution
    binhi N Masked card value showing first six (6) digits of the account

    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