Overview
The CardPointe Gateway API allows you to securely accept a wide-range of credit, debit, and alternative payments.
The CardPointe Gateway API allows you to securely accept a wide-range of credit, debit, and alternative payments.
To get started with the CardPointe Gateway API, review the Integration Process Overview for helpful information for testing and integrating the API.
Visit Statuspage and click subscribe to updates to receive important release and status notifications.
An update to the CardPointe Gateway was released to the UAT environment on 10/23/2023 and has been deployment to the production environment on 11/9/2023.
This release includes the following updates in addition to internal fixes and enhancements:
Refund requests must include the Merchant ID (MID) used in the original authorization request. If the refund includes a different MID, or a null value, then the request returns an error as seen in the example below. See the Refund Requirement Update for more information.
{ "respproc": "PPS", "resptext": "Txn not found", "retref": "198096236590", "respcode": "29", "respstat": "C" }
The surcharge endpoint has been added to determine whether or not a surcharge fee will be applied to a transaction, based on the cardholder's postal code and payment method. This allows your application to notify the cardholder of the potential credit card surcharge prior to completing a transaction.
This request does not effect whether or not a surcharge is applied to a transaction; the CardPointe Gateway automatically applies a surcharge depending on the merchant configuration and the eligibility of the payment account. This request is used only for informational purposes.
For more information on credit card surcharging, see the Merchant Surcharge Program overview.
{ "token": "CREDIT", "postal": "NOT_RESTRICTED", "messages": [] }
The authcode
field is now included in the API response for the /refund endpoint for both online and offline refunds. For online refunds the authcode
returned by the processor will be included in the response. For auto-approved (offline) refunds, the "authcode":"REFUND"
is returned in the response. The following example displays an online refund authorization response:
{ "authcode": "PPS655", "respproc": "AMEX", "amount": "3.00", "resptext": "Approval", "retref": "270110240566", "respstat": "A", "respcode": "000", "merchid": "831831831901" }
See the Refund Authorization overview for more information on online refunds.
When making an authorization request with a stored profile, the profile field will no longer accept a token; instead, you must include the profile ID and account ID pair to authorize a transaction.
An update to the CardPointe Gateway is tentatively scheduled for release to the UAT environment on 8/18/2023 and to the Production environment on 8/26/2023.
This release includes the following updates in addition to internal fixes and enhancements:
Refund requests must include the Merchant ID (MID) used in the original authorization request. If the refund does not include the same MID, or a null value, then the request returns an error; for example:
{ "respproc": "PPS", "resptext": "Txn not found", "retref": "198096236590", "respcode": "29", "respstat": "C" }
When an incorrect endpoint URL is called a new error response is returned that displays the incorrect URL passed in the request. For example, the path below has a spelling error:
{ "timestamp": "2023-06-20T15:04:43.980+00:00", "status": 404, "error": "Not Found", "path": "/cardconnect/rest/inquireByOderid" }
The CardPointe Gateway API uses RESTful web services to implement create, read, update, and delete (CRUD) functions.
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.
All request parameters are case-sensitive, as documented in the API.
The CardPointe Gateway API returns all response data in JSON. Updates to the API are backwards compatible, and we reserve 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.
The following resources are available to simplify your integration.
Our Developer Guides provide additional information for integrating the CardPointe Gateway and related products and services.
You can browse the whole library at the Developer Guides home page, or jump right to the CardPointe Gateway Developer Guides to make the most of your CardPointe Gateway API integration.
To help you get started with your integration, we created 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:
See Running the API in Postman in the CardPointe Gateway Developer Guides for more information on using the Postman collection.
Your application communicates with the CardPointe Gateway RESTful web service using the following URL:
https://<site>.cardconnect.com/cardconnect/rest/<endpoint>
A username and password are required in the HTTP Authorization Header property in each API request using the API credentials provided for your merchant account.
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 CardPointe services.
To test and validate your API 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: <site>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."
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 CardPointe merchant IDs or for businesses with merchants operating in multiple locations, to ensure that the merchant ID is boarded to the correct site.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/inquireMerchant/<merchid> |
Headers | Content-Type: application/json Authorization: Basic |
Fields in bold are required.
Field | Max Length | Type | Description |
---|---|---|---|
merchid | 16 | N | The MID to validate against the site specified in the request URL. |
The inquireMerchant response includes the status of the merchant account.
If the MID is valid, the response includes the following details:
Field | Max Length | Type | Description |
---|---|---|---|
acctupdater | 1 | AN | Specifies whether or not the MID is enrolled in the Card Account Updater service. Possible values are:
|
avs | 1 | AN | Specifies whether or not AVS validation is enabled for the MID. Possible values are:
Y , the MID can perform $0 authorizations to validate the postal and address values in the auth request. |
cardproc | 4 | AN | The card processor that the MID is configured to use. |
cvv | 1 | AN | Specifies whether or not CVV validation is enabled for the MID.
If |
echeck | 1 | AN | Specifies whether or not the MID is configured to process eCheck/ACH transactions.
If |
enabled | 5 | AN | Specifies whether the MID is currently enabled for use. Possible values are:
|
fee_format | 7 | AN | Specifies the surcharge fee format. Possible values are:
|
fee_merchid | 16 | N | Specifies the linked MID used for processing transactions with surcharge enabled. if not applicable, this field is returned as an empty string. |
fee_type | 1 | AN | Specifies whether the merchant has convenience or surcharge fees enabled. Possible values are:
|
fee_value | - | N | Specifies the fee value configured for the MID, where the value is either a percentage or flat amount, used to calculate the fee for each transaction. |
merchid | 16 | N | The MID specified in the request. |
site | 12 | AN | The site that the MID is configured to use. |
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"}
The surcharge endpoint is used to determine whether or not a surcharge fee will be applied to a transaction, based on the cardholder's postal code and payment method. This allows your application to notify the cardholder of the potential credit card surcharge prior to completing a transaction.
This request does not affect whether or not a surcharge is applied to a transaction; the CardPointe Gateway automatically applies a surcharge depending on the merchant configuration and the eligibility of the payment account. This request is used only for informational purposes.
For more information on credit card surcharging, see the Merchant Surcharge Program overview.
This endpoint only accepts a tokenized credit or debit account in the request.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/surcharge?merchid=<MID>&token=<token>&postal=<cardholder postal> |
Headers | Content-Type: application/json Authorization: Basic |
Field | Max Length | Type | Description |
merchid | 16 | N | The merchant ID (MID) used to process the transaction. |
postal | 9 | AN | The cardholder's postal code used to verify that the cardholder's state supports surcharging. Optional if |
token | 19 | N | The tokenized account number used to verify that the card type is eligible for surcharging. Optional if |
Field | Content | Max Length | Type | Description |
messages | An array of one or more detailed response messages | 28 | A | Empty ( Otherwise, an array with one or more of the following objects:
|
postal | Postal restriction indicator | 14 | A | Whether or not the cardholder's location allows surcharging. One of the following:
|
token | Card type restriction indicator | 7 | A | The card type identified by the token. One of the following:
|
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:
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 seven (7) days. Pending authorizations display as holds or pending transactions on a cardholder's account 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, including Level 2 and Level 3 transaction details, may be sent in the authorization request; however, they are only processed if "capture" : "y"
in the request.
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 fields can include any string value, and you can include as many fields as necessary; however, the total length of user defined fields, URL/JSON encoded, is limited to 4000 bytes, where 1 character is equal to 1 byte.
If you use the CardPointe web application for transaction reporting, you must ensure that you pass your custom fields in an array, in the order that they are configured in the CardPointe application to ensure that the fields are populated correctly in the Transactions table. If there is no value for a field, you must include the field with an empty value (for example, "udf1":""
) to preserve the expected order of the fields. If you pass the fields in an object, the order will not be preserved.
Field | Size | Type | Comments |
---|---|---|---|
name | Any | AN | The name of the field |
value | Any | AN | The value of the field |
//object "userfields": { "udf0": "value0", "udf1": "value1", "udf2": "value2" } //array "userfields": [ {"udf0": "value0"}, {"udf1": "value1"}, {"udf2": "value2"}, {"custommerchant": "ABC Company"}, {"customphone": "888-555-4357"} ]
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.
Field | Size | Type | Comments |
---|---|---|---|
custommerchant | 12 | AN | Merchant name field |
customproduct | 12 | AN | Product name field |
customphone | 10 | N | Format must be ########## |
The CardPointe Gateway can supports electronic check transactions (ACH) for merchants boarded to a supported ACH services platform (for example ProfitStars).
See Processing ACH Payments in the CardPointe Gateway Developer Guides, for detailed information and requirements for processing ACH transactions on the ProfitStars platform.
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/auth |
Headers | Content-Type: application/json Authorization: Basic |
Notes:
Fields in bold are required.
Underlined fields can be saved to a profile, if "profile" : "y"
in the request. See Profiles for more information.
Note: If the authorization request fails or is declined, the profile is not created.
Most fields in the authorization request correspond to columns on the CardPointe application's Transactions table. See the CardPointe Web App User's Guide for more information.
Field | Max Length | Type | Comments |
---|---|---|---|
merchid | 16 | N | CardPointe 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:
|
expiry | 8 | N | Card expiration in one of the following formats
|
account | 19 | N | Can be:
account property and supply the profile ID in the profile field instead. See Profiles for more information. |
postal | 9 | AN | The account holder's postal code. If country is "US", must be 5 or 9 digits. Otherwise any alphanumeric string is accepted. Defaults to "55555" if not included in the request or stored profile. Note: It is strongly recommended that your application prompts for postal code for card-not-present transactions to prevent fraud and downgrades, and to avoid declines on the CardPointe Gateway if the AVS verification option is enabled for your merchant account. |
cvv2 | 4 | N | The 3 or 4-digit cardholder verification value (CVV2/CVC/CID) value present on the card. Note: It is strongly recommended that your application prompts for CVV for card-not-present transactions for fraud prevention and to avoid declines on the CardPointe Gateway if the CVV verification option is enabled for your merchant account. |
ecomind | 1 | A | A transaction origin indicator, for card-not-present and eCheck (ACH) transactions only. For ProfitStars ACH transactions, see Making an ACH Authorization Request for more information. For card-not-present transactions, one of the following values:
Note: You should include the appropriate |
cof | 1 | AN | Required for initial and subsequent transactions using stored cardholder payment information. The Specify one of the following values:
See the Visa and Mastercard Stored Credential Transaction Framework support article for detailed information and requirements for using the |
cofpermission | 1 | AN | Optionally, when Specify one of the following values:
Defaults to N if not provided. |
cofscheduled | 1 | AN | Required for transactions using stored cardholder payment information. For a merchant-initiated transaction (MIT), the Specify one of the following values:
See the Visa and Mastercard Stored Credential Transaction Framework support article for detailed information and requirements for using the cof and cofscheduled fields. |
currency | 3 | AN | Currency of the authorization (for example, USD for US dollars or CAD for Canadian Dollars). Note: If specified in the auth request, the currency value must match the currency that the MID is configured for. Specifying the incorrect currency will result in a "Wrong currency for merch" response. |
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 captured using a supported card reader device (for example, a desktop card reader device). Can be unencrypted Track 1 or Track 2 data, or encrypted swipe data (containing Track 1 and/or Track 2) data. |
receipt | 4 | A | Optional, to return receipt data fields in the authorization response to print on a receipt. Specify one of the following values:
|
bin | 1 | A | Optional, to return BIN lookup fields in the authorization response. Specify Y to retrieve the BIN data for the card. Defaults to N if not provided. |
profile | 24 | AN | Optional, to create a stored customer profile or to use an existing profile. To create a profile using the account holder data provided in the request, specify Y.
Note: If the authorization request fails or is declined, the profile is not created. 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 Note: You can submit a $0 authorization, including CVV and AVS verification, to validate the customer's information before creating a profile. |
auoptout | 1 | A | Optional, when creating a profile, to specify whether or not the profile is set to opt out of the Card Account Updater service. Requires the merchant account to be enrolled in the Card Account Updater add-on. Specify one of the following values:
Defaults to N if not provided. |
capture | 1 | A | Optional, specify Y to capture the transaction for settlement if approved. Defaults to N if not provided. Note: When |
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. |
name | 30 | AN | Account holder's name, optional for credit cards and electronic checks (ACH). |
company | 128 | AN | Account holder's company name. |
address | 30 | AN | Account holder's street address, required for AVS verification. |
address2 | 30 | AN | Second address line (for example, apartment or suite number) if applicable. |
city | 30 | AN | Account holder's city. |
region | 20 | AN | Account holder's region, US State, Mexican State, Canadian Province |
country | 2 | AN | Account holder's country (2-character country code), defaults to "US". Required for all non-US addresses |
phone | 15 | AN | Account holder's phone number. |
128 | AN | Account holder's email address. | |
orderid | 50 | AN | Source system order number. Note:If you include an order ID it must meet the following requirements:
|
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. |
taxamnt | 12 | N | Tax amount for the order, either decimal or in currency minor units (for example, USD Pennies or MXN Centavos). If taxexempt is Y, taxamnt must be zero or omitted. If taxexempt is N, taxamnt must be a positive, non-zero value. |
termid | 8 | AN | The Terminal Device ID, required when the Send Terminal ID for Reporting feature is enabled for First Data ClientLine Reporting.termid must be exactly 8 characters long, and the last 5 characters (used to display on the report) must be numbers.Note: This field is not used for CardPointe transaction reporting. |
accttype | 6 | A | The account type, not required unless one of the following:
|
A successful authorization response returns the following fields for an approved or declined authorization:
Field | Content | Max Length | Comments |
---|---|---|---|
respstat | Status | 1 | Indicates the status of the authorization request. Can be one of the following values:
|
retref | Retrieval reference number | 12 | The unique retrieval reference number, used to identify and manage the transaction. |
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. |
expiry | Expiration Date | 4 | The payment card expiration date, in MMYY format, if expiry was included in the request. |
token | Token | 19 | The tokenized account number, which can be used in profile, capture, and settlement requests. |
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. |
orderId | Order ID | 50 | The The If no |
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 processor | 4 | Abbreviation that represents the platform and the processor for the transaction |
cof | Stored Credential Transaction Indicator | 1 | Returns the cof value, if included in the authorization request. One for the following values:
|
avsresp | AVS Response Code | 2 | Alpha-numeric AVS (zip code) verification response code. Note: avsresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account. |
cvvresp | CVV Response Code | 1 | Alpha-numeric CVV (card verification value) verification response code, if returned by the processor. One of the following values:
cvvresp is typically only returned for approved authorizations, however this field can be returned in the response for a declined authorization if this setting is enabled for the merchant account. |
binInfo | BIN service response | - | An array that includes the fields returned in the BIN response. |
bintype | Type of BIN | 16 | Possible Values:
|
entrymode | POS Entry Mode | 25 | Possible Values:
|
fee_amount | 14 | N | a fee amount (for example a credit card surcharge amount) applied to the transaction, in dollars and cents. |
fee_authcode | 6 | N | Duplicate of the authcode field included if the transaction included a fee (for example, a credit card surcharge). |
fee_format | 7 | AN | The fee format configured for the merchant account (for example, "percent" ). |
fee_merchid | - | - | The merchant ID used to process a fee. If not applicable or the same as the transaction merchant ID, returns an empty value ("" ). |
fee_retref | - | - | The unique retrieval reference number for a fee. If not applicable or the same as the transaction retref, returns an empty value ("" ). |
fee_type | 13 | AN | The type of fee applied to the transaction. |
fee_value | 3 | N | The fee rate applied to the transaction with decimal implied (for example "300" for a 3% rate. |
declineCategory | Visa Decline Category Code | 1 | A numeric decline category code, only returned for declined transactions using Visa accounts. See Visa Decline Rules and Responses for detailed information on handling Visa declines. One of the following values:
|
declineCategoryText | Visa Decline Category Code Description | 25 | A text description to provide more information on the decline. One of the following:
|
Additionally, the following fields are returned for approved authorizations.
Field | Content | Max Length | Comments |
---|---|---|---|
authcode | Authorization Code | 6 | Authorization Code from the Issuer |
signature | Signature Bitmap | 6144 | JSON escaped, Base64 encoded, Gzipped, BMP of signature data. 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. |
emvTagData | Receipt/EMV Tag Data | 2000 | A string of receipt and EMV tag data (when applicable) returned from the processor. This data returned should be presented on a receipt if applicable, and recorded with the transaction details for future reference. See EMV Tag Data Fields, below, for a list of the possible fields returned. Note: This string is returned for both EMV and non-EMV transactions on the First Data RapidConnect (RPCT) front end platform. |
receipt | Receipt Data Array | - | Returned when the request includes "receipt":y" . A stringifed array that includes additional fields to be printed on a receipt. See Receipt Data Fields, below, for a list of the possible fields returned. |
receiptObj | Receipt Data Object | - | Returned when the request includes "receipt":json" . Additional fields to be printed on a receipt. receiptObj includes additional details not included in the receipt string. See Receipt Data Fields, below, for a list of the possible fields returned. |
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.
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" | CardPointe Gateway | 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 Label | Identifies the Authorizing Network Name, which should be printed on the receipt. | Issuer | String | 10 | |
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:
| Terminal | String | 26 | |
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
and receiptObj
provide additional merchant and authorization details for use in printing receipts. The receipt data 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.
Expand the following topics to review the contents and examples of the receipt
and receiptObj
data.
receiptObj
includes the same fields as the receipt
string, as well as additional fields duplicated from the emvTagData
array.
The receipt
string includes the following fields:
Field | Format | Description |
---|---|---|
header | AN | A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement. |
footer | AN | A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement. |
dba | AN | The merchant's Doing Business As (DBA) name. |
address1 | AN | Line 1 of the merchant's address. |
address2 | AN | Line 2 of the merchant's address. |
phone | N | The merchant's phone number. |
dateTime | N | The date and time of the transaction (YYYYMMDDHHMMSS). |
nameOnCard | A | The Cardholder's name, if included in the authorization request. |
orderNote | AN | A custom order note, if included in the userFields in the authorization request. |
items | AN | A custom item descriptor, if included in the userFields in the authorization request. |
receipt Example
"receipt": "{\"dateTime\":\"20210113154743\",\"dba\":\"receipt Test North2\",\"address2\":\"DENVER\",\"phone\":\"123-456-7890\",\"footer\":\"\",\"nameOnCard\":\"CC TEST\",\"address1\":\"Street\",\"orderNote\":\"\",\"header\":\"\",\"items\":\"\"}"
The receiptObj
string includes the following fields:
Each field is only returned when a value is present, otherwise the field is omitted from the object.
Field | Format | Description |
address1 | AN | Line 1 of the merchant's address. |
address2 | AN | Line 2 of the merchant's address. |
Application Label | AN | Duplicated from the emvTagData object. Mnemonic associated with the AID according to ISO/IEC 7816-5. |
dateTime | N | The date and time of the transaction (YYYYMMDDHHMMSS). |
dba | AN | The merchant's Doing Business As (DBA) name. |
emv | JSON Object | An object that returns the following fields, when present, duplicated from the emvTagData object:
|
Entry Method | AN | Duplicated from the emvTagData object.
Indicator identifying how the card information was obtained.
|
footer | AN | A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement. |
header | AN | A customizable field to display an alphanumeric message. For example, a specific terms, disclosure, or cardholder agreement statement. |
items | AN | A custom item descriptor, if included in the userFields in the authorization request. |
Mode | AN | Duplicated from the emvTagData object. Identifies the mode used to authorize (or decline) the transaction. Always Issuer . |
nameOnCard | AN | The Cardholder's name, if included in the authorization request. |
orderNote | AN | A custom order note, if included in the userFields in the authorization request. |
phone | N | The merchant's phone number. |
PIN | AN | Duplicated from the emvTagData object. Indicates the results of the last CVM performed. If PIN was entered, then "Verified by PIN" |
Signature | AN | Duplicated from the emvTagData object. 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. |
receiptObj Example
"receiptObj": {\"dateTime\":\"20210113154743\",\"dba\":\"RapidConnect Retail\",\"PIN\":\"Verified by PIN\",\"address2\":\"DENVER\",\"phone\":\"123-456-7890\",\"footer\":\"\",\"nameOnCard\":\"CC TEST\",\"address1\":\"Street\",\"Mode\":\"Issuer\",\"Network Label\":\"AMEX\",\"Entry Method\":\"Chip Read\",\"Application Label\":\"AMEX 2\",\"emv\":{\"TVR\":\"0000008001\",\"AID\":\"A0000000042203\",\"IAD\":\"0110A0000F040000010203040506070809FF0102030405060708090A0B0C0D0E\"}}"
The CardPointe Gateway 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.
The status of the authorization is indicated by the response status (respstat
) value in the authorization response.
respstat | Meaning |
---|---|
A | Approved |
B | Retry |
C | Declined |
Additional processor response information is returned in the respcode
and respproc
fields. See Gateway Response Codes for detailed information.
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.
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/capture |
Headers | Content-Type: application/json Authorization: Basic |
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 | CardPointe 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 (for example, USD Pennies or MXN Centavos) |
invoiceid | 12 | AN | An optional invoice ID. |
receipt | 1 | A | Optional, to return receipt data fields in the response. Specify Y to return additional merchant and transaction data to print on a receipt. Defaults to N if not provided. |
Field | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 16 | Copied from the capture request |
account | Account number (masked) | 19 | Masked account number |
authcode | Authorization Code | 6 | Authorization Code from the Issuer |
orderId | Order ID | 50 | The The If no |
amount | Amount to capture | 12 | The amount included in the capture request. |
retref | Retrieval reference number | 14 | The retref included in the capture request. |
batchid | Batch ID assigned to transaction | 12 | Automatically created and assigned unless otherwise specified |
commcard | Commercial Card Flag | 1 | Y if a Corporate or Purchase Card |
setlstat | Settlement status | 40 | The current settlement status. The settlement status changes throughout the transaction lifecycle, from authorization to settlement. The following values can be returned in the capture response: Note: See Settlement Status Response Values for a complete list of setlstat values.
|
receipt | Receipt 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. |
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 for the order, either decimal or in currency minor units (for example, USD Pennies or MXN Centavos). If taxexempt is Y, taxamnt must be zero or omitted. If taxexempt is N, taxamnt must be a positive, non-zero value. |
Many Level 2 protocols refer to a "Customer Code," which is described as "an identifier the customer would recognize." The CardPointe Gateway 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 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.
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). The unitcost should not be greater than the amount for the order.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.If taxexempt is Y, taxamnt must be zero or omitted. If taxexempt is N, taxamnt must be a positive, non-zero value. |
taxexempt | 1 | AN | Indicates whether or not the order is tax exempt.taxexempt should be Y if:
taxexempt defaults to N. |
discamnt | 12 | N | Optional discount amount for each item, as a decimal amount or in currency minor units. |
The void service cancels a transaction that is in either "Authorized" or "Queued for Capture" status.
Partial voids are not supported for debit transactions. If you specify a partial void amount for a debit transaction, the entire amount is voided. Omit the amount or specify the full amount for a debit void.
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 setlstat
field in determines the amount that can be voided, where:
"setlstat" : "Authorized"
"setlstat" : "Queued for Capture"
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/void |
Headers | Content-Type: application/json Authorization: Basic |
Fields in bold are required.
Field | Size | Type | Comments |
---|---|---|---|
merchid | 16 | N | Merchant ID, required for all requests. Must match |
retref | 14 | N | The retrieval reference number from the original authorization response. |
amount | 12 | N | Optional. If omitted or equal to $0, the full amount is voided. If no capture has taken place ( Note: Partial voids are not supported for debit transactions. If you specify a partial void amount for a debit transaction, the entire amount is voided. Omit the amount or specify the full amount for a debit void. |
If the void is successful, the authcode
will contain REVERS
. If transaction is not found or an error occurs:
respproc
will contain PPSrespcode
will contain an error code respstat
will contain C indicating the transaction has declinedresptext
will contain a descriptive messageField | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 16 | Retrieved from void request |
orderId | Order ID | 50 | The order ID associated with the authorization, if present.orderId is returned in the void response when the corresponding authorization request included an orderid and "receipt":"y" . If no orderid was passed, but "receipt":"y" , the orderId field is returned with no value ("orderId":"" ); however, if no orderid was passed and "receipt":"json" , "n" , or is omitted, the orderId field is omitted. |
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:
|
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:
|
resptext | Response text | 40 | Text description of response |
receipt | Receipt Data | - | An object that includes additional fields to be printed on a receipt, copied from the original authorization response, if present. 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. |
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.
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/refund |
Headers | Content-Type: application/json Authorization: Basic |
Fields in bold are required.
Field | Size | Type | Comments |
---|---|---|---|
merchid | 16 | N | Merchant ID, required for all requests. |
retref | 14 | N | The retrieval reference number from the original authorization. |
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. |
orderid | 50 | AN | Optional, a unique order number for the refund transaction, to specify a unique identifier for the refund instead of retaining the order ID from the original authorization (if present). If an If an Note: If you include an order ID it must meet the following requirements:
|
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 PPSrespcode
will contain an error code respstat
will contain C indicating the transaction has declinedresptext
will contain a descriptive message See Gateway Response Codes for more information on these values.
Refunds are automatically approved by the CardPointe Gateway and submitted for 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 |
orderId | Order ID | 50 | The The If no |
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 |
receipt | Receipt Data | - | An object that includes additional fields to be printed on a receipt, copied from the original authorization response, if present. 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. |
declineCategory | Visa Decline Category Code | 1 | A numeric decline category code, only returned for declined transactions using Visa accounts. See Visa Decline Rules and Responses for detailed information on handling Visa declines. One of the following values:
|
declineCategoryText | Visa Decline Category Code Description | 25 | A text description of the One of the following:
|
The inquire service returns information for an individual transaction, including its settlement status (setlstat
) and the response codes from the initial authorization.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/inquire/<retref>/<merchid> |
Header | Authorization: Basic |
Fields in bold are required.
Field | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 16 | From the original authorization |
retref | Retrieval Reference Number | 14 | From the original authorization |
Field | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 12 | The Merchant ID, copied from the Inquire request. |
orderId | Order ID | 50 | The order ID associated with the authorization, if present.
|
account | Account number | 25 | The tokenized payment account used in the original authorization. |
expiry | Account expiration date | 4 | The account's expiration date, in format MMYY. |
amount | Amount to capture | 12 | Copied from original authorization response. |
currency | Currency of amount | 3 | Copied from original authorization response. |
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 | A unique batch ID, if the transaction was successfully captured. |
setlstat | Settlement Status | 40 | The current settlement status. The settlement status changes throughout the transaction lifecycle, from authorization to settlement. The following values can be returned in the inquire response:
|
capturedate | Capture date and time | 14 | The date the transaction was captured, in the format YYYYMMDDHHMMSS. |
settledate | Settlement date and time | 14 | The date the transaction was settled, in the format YYYYMMDDHHMMSS. |
signature | Signature Bitmap | 6144 | JSON-escaped, Base64-encoded, Gzipped, BMP of signature data (from a signature-capable terminal). 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 response. |
profileid | 20 digit profile ID | 20 | Primary identifier to access profiles. Present if transaction utilized a stored profileid. |
acctid | 3 digit account ID | 3 | Account identifier within a profile. Present if transaction utilized a stored profileid. |
authdate | Authorization Date | 8 | Date of the authorization, in the format YYYYMMDD. |
lastfour | Last four of token/card number | 4 | Last 4 digits of the token and card number. |
name | Account name | 30 | The account name, if returned in the track data. |
bintype | Type of BIN | 16 | The type of card, based on the BIN. Possible values:
|
entrymode | POS Entry Mode | 25 | Possible Values:
|
fee_authcode | 6 | N | Duplicate of the authcode field included if the transaction included a fee (for example, a credit card surcharge). |
fee_format | 7 | AN | The fee format configured for the merchant account (for example, "percent" ). |
fee_merchid | - | - | The merchant ID used to process a fee. If not applicable or the same as the transaction merchant ID, returns an empty value ("" ). |
fee_retref | - | - | The unique retrieval reference number for a fee. If not applicable or the same as the transaction retref, returns an empty value ("" ). |
fee_type | 13 | AN | The type of fee applied to the transaction. |
fee_value | 3 | N | The fee rate applied to the transaction with decimal implied (for example "300" for a 3% rate. |
emvTagData | EMV tag data | 2000 | A 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 |
receipt | Receipt 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 Field | 20 | A value passed by the merchant with the original authorization to further identify the transaction (see the userfields description under the Authorization Service). |
voidable | Void Indicator | 1 | Indicates 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. |
refundable | Refund Indicator | 1 | Indicates 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. |
declineCategory | Visa Decline Category Code | 1 | A numeric decline category code, only returned for declined transactions using Visa accounts. See Visa Decline Rules and Responses for detailed information on handling Visa declines. One of the following values:
|
declineCategoryText | Visa Decline Category Code Description | 25 | A text description of the One of the following:
|
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.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/inquireByOrderid/<orderid>/<merchid>/<set> |
Header | Authorization: Basic |
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.
Field | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 14 | From the original authorization |
orderid | Order ID | 50 | From the original authorization |
set | 1 or blank | 1 | set 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. |
If the specified Order ID was used in multiple authorization attempts (for example, to retry a declined transaction), then the InquireByOrderID response returns an array that includes an object for each transaction record that matches the Order ID.
Field | Content | Max Length | Comments |
---|---|---|---|
amount | Amount to capture | 12 | Copied from the original authorization response. |
orderId | Order ID | 50 | The order ID associated with the transaction. |
resptext | Response text | 40 | Copied from the original authorization response. |
setlstat | Settlement Status | 40 | The current settlement status. The settlement status changes throughout the transaction lifecycle, from authorization to settlement. The following values can be returned in the inquireByOrderid response:
|
respcode | Response code | 4 | Copied from the original authorization response. |
merchid | Merchant ID | 12 | Copied from the original authorization response. |
token | token | varies | Copied from the original authorization response. |
respproc | Response processor | 4 | Copied from the original authorization response. |
authdate | Authorization Date | 8 | The date of the authorization in the format YYYYMMDD. |
lastfour | Last four of token/card number | 4 | Last 4 digits of the token and card number. |
name | Account name | 30 | Account name, if returned in the track data. |
expiry | Account expiration date | 4 | Expiration date in the format MMYY. |
currency | Currency of amount | 3 | Copied from the original authorization response. |
retref | Retrieval reference number | 12 | Copied from the inquireByOrderid request. |
respstat | Response status | 1 | Copied from the original authorization response. |
account | Account number | 25 | The tokenized payment account used in the original authorization. |
bintype | Type of BIN | 16 | The type of card, based on the BIN. Possible values:
|
entrymode | POS Entry Mode | 25 | Possible Values:
|
fee_authcode | 6 | N | Duplicate of the authcode field included if the transaction included a fee (for example, a credit card surcharge). |
fee_format | 7 | AN | The fee format configured for the merchant account (for example, "percent" ). |
fee_merchid | - | - | The merchant ID used to process a fee. If not applicable or the same as the transaction merchant ID, returns an empty value ("" ). |
fee_retref | - | - | The unique retrieval reference number for a fee. If not applicable or the same as the transaction retref, returns an empty value ("" ). |
fee_type | 13 | AN | The type of fee applied to the transaction. |
fee_value | 3 | N | The fee rate applied to the transaction with decimal implied (for example "300" for a 3% rate. |
emvTagData | EMV tag data | 2000 | A 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 |
receipt | Receipt 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 Field | 20 | A value passed by the merchant with the original authorization to further identify the transaction (see the userfields description under the Authorization Service). |
voidable | Void indicator | 1 | Indicates 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. |
refundable | Refund indicator | 1 | Indicates 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. |
declineCategory | Visa Decline Category Code | 1 | A numeric decline category code, only returned for declined transactions using Visa accounts. See Visa Decline Rules and Responses for detailed information on handling Visa declines. One of the following values:
|
declineCategoryText | Visa Decline Category Code Description | 25 | A text description of the One of the following:
|
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.
Partial voids are not supported for debit transactions. If you specify a partial void amount for a debit transaction, the entire amount is voided. Omit the amount or specify the full amount for a debit void.
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.
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/voidByOrderId/ |
Headers | Content-Type: application/json Authorization: Basic |
Fields in bold are required.
Field | Max Length | Type | Comments |
---|---|---|---|
merchid | 14 | N | From the original authorization |
orderid | 50 | A | From the original authorization |
amount | 12 | N | Optional. If omitted or equal to $0, the full amount is voided. If no capture has taken place ( Note: Partial voids are not supported for debit transactions. If you specify a partial void amount for a debit transaction, the entire amount is voided. Omit the amount or specify the full amount for a debit void. |
If the void is successful, the authcode
will contain REVERS
. If the transaction is not found, or an error occurs:
respproc
will contain PPSrespcode
will contain an error code respstat
will contain C indicating the transaction has declinedresptext
will contain a descriptive messageField | Content | Max Length | Comments |
---|---|---|---|
merchid | Merchant ID | 16 | Retrieved from void request |
orderId | Order ID | 50 | The order ID associated with the transaction. |
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:
|
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:
|
resptext | Response text | 40 | Text description of response |
receipt | Receipt Data | - | An object that includes additional fields to be printed on a receipt, copied from the original authorization response, if present. 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. |
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 the CardPointe Gateway 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.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/settlestat? |
Parameters |
|
Header | Authorization: Basic |
The merchid
parameter is required in all instances.
Field | Content | Max Length | Comments |
---|---|---|---|
batchid | Batch ID | 12 | Copied from the capture request |
hoststat | Batch settlement status | 2 | One of the values below:
|
hostbatch | Host batch ID | 16 | The batch identifier assigned by the payment processor. |
merchid | Merchant ID | 16 | Merchant ID |
respproc | Clearing House | 4 | CardPointe Gateway 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 |
---|---|---|---|
authcode | Authorization code | 6 | The authcode copied from the authorization response. |
cardtype | Card brand or account type | 4 | The card brand or account type returned by the processor. |
retref | Retrieval reference number | 12 | CardPointe retrieval reference number from authorization response |
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.
|
setlstat | Settlement status | 1 | The current settlement status. The settlement status changes throughout the transaction lifecycle, from authorization to settlement. The following values can be returned in the settlestat response:
|
The settlement status changes throughout the transaction lifecycle, from authorization to settlement. The setlstat
field returns the current settlement status, and is included in the following response objects:
setlstat
field in the capture response indicates the transaction's status post-authorization, but prior to settlement.setlstat
field in the inquire responses indicates the transaction's status throughout the entire transaction lifecycle; therefore the inquire response can return all possible setlstat
values.setlstat
field in the settlestat response indicates the transaction's status once the batch has been sent for settlement. The response includes a setlstat
value for each transaction in the txn
array.The following table provides detailed information on each setlstatus value, including the values can be returned in the response:
The setlstat
value format varies depending on the response type:
setlstat
status, listed in the Status column in the following table (for example, "setlstat":"Queued for Capture"
).setlstat
label, listed in the Label column in the following table (for example, "setlstat":"N"
).Label |
Status |
Returned by |
Description |
A |
Authorized |
The authorization was approved, but the transaction has not yet been captured. |
|
D |
Declined |
The authorization was declined. |
|
F |
Format error |
The order did not transmit for settlement due to unexpected or invalid order or item data. Contact Support if you encounter this status. |
|
N |
Rejected |
The batch was sent for settlement, but the transaction was rejected for funding. Contact Support if you encounter this status. |
|
P |
Pin Debit |
Vantiv only. PIN debit transactions are settled by Vantiv, and are not submitted with the batch for settlement. |
|
R |
Queued for Capture |
The authorization was approved and captured but has not yet been sent for settlement. |
|
T |
Token Decrypt |
The transaction was not settled due to a token decryption error. Contact Support if you encounter this status. |
|
V |
Voided |
The transaction was voided. |
|
W |
Amount under review |
First Data North and Rapid Connect only. The batch for this transaction was transmitted for settlement, and the transaction was placed under review because the amount exceeded a configured threshold. The transaction should be accepted or rejected for funding the next day; however, the |
|
Y |
Accepted |
The batch for this transaction was transmitted and accepted for funding. |
|
Z |
Zero amount |
The authorization was a $0 auth for account validation. |
Funding data is only available for merchants with the funding service configured and enabled in the production environment.
The funding endpoint provides merchant funding information and supplemental transaction and funding adjustment details. This information is provided by the host payment processing platform (for example, First Data Omaha).
For merchants with next day funding, funding data is typically available between 1PM and 6PM ET on the day following settlement.
For merchants without next day funding, funding data is typically available within 1-2 business days between 1PM and 6PM ET.
Profitstars ACH funding data is typically available within 72 hours.
A request to the funding endpoint returns all available funding data for the merchant on the date specified, in an array of fundings
, txns
(transactions), adjustments
, and chargebacks
records. If no adjustment or chargeback data is present for the date specified, these arrays are not returned.
If no batches are found or are ready to return, the service returns
{"errormsg":"No deposits match your request"}
.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/funding? |
Query Parameters | merchid=<merchid>&date=<MMDD>or<YYYYMMDD> |
Header | Authorization: Basic |
merchid
is required.
date
is optional, and can be specified in the format MMDD
to specify a day within the current calendar year, or YYYYMMDD
to specify a date in a previous calendar year. If no date
is specified, the service checks for any funding data that has not already been retrieved.
To use the funding endpoint to retrieve ACH funding data, you must use the ACH MID and API credentials associated with this MID.
Each funding service request returns up to four JSON arrays (txns
, fundings
, adjustments
, and chargebacks
) as applicable, along with other fields that help identify information about the funding.
The following table describes each property/node in the object provided in the Funding response.
Field | Max Length | Type | Description |
---|---|---|---|
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. |
chargebacks | varies | Data Array | This array represents all the chargebacks for the given date provided. The chargebacks node is only available for merchants configured to obtain this data, and is only returned if chargeback data is available for the given date. 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. |
Field | Content | Max Length | Description |
---|---|---|---|
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, when no adjustment type is provided by the host. |
totalfunding | Funding Amount | 12 | Total amount of merchant 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 |
deposittrancode | Deposit Transaction Code | 10 | |
depositachtracenumber | Deposit ACH Trace Number | 20 |
Field | Content | Max Length | Description |
---|---|---|---|
fundingtxnid | Transaction ID | 22 | The fundingmasterid associated with the transaction. |
retref | Gateway ID | 30 | Gateway retrieval reference number (aka retref ). |
authcode | Authorization Code | 6 | The authorization code returned by the issuer. |
authdate | Authorization Date | 14 | The date on which the authorization was processed, in the format YYYYMMDDHHMMSS . |
respcode | Response code | - | Alpha-numeric response code that represents the description of the response. |
batchid | Batch ID | 12 | The batch ID, automatically created and assigned unless otherwise specified in the authorization request. |
cardproc | Card Processor | 4 | The processor that the MID is configured to use. |
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 with the card. Refer to the Response Appendix (Card Brand) for possible field values. |
amount | Amount | 12 | The transaction amount. |
currency | Currency Code | 3 | Three character currency code associated to transaction. Refer to the Response Appendix (Currency Codes) for possible field values. |
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. |
userfieldn | Custom Field | 20 | A value passed by the merchant with the original authorization to further identify the transaction (see "userfields" within the Authorization Service). The response can include up to 10 custom userfields, labeled userfield0 through userfield9 .
Currently, the userfieldn is not supported in UAT for testing. |
fundingid | Funding Identifier | 22 | CardPointe unique key identifier for merchant transaction funding activity. |
plancode | Interchange Level | 10 | An alpha-numeric value representing the applicable interchange rate. |
downgradereasoncodes | Downgrade Reason Codes | 100 | The downgrade reason codes associated with the transaction, if applicable. |
invoicenumber | Invoice Number | Num | The invoice number from the original transaction, if applicable. |
sourcetransactionid | Source Transaction ID | 100 | The source transaction ID, (either the CardPointe Gateway transaction GUID or the BluePay Gateway source transaction ID) for the transaction. |
terminalnumber | Terminal Number | 10 | |
achreturncode | ACH Return Code | 5 | Alpha-numeric code that provides additional information for rejected ACH transactions. See Using the Funding Endpoint in the CardPointe Gateway Developer Guides for possible field values. |
parentretref | Parent Retrieval Reference Number | 30 | The original (or prior) transaction associated with a refund or ACH Return. |
Field | Content | Max Length | Description |
---|---|---|---|
fundingadjustmentid | Funding Adjustment ID | 22 | CardPointe 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. |
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 Changed | 8 | The date when the record was last updated, in the format YYYY-MM-DD . |
dateadded | Date Added | 8 | The date when the transaction was created, in the format YYYY-MM-DD . |
If no adjustment detail is listed by the host, any offset to the funding amount will be listed as other adjustment in this record.
Chargeback data is only applicable to specific clients that have been configured appropriately. This node is only returned if chargeback records are present for the given date.
Field | Content | Max Length | Description |
---|---|---|---|
depositdate | Deposit Date | 8 | The merchant's deposit date associated with the chargeback record, in the format YYYY-MM-DD . |
amount | Chargeback Amount | 20, 2 dec | The amount of the chargeback to the cardholder's account. |
transactiondate | Transaction Date | 8 | The date of the original transaction, in the format YYYY-MM-DD . |
reasondescription | Chargeback Description | 200 | A description of the chargeback reason, useful in understanding or disputing the chargeback. See Chargeback Reason Codes and Descriptions in the Response Appendix below for more information. |
reasoncode | Chargeback Reason Code | 4 | An alphanumeric code returned by the issuer, that provides the reason for the chargeback. See Chargeback Reason Codes and Descriptions in the Response Appendix below for more information. |
datechanged | Date Changed | 8 | The date of the most recent update to the chargeback event record, in the format YYYY-MM-DD . |
sourcetransactionid | Source Transaction ID | 100 | The source transaction ID, (either the CardPointe Gateway transaction GUID or the BluePay Gateway source transaction ID) for the original transaction associated with the chargeback. |
transactionamount | Transaction Amount | 20, 2 dec | The amount of the original transaction associated with the chargeback. |
chargebackdate | Date of Chargeback | 8 | The date that the chargeback event occurred, in the format YYYY-MM-DD . |
sequencenumber | Chargeback Sequence Number | 30 | The chargeback sequence number, returned by the processor. |
dateadded | Date Added | 8 | The date that the chargeback record was added to the master funding event, in the format YYYY-MM-DD . |
merchid | Merchant ID | 30 | The merchant ID associated with the original transaction associated with the chargeback. |
authcode | Authorization code | 8 | The authorization code for the original transaction associated with the chargeback. |
fundingmasterid | Funding Master ID | 22 | The unique ID for the funding record that includes the chargeback. |
fundingchargebackid | Funding Chargeback ID | - | The unique ID for the chargeback record within the parent funding record. |
casenumber | Chargeback Case Number | 30 | A unique case number returned by the processor. |
acquirereferencenumber | Acquirer Reference Number | 30 | A unique reference number for the chargeback record, returned by the acquirer/issuer. |
cardnumber | Masked Card Number | 30 | The masked card number from the original transaction associated with the chargeback. |
retref | Retrieval Reference Number, CardPointe Transaction ID | 30 | The retref from the original transaction associated with the chargeback. |
invoicenumber | Transaction Invoice Number | - | The invoice number from the original transaction associated with the chargeback, if applicable. |
See below for a legend of possible return values for the cardtype
field.
Card Type | Description |
---|---|
Credit | Payment card issued by a bank, business, etc., allowing the holder to purchase goods or services on credit. |
Debit | Payment card issued by a bank allowing the holder to transfer money electronically to another bank account when making a purchase. |
EBT | Electronic Benefit Transfer is an electronic system that allows state welfare departments to issue benefits via a magnetically encoded payment card. |
See below for a legend of possible return values for the cardbrand
field.
Card Brand | Description |
---|---|
MC | MasterCard |
VISA | Visa |
DSCV | Discover |
UNKN | Unknown |
AMEX | American Express |
WEX | Wright Express |
VYGR | Voyager |
TEL | Telecheck |
DNR | Diners |
JCB | Japan Credit Bureau |
BML | Bill Me Later |
RM | Revolution Money |
The CardPointe Gateway 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.
See below for a legend of possible return values for the type
field.
Transaction Type | Description |
---|---|
SALE | Sale or ticket-only sale. |
REFUND | Credit back of a sale due to a return or refund. |
CASH ADVANCE | Cash Advance |
VOID SALE | Void a sale or ticket-only sale or a cash advance. |
VOID REFUND | Void a return or refund. |
AUTH REQUEST | Authorization request. |
ACCOUNT VERIFY | Account verification. |
UNKNOWN | Source data transaction type not mapped. |
See below for a legend of possible return values for the status
field.
Transaction Status | Description |
---|---|
Auth | The credit card authorization request was processed successfully. |
Captured | The credit card authorization was captured, and the request was processed successfully by the payment processor. |
Voided | A deletion of the transaction information. |
Failure | The credit card (authorization, capture, or credit) or check (debit or credit) request failed. |
Rejected | A rejection of the transaction information due to duplicate transaction or fraud protection. |
Declined | A response from the card issuer denying the use of the card for the attempted transaction. |
Settled | The check debit or credit request was processed successfully. |
Processed | The transaction was fully processed. Note: for ACH transactions, the Processed status is displayed for rejected transaction. See the achreturncode field for more information on the transaction. |
Unknown | Transaction status not supplied. |
See below for a legend of possible returns for the category
field.
Adjustment Group | Adjustment Group Detail |
---|---|
ADJUSTMENTS | DEPOSIT ADJUSTMENTS |
ADJUSTMENTS | FINANCIAL ADJUSTMENTS |
ADJUSTMENTS | AGENT BANK |
ADJUSTMENTS | CASH ADVANCE ADJUSTMENT |
ADJUSTMENTS | COST OF FUNDS |
ADJUSTMENTS | DEPOSIT ADJUSTMENTS |
FEES | FEES |
FEES | ADDRESS VERIFICATION |
FEES | AUTHORIZATIONS |
FEES | ACCOUNT MANAGEMENT FEES |
FEES | WS INFO. MGR. |
FEES | CHARGEBACK TRANSACTION PROCESSING |
FEES | DEBIT |
FEES | DATA CAPTURE |
FEES | CES IMAGE |
FEES | EQUIPMENT |
FEES | COMMUNICATION |
FEES | CASH ADVANCE |
FEES | CES LINK |
FEES | CHECK SERVICES |
FEES | FUNDS TRANSFER |
FEES | SUPPLIES |
FEES | FOREIGN HANDLING |
FEES | REPORT |
FEES | CES TRANSLINK |
FEES | USAVE |
INTERCHANGE CHARGES | INTERCHANGE CHARGES |
INTERCHANGE CHARGES | INTERCHANGE |
INTERCHANGE CHARGES | ASSESSMENT |
INTERCHANGE CHARGES | NON-QUAL TRANSACTIONS |
INTERCHANGE CHARGES | AGENT INTERCHANGE |
INTERCHANGE CHARGES | INTERCHANGE/ASSESSMENT ADJ. |
INTERCHANGE CHARGES | DEBIT |
REVERSAL | CHARGEBACKS/CHARGEBACK REVERSALS |
REVERSAL | DEBIT ADJUSTMENTS |
REVERSAL | DEBIT ADJUSTMENT REVERSAL |
SERVICE CHARGES | SERVICE CHARGES |
SERVICE CHARGES | SERVICE CHARGE ADJUSTMENTS |
SERVICE CHARGES | DEBIT SERVICE CHARGE |
THIRD PARTY | THIRD PARTY ADJUSTMENTS |
OTHER ADJUSTMENT | OTHER ADJUSTMENT |
Card Brand | reasoncode | reasondescription | Days to Dispute | Dispute Category |
---|---|---|---|---|
Amex | A01 | No Valid Authorization/Excessive Amount | 120 | Authorization |
Amex | A02 | No Authorization/Invalid Approval Code | 120 | Authorization |
Amex | A08 | Authorization Approval Code Expired | 120 | Authorization |
Amex | C02 | Credit Not Processed | 120 | Cardholder Dispute |
Amex | C04 | Credit Not Processed / Returned Merchandise | 120 | Cardholder Dispute |
Amex | C05 | Credit Not Processed / Cancelled Transaction | 120 | Cardholder Dispute |
Amex | C08 | Non Receipt of Merchandise / Service | 120 | Cardholder Dispute |
Amex | C14 | Paid By Other Means | 120 | Processing Errors |
Amex | C18 | Cancelled Trans / No Show | 120 | Cardholder Dispute |
Amex | C28 | Cancelled Recurring | 120 | Cardholder Dispute |
Amex | C31 | Cardholder Dispute - Not As Described | 120 | Cardholder Dispute |
Amex | C32 | Cardholder Dispute - Defective | 120 | Cardholder Dispute |
Amex | F10 | No swipe - keyed transaction | 120 | Fraud |
Amex | F14 | No Signature Obtained | 120 | Fraud |
Amex | F24 | Fraud - No Cardholder Knowledge | 120 | Fraud |
Amex | F29 | Fraudulent Transaction - Card Not Present | 120 | Fraud |
Amex | F30 | EMV Counterfeit | 120 | Fraud |
Amex | F31 | EMV Lost/Stolen/Non Received | 120 | Fraud |
Amex | FR2 | Fraud - Full Recourse Agreement | 120 | Fraud |
Amex | FR4 | Immediate Chargeback Program | - | Miscellaneous |
Amex | FR5 | Immediate Chargeback Program | - | Miscellaneous |
Amex | FR6 | Immediate Chargeback Program | - | Miscellaneous |
Amex | M01 | Merchant Accepted Chargeback | - | Miscellaneous |
Amex | M04 | Merchant Accepted Chargeback | - | Miscellaneous |
Amex | M10 | Capital damages | - | Miscellaneous |
Amex | M11 | CM Credited- Chargeback Reversed | - | Miscellaneous |
Amex | M19 | Offset Adjustment | - | Miscellaneous |
Amex | M23 | Offset Adjustment | - | Miscellaneous |
Amex | M27 | Offset Adjustment | - | Miscellaneous |
Amex | M29 | Discount Fees | - | Miscellaneous |
Amex | M36 | Dispute Other | - | Miscellaneous |
Amex | M38 | Chargeback Reversed | - | Miscellaneous |
Amex | M42 | Chargeback Reversal Expired | - | Miscellaneous |
Amex | M43 | Marketing Programs | - | Miscellaneous |
Amex | M44 | Marketing Programs | - | Miscellaneous |
Amex | M45 | Offset adjustment | - | Miscellaneous |
Amex | M46 | Offset adjustment | - | Miscellaneous |
Amex | M49 | Unauthorized Charge - Car Rental | 120 | Fraud |
Amex | P01 | Non-Matching Account Number | 120 | Authorization |
Amex | P03 | Credit Posted as a Card Sale | 120 | Processing Errors |
Amex | P04 | Card Sale Posted as a Credit | 120 | Processing Errors |
Amex | P05 | Transaction amount differs | 120 | Processing Errors |
Amex | P07 | Late Presentment | 120 | Processing Errors |
Amex | P08 | Duplicate Processing | 120 | Processing Errors |
Amex | P22 | Card Number Does Not Match Original Charge | - | Authorization |
Amex | P23 | Correct Transaction Currency Code Not Provided | 120 | Processing Errors |
Amex | R03 | Insufficient Doc | - | Miscellaneous |
Amex | R13 | Retrieval Response Not Received | - | Miscellaneous |
Discover | 4534 DP | Duplicate Processing | 120 | Processing Errors |
Discover | 4541 AP | Recurring Payments | 120 | Cardholder Dispute |
Discover | 4542 LP | Late Presentation | 120 | Processing Errors |
Discover | 4550 CD | Credit/Debit Posted Incorrectly | 120 | Processing Errors |
Discover | 4553 RM | Cardholder Disputes Quality of Goods or Services | 120 | Cardholder Dispute |
Discover | 4586 AW | Altered Amount | 120 | Processing Errors |
Discover | 4752 AA | Does Not Recognize | 120 | Fraud |
Discover | 4753 IN | Invalid Card Number | 120 | Fraud |
Discover | 4755 RG | Non-Receipt of Goods or Services | 120 | Cardholder Dispute |
Discover | 4757 TF | Violation of Operating Regulations | 120 | Authorization |
Discover | 4762 05 | Good Faith Investigation | 120 | Fraud |
Discover | 4863 AT | Authorization NonCompliance | 120 | Authorization |
Discover | 4864 NF | Non-Receipt of Case from ATM | 120 | Cardholder Dispute |
Discover | 4865 PM | Paid by Other Means | 120 | Processing Errors |
Discover | 4866 UA05 | Fraud Chip Card Counterfeit Transaction | 120 | Fraud |
Discover | 4867 UA06 | Fraud Chip and PIN Transaction | 120 | Fraud |
Discover | 6050 DC | Dispute Compliance | 120 | Authorization |
Discover | 7010 UA01 | Fraud - Card Present Transaction | 120 | Fraud |
Discover | 7030 UA02 | Fraud - Card Not Present Transaction | 120 | Fraud |
Discover | 8002 RN2 | Credit Not Processed | 120 | Cardholder Dispute |
MasterCard | 07 | Warning Bulletin File | - | Authorization |
MasterCard | 08 | Authorization Related | 90 | Authorization |
MasterCard | 12 | Account number not on file | - | Authorization |
MasterCard | 31 | Transaction amount differs | 120 | Proccessing Errors |
MasterCard | 34 | Point of Interaction Error | 120 | Proccessing Errors |
MasterCard | 37 | No Cardholder Authorization | 120 | Fraud |
MasterCard | 40 | Fraudulent Processing of Transactions | 120 | Fraud |
MasterCard | 41 | Cancelled Recurring Digital Goods Transaction | 120 | Cardholder Dispute |
MasterCard | 42 | Late Presentment | 120 | Proccessing Errors |
MasterCard | 46 | Correct Transaction Currency Code not provided | 120 | Proccessing Errors |
MasterCard | 49 | Questionable Merchant Activity | 120 | Fraud |
MasterCard | 50 | Installment Billing | 120 | Cardholder Dispute |
MasterCard | 53 | Cardholder Dispute Defective\Not as Described | 120 | Cardholder Dispute |
MasterCard | 54 | Cardholder Dispute Not Elsewhere Classified (US Region only) | 120 | Cardholder Dispute |
MasterCard | 55 | Goods or Services Not Provided |
120 | Cardholder Dispute |
MasterCard | 59 | No Show, Addendum, or ATM Dispute | 120 | Cardholder Dispute |
MasterCard | 60 | Credit Not Processed | 120 | Cardholder Dispute |
MasterCard | 63 | Cardholder Does Not Recognize-Potential Fraud | 120 | Fraud |
MasterCard | 70 | Chip Liability Shift | 120 | Fraud |
MasterCard | 71 | Chip/PIN Liability Shift | 120 | Fraud |
Visa | 30 | Services/Merchandise Not Rendered | 120 | Cardholder Dispute |
Visa | 41 | Cancelled Recurring Transaction | 120 | Cardholder Dispute |
Visa | 53 | Not As Described/Defective | 120 | Cardholder Dispute |
Visa | 57 | Fraudulent Processing of Transactions | 120 | Fraud |
Visa | 62 | Counterfeit Transaction | 120 | Fraud |
Visa | 71 | Authorization Request Declined | 75 | Authorization |
Visa | 72 | No Authorization | 75 | Authorization |
Visa | 73 | Expired Card | 75 | Authorization |
Visa | 74 | Late Presentment | 120 | Processing Errors |
Visa | 75 | Cardholder Does Not Recognize | 120 | Fraud |
Visa | 76 | Incorrect Transaction Code(Credit Posted as a Purchase) | 120 | Processing Errors |
Visa | 77 | Non-Matching Account Number | 75 | Authorization |
Visa | 80 | Incorrect Transaction Amount Or Account number | 120 | Processing Errors |
Visa | 81 | Fraud- Card Present Environment | 120 | Fraud |
Visa | 82 | Duplicate Processing | 120 | Fraud |
Visa | 82 | Duplicate Processing | 120 | Processing Errors |
Visa | 83 | Fraud- Card Not Present Environment | 120 | Fraud |
Visa | 85 | Credit Not Processed | 120 | Cardholder Dispute |
Visa | 86 | Paid by Other Means | 120 | Processing Errors |
Visa | 90 | Non-Receipt of Cash at ATM | 120 | Cardholder Dispute |
Visa | 93 | Fraud Monitoring Program | 120 | Fraud |
Visa | 70 Int'l only | Card Recovery Bulletin or Exception File | 75 | Authorization |
Visa | 78 Int'l only | Service Violation Code | 75 | Authorization |
Visa | 1010 | EMV Liability Shift Counterfeit Fraud | up to 120 days | Fraud |
Visa | 1020 | EMV Liability Shift Non-Counterfeit Fraud | up to 120 days | Fraud |
Visa | 1030 | Other Fraud – Card Present Environment | up to 120 days | Fraud |
Visa | 1040 | Other Fraud – Card Absent Environment | up to 120 days | Fraud |
Visa | 1050 | Visa Fraud Monitoring Program | up to 120 days | Fraud |
Visa | 1110 | Card Recovery Bulletin | up to 120 days | Authorization |
Visa | 1120 | Declined Authorization | up to 120 days | Authorization |
Visa | 1130 | No Authorization | up to 120 days | Authorization |
Visa | 1210 | Late Presentment | up to 120 days | Processing Errors |
Visa | 1220 | Incorrect Transaction Code | up to 120 days | Processing Errors |
Visa | 1230 | Incorrect Currency | up to 120 days | Processing Errors |
Visa | 1240 | Incorrect Account Number | up to 120 days | Processing Errors |
Visa | 1250 | Incorrect Amount | up to 120 days | Processing Errors |
Visa | 1261 | Duplicate Processing | up to 120 days | Processing Errors |
Visa | 1262 | Paid by Other means | up to 120 days | Processing Errors |
Visa | 1270 | Invalid Data | up to 120 days | Processing Errors |
Visa | 1310 | Merchandise/Services Not Received | up to 120 days | Cardholder Dispute |
Visa | 1320 | Cancelled Recurring | up to 120 days | Cardholder Dispute |
Visa | 1330 | Not As Described or Defective Merchandise/Services | up to 120 days | Cardholder Dispute |
Visa | 1340 | Counterfeit Merchandise | up to 120 days | Cardholder Dispute |
Visa | 1350 | Misrepresentation | up to 120 days | Cardholder Dispute |
Visa | 1360 | Credit Not Processed | up to 120 days | Cardholder Dispute |
Visa | 1370 | Cancelled Merchandise/Services | up to 120 days | Cardholder Dispute |
Visa | 1380 | Original Credit Transaction Not Accepted | up to 120 days | Cardholder Dispute |
Visa | 1390 | Non-Receipt of Cash or Load Transaction Value | up to 120 days | Cardholder Dispute |
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).
The profile service provides three methods.
Method | URL | Headers |
---|---|---|
PUT or POST (Create/Update) | https://<site>.cardconnect.com/cardconnect/rest/profile See the Create/Update Profile Request for more information. | Content-Type: application/json Authorization: Basic |
GET | https://<site>.cardconnect.com/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid> If the account ID is omitted, then all accounts in the profile are returned. See the Get Profile Request for more information. | Authorization:Basic |
DELETE | https://<site>.cardconnect.com/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid> If the account ID is omitted, then all accounts in the profile are deleted. If a profile or an account within a profile is associated with a CardPointe Billing Plan, then deleting the account or profile also cancels and deletes the billing plan. See the Delete Profile Request for more information. | Content-Type: application/json Authorization: Basic |
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:
Create/Update Profile Request URL
https://<site>.cardconnect.com/cardconnect/rest/profile/
If you attempt to create a new profile that exactly matches an existing profile, the new profile will not be created; instead the response includes the profileid
and acctid
for the existing profile.
The following fields are checked for matches, and if all of the following fields match an existing profile, the new profile is not created:
If the request includes "defaultacct":"Y"
, the CardPointe Gateway will update the existing profile to set it as the default, and will return the existing profileid
and acctid
info in the response.
You can submit a $0 authorization, including CVV and AVS verification, to validate the customer's information before creating a profile.
Fields marked with an asterisk (*) are copied from the Authorization request.
Fields in bold are required.
Field | Max Length | Type | Comments |
---|---|---|---|
profile | 20+ | N | 20-digit profile ID and (optional) 3-digit account ID string in the format <profile id>/<account id>, required to update an existing profile. |
defaultacct | 1 | AN | "Y" to assign as default account |
profileupdate | 1 | AN | "Y" to update profile data with non-empty request data only as opposed to full profile replacement including empty values |
cofpermission* | 1 | AN | Optionally specifies whether or not the cardholder provided consent to store their payment details in a profile. Specify one of the following values:
Defaults to N if not provided. |
auoptout | 1 | AN | Specifies whether or not the profile is set to opt out of the CardPointe Account Updater service. Requires the merchant account to be enrolled in the Card Account Updater add-on. Specify one of the following values:
Defaults to N if not provided. |
accttype | 6 | AN | One of PPAL, PAID, GIFT, PDEBIT, otherwise not required |
merchid* | 16 | N | Merchant ID, required for all requests |
account* | 19 | N | One of the following:
|
bankaba | 9 | N | Bank routing (ABA) number, ECHK only |
expiry | 8 | N | Card expiration in one of the following formats:
Not required for eCheck (ACH) or digital wallet (for example, Apple Pay or Google Pay) payments. |
name | 30 | AN | Account name; optional for credit cards, but required for E-check/ACH authorizations. |
address | 30 | AN | Account street address. |
city | 30 | AN | Account city. |
region | 20 | AN | Account US state, Mexican state, or Canadian province. |
country | 3 | AN | Account country (2 character country code). |
phone | 15 | AN | Account phone; optional for credit cards, but required for ACH(ECHK or ESAV) transactions. |
postal | 10 | AN | Account postal code. if country is "US" , must be 5 or 9 digits otherwise any alphanumeric string is accepted |
company | 128 | AN | Company name associated with the account. |
128 | AN | E-Mail address of the account holder |
Field | Max Length | 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 account type. |
expiry | 8 | N | Card Expiration. |
name | 30 | AN | Account name. |
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. |
postal | 10 | AN | Account postal code. |
128 | AN | Email address of the account holder. | |
company | 128 | AN | Company 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. |
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.
|
cofpermission | 1 | AN | Identifies whether or not the cardholder provided consent to store their payment details in a profile. One of the following values:
|
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://<site>.cardconnect.com/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>
Fields in bold are required.
Field | Max Length | Type | Comments |
---|---|---|---|
profile ID | 20 | N | Primary identifier to access profiles |
account ID | 3 | N | Account identifier within a profile |
merchid | 16 | N | CardPointe merchant ID (MID) required in all requests. |
Field | Max Length | Type | Comments |
---|---|---|---|
profileid | 20 | N | The primary profile identifier. |
acctid | 3 | N | The account identifier within a profile. |
accttype | 6 | AN | The value supplied in account creation; VISA, MC, DISC, ECHK. |
token | 19 | N | The token associated with the account. |
expiry | 8 | N | Card expiration in either MMYY or YYYYMMDD format. |
name | 30 | AN | Account name; optional for credit cards, but required for ACH (ECHK or ESAV). |
address | 30 | AN | Account street address. |
city | 30 | AN | Account city. |
region | 20 | AN | Account US state, Mexican state, or 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. |
company | 128 | AN | Company name associated with the account. |
defaultacct | 1 | AN | Y marks the default account referenced when a profile ID is used without an associated account ID |
auoptout | 1 | AN | Identifies whether or not the profile is set to opt out of the CardPointe Account Updater service.
|
cofpermission | 1 | AN | Identifies whether or not the cardholder provided consent to store their payment details in a profile. One of the following values:
|
gsacard | 1 | AN | Identifies whether the card is government issued. |
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.
If a profile or an account within a profile is associated with a CardPointe Billing Plan, then deleting the account or profile also cancels and deletes the billing plan.
Delete Profile Request URL
https://<site>.cardconnect.com/cardconnect/rest/profile/<profile ID>/<account ID>/<merchid>
Fields in bold are required.
Field | Max Length | 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. |
Field | Max Length | Type | Comments |
---|---|---|---|
resptext | 20 | A | Profile delete request status |
respcode | 6 | N | Response code assigned by the CardPointe Gateway 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 |
This signature capture service augments an existing authorization record with the provided signature data. The signature can then be retrieved by an inquire request.
Method | PUT or POST |
URL | https://<site>.cardconnect.com/cardconnect/rest/sigcap |
Headers | Content-Type: application/json Authorization: Basic |
Fields in bold are required.
Field | Max Length | Type | Comments |
---|---|---|---|
merchid | 12 | N | Merchant ID, required for all requests |
retref | 12 | N | CardPointe retrieval reference number from authorization response |
signature | 6146 | AN | JSON Encoded, Base64 Encoded, GZipped, BMP (200x100px) image. Omit to erase an associated signature. |
Field | Type | Comments |
---|---|---|
resptext | AN | Response text |
respcode | N | Response code (02 - success, 03 - failure) |
retref | N | Provided retref |
merchid | N | Provided merchid |
The BIN service allows you to use a CardSecure 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 an Issuer Identification Number (IIN).
The BIN service supports the Visa, Mastercard, Amex, Discover, Diners, and JCB card brands.
Visa and Mastercard return all parameters described in the BIN response. For other card brands, only the country
, product
, and bin
parameters are relevant.
Method | GET |
URL | https://<site>.cardconnect.com/cardconnect/rest/bin/<merchid>/<token> |
Header | Authorization: Basic |
Field | Type | Comments |
---|---|---|
country | A | Issuer country of origin |
product | A | Card type, one of the following:
|
bin | N | The bank identification number (BIN) of the card used. |
cardusestring | A | General usage type, one of the following:
|
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 |
issuer | A | Card issuing bank/institution |
binlo | N | The low end of the BIN range that includes the card’s BIN value. Masked after the first six (6) digits. |
binhi | N | The high end of the BIN range that includes the card’s BIN value. Masked after the first six (6) digits. |
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 |