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

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

Overview

The CoPilot API provides resources creating and modifying merchants. The API uses JSON web service semantics. Each web service implements the business processes as defined in this API documentation.

What's New?

Date Updated: 10/8/2019

This release includes the following update:

BlueChex Volume Fields

The CoPilot API includes a new blueChexVolume object in the Processing schema.

The blueChexVolume details are required for merchants using the BlueChex add-on.

This object includes the following fields:

FieldSizeTypeDescription
avgPerTransactionSalesAmount18.2DecimalAverage sales amount per BlueChex transaction.
maxPerTransactionSalesAmount18.2DecimalMaximum sales amount per BlueChex transaction.
avgPerTransactionCreditAmount18.2DecimalAverage credit (refund) amount per BlueChex transaction.
maxPerTransactionCreditAmount18.2DecimalMaximum credit (refund) amount per BlueChex transaction.
avgPerMonthSalesAmount18.2DecimalAverage monthly sales amount for all BlueChex transactions.
maxPerMonthSalesAmount18.2DecimalMaximum monthly sales amount for all BlueChex transactions.
avgPerMonthCreditAmount18.2DecimalAverage monthly credit (refund) amount for all BlueChex transactions.
maxPerMonthCreditAmount18.2DecimalMaximum monthly credit (refund) amount for all BlueChex transactions.

For example:

"processing": {
     "blueChexVolume" : {
          "avgPerTransactionSalesAmount" : "250.00",
          "maxPerTransactionSalesAmount" : "9999.00",
          "avgPerTransactionCreditAmount" : "200.00",
          "maxPerTransactionCreditAmount" : "9999.00",
          "avgPerMonthSalesAmount" : "25000.00",
          "maxPerMonthSalesAmount" : "50000.00",
          "avgPerMonthCreditAmount" : "5000.00",
          "maxPerMonthCreditAmount" : "10000.00"
         }
      }

Authentication

Authenticate your account via a JSON Web Token (JWT). You will send a request to obtain the access token and then use it for accessing resources in the Authorization header.

Note that an access token token has a very limited timeframe the(expires_in) determines the lifespan of the token in seconds. If your application needs access to the API beyond the lifetime of a single access token, it is recommended to obtain a new token via the refresh token endpoint, since refresh tokens have a much longer timeframe.

Important Security Considerations:

  • The provided client_secret is a secret and should never be expose on the client side via JavaScript. Take steps to ensure that the client secret is stored securely in your application.
  • Be sure to not expose the access_token or refresh_token in client side applications

Get Access Token Endpoint

Path

https://accountsuat.cardconnect.com/auth/realms/cardconnect/protocol/openid-connect/token

Method

POST

Request Body Content

FieldRequiredDefault ValueComments
usernameyes
passwordyes
grant_typeyespassword
client_idyesmerchapi
client_secretyesOnce you are registered for copilot API access you will be provided the client_secret value

The response will return JSON with an access_token, which is a signed OpenID Connect JSON Web Token (JWT).

Example Response Object

Once the token is obtained it can be used to Authenticate to any given resource of the API by adding it to the request via an Authorization header.

  • Authorization: Bearer accessTokenValue

Request Overview

Whenever possible, newer versions of the API will be backwards compatible with older versions. Since this will not always be possible, older version will be supported for a certain amount of time. Therefore, every request will need to include a request header named X-CopilotAPI-Version with a value of the version your application is currently requesting.

Example Header

Authorization: Bearer accessTokenValue
Content-type: application/json
X-CopilotAPI-Version: 1.0

Resources

Create Merchant Endpoint

Path

https://api-uat.cardconnect.com/merchant

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
templateId19LongyesThe merchant template needs to exist prior to any create endpoint calls.
merchantn/amerchantyesThe merchant definition.
ownerSiteUsern/asite usernoThis is the merchant's CardPointe user. If this is null, a CardPointe user will be created using the ownership fields in the merchant.

Response Body Content

FieldSizeTypeComments
merchantId19LongThe merchantId of the merchant
errorsn/aerrorThe error array if there was a problem creating the merchant.

Update Merchant Endpoint

This will update the merchant.

Partial Updates
Only objects passed in will be updated. For instance, if merchant.ownership is null or is not passed into the request, no changes will be made to the ownership. If an object is passed in, all fields fields in that object will be updated. For instance, if the merchant.ownership object is passed in but the merchant.ownership.driversLicenseNumber is not passed in, it will be set to null.

CardPointe user
Unlike merchant create, a CardPointe user will not be created from the merchant.ownership.owner fields. Once a merchant is created, updating the owner's CardPointe user can be done from the Owner Site User Endpoints. Alternatively, the ownerSiteUser object can be passed into the merchant update and either a new owner user will be created or the existing owner user will be updated (See the Example Request Object below).

Path

https://api-uat.cardconnect.com/merchant/{merchantId}

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
merchantn/amerchantyesThe merchant definition.
ownerSiteUsern/asite usernoThis is the merchant's CardPointe user. If this is null, no changes will be made to the owner site user.

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if there was a problem creating the merchant.

Merchant Find Endpoint

Path

https://api-uat.cardconnect.com/merchant/{merchantId}

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Merchant Status Endpoint

Path

https://api-uat.cardconnect.com/merchant/{merchantId/status

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Owner CardPointe User Create/Update

This is the site user that the owner will use to log into CardPointe to sign the application. This endpoint can only be called if the user has not already registered their CardPointe user account. After that, the user can manage their own profile from CardPointe.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/ownerSiteUser

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
ownerSiteUsern/asite useryes

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if there was a problem creating owner's CardPointe User.

Owner CardPointe User find

This is the site user that the owner will use to log into CardPointe to sign the application. This endpoint can only be called if the user has not already registered their CardPointe user account. After that, the user can manage their own profile from CardPointe.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/ownerSiteUser

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

FieldSizeTypeComments
ownerSiteUsern/asite user
errorn/aerrorThe error array if there an error finding the owner's CardPointe user

Request Signature Endpoint

The Merchant needs to be in the In Progress state to request a signature.All fees and pricing need to be submitted and the merchant must have an owner user.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/signature

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

No request body needed for this endpoint

Response Body Content

If the request signature was successful, the signature url is included in the request signature response.

Signature Status Endpoint

This endpoint will return the merchants signature status. This includes a page url for the owner to fill out and sign. If the merchant application has already been signed or the owner user is already a registered CardPointe user, the url will be simply be a link to the CardPointe login page.

The signatureStatusCd will be one of the following: NOT_SENT, PENDING, or SIGNED. NOT_SENT represents a merchant that is not ready for the owner to sign the application and an email has not been sent to the owner. PENDING represents a signature request has been sent to the owner. SIGNED means the owner has signed the application.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/signature

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Retract Signature Endpoint

The Merchant needs to be in the Out For Signature state to retract the signature.This endpoint will put the merchant back in the In Progress state.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/signature

Method

DELETE

Consumes

application/json

Produces

application/json

Request Body Content

No request body needed for this endpoint

Merchant Attachment Create

Create a merchant attachment

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/attachment

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
attachmentn/aattachmentyes

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if there was a problem creating the attachment.
attachmentIdn/aIntegerThe attachment id

Equipment Catalog List

List the equipment available for a sales code.

Path

https://api-uat.cardconnect.com/equipmentCatalog/list?salesCode={salesCode}&equipmentSupplierCd={equipmentSupplierCd}&equipmentTypeCd={equipmentTypeCd}&pageNumber={pageNumber}&pageSize={pageSize}

Method

GET

Consumes

application/json

Produces

application/json

Request Parameters

FieldSizeTypeRequiredComments
salesCode19StringyesThe salesCode
equipmentSupplierCd20enumerationnoThe equipment supplier
equipmentTypeCd20enumerationnoThe equipment type
pageNumbern/aIntegernoThe page number (starting with 1)
pageSizen/aIntegernoThe page size

Response Body Content

FieldSizeTypeComments
rowsn/aList of equipmentList of equipment definitions.
totalServerItemsCountn/aLongTotal number of rows
totalDisplayItemsCountn/aLongThe total number of rows before and including this page
moreRowsAvailablen/aBooleanTrue if the are more rows available on the next page
columnSumsn/an/aInternal use
errorsn/aerrorThe error array if there was a problem creating the order.

Create Order

Path

https://api-uat.cardconnect.com/order

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
ordern/aorderyesThe order definition.

Response Body Content

FieldSizeTypeComments
orderId19LongThe orderId of the order
errorsn/aerrorThe error array if there was a problem creating the order.

Update Order Endpoint

Path

https://api-uat.cardconnect.com/order/{orderId}

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

Example Request Object

Note: the merchantId and equipmentId cannot be changed once an order is created.

FieldSizeTypeRequiredComments
ordern/aorderyesThe order definition.

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if the was a problem updating the order.

Get Order Endpoint

Path

https://api-uat.cardconnect.com/order/{orderId}

Method

GET

Produces

application/json

Response Body Content

FieldSizeTypeComments
ordern/aorderThe order definition.

Find Orders Endpoint

Path

https://api-uat.cardconnect.com/orders?merchantId={merchantId}&pageNumber={pageNumber}&pageSize={pageSize}

Method

GET

Produces

application/json

Request Parameters

FieldSizeTypeRequiredComments
merchantId19LongyesThe merchantId of the merchant
pageNumbern/aIntegernoThe page number (starting with 1)
pageSizen/aIntegernoThe page size

Response Body Content

FieldSizeTypeComments
ordersn/aList of orderThe order definitions.

Cancel Order Endpoint

Only orders in the NEW status can be canceled.

Path

https://api-uat.cardconnect.com/order/{orderId}/cancel

Method

POST

Produces

application/json

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if the was a problem canceling the order.

Create Billing Plan Endpoint

This endpoint will create a new billing plan

Path

https://api-uat.cardconnect.com/billingplan/create

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
billingPlann/aBilling PlanyesThe billing plan definition.

Response Body Content

FieldSizeTypeComments
billingPlann/aBilling PlanThe billing plan definition.
errorn/aerrorThe error array if the was a problem creating the billing plan.

Cancel Billing Plan Endpoint

This endpoint will cancel a billing plan

Path

https://api-uat.cardconnect.com/billingplan/cancel

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
merchId11NumberyesThe mid the billing plan belongs to.
billingPlanId11NumberyesThe billing plan id to cancel.

Response Body Content

FieldSizeTypeComments
billingPlann/aBilling PlanThe billing plan definition.
errorn/aerrorThe error array if the was a problem cancelling the billing plan.

This endpoint will return a 404 status code if the billing plan cannot be found.

List Billing Plans Endpoint

This endpoint will list billing plans for a merchant

Path

https://api-uat.cardconnect.com/billingplan/list/<merchId>

Method

Get

Produces

application/json

FieldSizeTypeRequiredComments
merchId11NumberyesThe mid to search for billing plans.

Response Body Content

FieldSizeTypeComments
billingPlansn/aArray of Billing PlanAn array of billing plans without any payment schedule information. Use the get endpoint to retrieve scheduled payments for a specific billing plan
errorn/aerrorThe error array if the was a problem getting the billing plan.

This endpoint will return a 404 status code if no billing plans can be found.

Get Billing Plan Endpoint

This endpoint will get a billing plan

Path

https://api-uat.cardconnect.com/billingplan/<merchId>/<billingPlanId>

Method

Get

Produces

application/json

FieldSizeTypeRequiredComments
merchId11NumberyesThe mid the billing plan belongs to.
billingPlanId11NumberyesThe billing plan id to cancel.

Response Body Content

FieldSizeTypeComments
billingPlann/aBilling PlanThe billing plan definition.
errorn/aerrorThe error array if the was a problem getting the billing plan.

This endpoint will return a 404 status code if the billing plan cannot be found.

Update Billing Plan Account Endpoint

This endpoint will update the payment account for a billing plan

Path

https://api-uat.cardconnect.com/billingplan/updateAccount

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
merchId11NumberyesThe mid the billing plan belongs to.
billingPlanId11NumberyesThe billing plan id to update.
profileId20NumberyesThe profile to bill.
acctId3NumbernoThe account id within the profile to use. If not provided, the default account will be used.

Response Body Content

FieldSizeTypeComments
billingPlann/aBilling PlanThe billing plan definition.
errorn/aerrorThe error array if the was a problem getting the billing plan.

This endpoint will return a 404 status code if the billing plan cannot be found.

Mark Billing Plan Payment as Paid

This endpoint will update the status of a schedule payment to 'paid'

Path

https://api-uat.cardconnect.com/billingplan/markAsPaid

Method

POST

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
merchId11NumberyesThe mid the billing plan belongs to.
billingPlanId11NumberyesThe billing plan id to update.
billingPlanScheduleId11NumberyesThe the scheduled payment within the billing plan to update.
retref20StringnoThe retref (or refnum) of a transaction to associate with the payment. This can be left as null in if unavailable or in the case of a cash payment. If required, multiple payments may be associated to the same transaction by making multiple calls to this endpoint.

Response Body Content

FieldSizeTypeComments
billingPlann/aBilling PlanThe billing plan definition.
errorn/aerrorThe error array if the was a problem getting the billing plan.

This endpoint will return a 404 status code if the billing plan cannot be found.

Find Custom Fields Endpoint

This endpoint will list custom fields for a merchant

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/customfields

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Create Custom Fields Endpoint


Custom Fields
Custom fields are configured by a partner and they can be labeled, set as active, and set as required in Copilot. If a partner has active required custom fields, then they are required and should be included in the request when creating a merchant. If the partner does not have any active custom fields, then they should not be included in the request when creating a merchant.

Path

https://api-uat.cardconnect.com/merchant/{merchantId}/customfields

Method

PUT

Consumes

application/json

Produces

application/json

Request Body Content

FieldSizeTypeRequiredComments
customFields10List of customFieldyesRequired if the merchant's partner has one or more active required custom fields

Response Body Content

FieldSizeTypeComments
errorsn/aerrorThe error array if there was a problem creating the merchant.

Schemas

Use the below schema definitions for details on fields which you need to supply to any given endpoints.

Check the resources to determine which schema definitions are required for the request.

Merchant Definition

FieldSizeTypeRequiredComments
akaBusinessName200stringno
custPrimaryAcctFlgn/abooleanno
dbaName100stringyes
legalBusinessName500stringyes
taxFilingMethod3stringyesTIN or SSN, can only be SSN if merchant -> ownership -> ownershipType is INDIVSOLE
taxFilingName500stringyes
demographicn/ademographicyes
businessIdTypeCdstringnoUse the following codes ARTICLE,GOVT
businessStartDate8datenoMM/DD/YYYY
bankDetailn/abank detailyes
ownershipn/aownershipyes
merchantContactInfon/acontact infono
salesCode25stringyes
processingn/aprocessingno
webLeadFlgn/abooleanno
pricingn/apricingno
feesn/afeesno
customFields10List of customFieldyesRequired if the merchant's partner has one or more active required custom fields

Owner CardPointe User Definition

FieldSizeTypeRequiredComments
firstName300stringyes
lastName300stringyes
email300stringyes

Demographic Definition

FieldSizeTypeRequiredComments
businessIncorporatedStateCd2enumerationno
merchantTimeZone3stringnoone of (PT, MT, CT, ET, HST)
websiteAddress200stringyesRequired if merchant -> processing -> modeOfTransaction-> eCommercePct is greater than 0
businessPhone12stringno###-###-####
businessFax12stringno###-###-####
businessAddressn/aaddressyes
mailingAddressn/aaddressyes

Bank Detail Definition

FieldSizeTypeRequiredComments
depositBankn/abankyes
withdrawalBankn/abankyes

Bank Definition

FieldSizeTypeRequiredComments
bankAcctNum25stringyes
bankRoutingNum9numericyes
bankAcctTypeCd10enumerationyes
bankName200stringyes

Attachment Definition

FieldSizeTypeRequiredComments
fileName60stringyes
mimeType30stringyes
description1000stringyes
attachmentTypeCdn/aenumerationyes
document100MbBase 64 encoded stringyes

Equipment Definition

FieldSizeTypeComments
equipmentId60LongThe equipment ID
equipmentName60stringThe equipment name
description60stringThe equipment description
make60stringThe equipment make
model60stringThe equipment model
imageUrl60stringThe equipment image url
sku60stringyesThe equipment sku
platformCd60stringThe equipment platform
equipmentTypeCd60enumerationThe equipment type
equipmentSupplierCd60enumerationThe equipment supplier code
defaultPrice60stringThe default one time price
defaultPlanPrice60stringThe default monthly price if allowed
allowCustomBillingFlg60stringTrue if monthly billing is allowed
standardShippingPrice60stringThe standard shipping price (per unit)
expeditedShippingPrice60stringThe expedited shipping price (per unit)

Order Definition

FieldSizeTypeRequiredComments
orderId19LongnoThe merchantId the order is for. (cannot set this value, only used for GET)
merchantId19LongyesThe merchantId the order is for.
equipmentId19LongyesThe equipmentId the order is for.
orderNotes1000StringnoOptional notes for the person fulfilling the order.
quantity4IntegeryesThe number of devices being ordered.
unitPrice10Numberyes (when billToFrequencyCd is ONETIME)The price per unit.
monthlyPrice10Numberyes (if billToFrequencyCd is MONTHLY)The price per month.
billToCd100enumerationyesWho to bill for this order
billingFrequencyCd100enumerationyesBilling frequency
profileIdn/aStringyes (if billToCd is PARTNERCC)The profileId of the card to charge for this order.
acctId10Numberyes (if billToCd is PARTNERCC)The account number to charge for this order.
shippingDetailsn/ashippingdetailyes
orderStatusCdn/aenumerationno
placedDatetimen/aStringnoThe date the order was placed (Usually when right after the merchant signs the application)
shippedDatetimen/aStringnoThe date the order was shipped
canceledDatetimen/aStringnoThe date the order was canceled
fulfillingDatetimen/aStringnoThe date the order was fulfilled

Order Shipping Details Definition

FieldSizeTypeRequiredComments
shippingAddressn/aaddressyes
shipToAttn100StringyesName of the person receiving the order.
shipToAttnEmail100StringyesEmail of the person receiving the order.
shippingMethodCd100enumerationyesThe shipping method to be used.
shippingBillToCd100enumerationyes (if shippingMethodCd is EXPEDITED)Who to bill for the shipping (only set if shippingMethodCd is EXPEDITED)
shippingCarrierCd100enumerationnoThe shipping carrier
trackingNumber100StringnoThe shipping carrier
shippingCostn/aDecimalnoThe shipping cost
merchantContactPhone12Stringyes###-###-####
merchantContactPhoneExt5Stringno#####
poNumber30StringnoPurchase order number

Ownership Definition

FieldSizeTypeRequiredComments
ownern/aowneryes
ownershipTypeCd10enumerationno
driversLicenseNumber100stringyes
driversLicenseStateCd2enumerationyes
ownerOwnershipPct3numericno0-100%

Owner Definition

FieldSizeTypeRequiredComments
ownerAddressn/aaddressyes
ownerEmail300stringyes
ownerName300stringyes
ownerDob8stringnoMM/DD/YYYY
ownerPhone12stringyes###-###-####
ownerMobilePhone12stringyes###-###-####
ownerSSN11stringyes###-##-####
ownerTitle200stringyesSee List Below

Valid Owner Titles

Ownership TypeValid Owner Titles
PRTNRGEN (Partnership (General))PARTNER
PRTNRLIM (Partnership (Limited))PARTNER
GOVT (Government)OWNER, PARTNER, PRESIDENT, VICE_PRESIDENT, MEMBER_LLC, SECRETARY, TREASURER, CEO, CFO, COO
PUBCORP (Public Corporation)PRESIDENT, VICE_PRESIDENT, SECRETARY, TREASURER, CEO, CFO, COO
LLC (LLC)PRESIDENT, VICE_PRESIDENT, SECRETARY, TREASURER, CEO, CFO, COO, MEMBER_LLC
PRIVCORP (Private Corporation)PRESIDENT, VICE_PRESIDENT, SECRETARY, TREASURER, CEO, CFO, COO
SUBSCORP (Subchapter S Corporation)PRESIDENT, VICE_PRESIDENT, SECRETARY, TREASURER, CEO, CFO, COO
TAXEXMPT (Tax Exempt)OWNER, PARTNER, PRESIDENT, VICE_PRESIDENT, MEMBER_LLC, SECRETARY, TREASURER, CEO, CFO, COO
NONPRFT (Non-Profit Org)OWNER, PARTNER, PRESIDENT, VICE_PRESIDENT, MEMBER_LLC, SECRETARY, TREASURER, CEO, CFO, COO
INDIVSOLE (Individual / Sole Proprietor)OWNER

Merchant Contact Info Definition

FieldSizeTypeRequiredComments
contactName300stringno
contactEmail300stringno
contactPhone12stringno###-###-####

Processing Definition

FieldSizeTypeRequiredComments
platformDetailsn/aplatform detailsyes
businessDetailsn/abusiness detailsyes
volumeDetailsn/avolume detailsyes
blueChexVolumen/aBlueChex volume detailsnoRequired for applications that include the BlueChex add on and a digital signature.
deliveryPercentagesn/adelivery detailsno
modeOfTransactionn/amode of transaction detailsno

Platform Details Definition

FieldSizeTypeRequiredComments
backEndMid25stringno (yes for CardPointe only accounts)
frontEndMid25stringno (yes for CardPointe only accounts)
processorReportingMid25stringno (yes for CardPointe only accounts)
backEndPlatform20enumerationno (yes for CardPointe only accounts)
frontEndPlatformCd20enumerationno (yes for CardPointe only accounts)
amexProgramAssetCd7enumerationyes
amexProgramMid25stringyes
discoverMid25stringyes
discoverProgramCd10enumerationyes
acquiringFlgn/abooleanyestrue = Merchant Services, false = CardPointe only
taxId9numericno
tidstringno
busnsIdstringno
busnsIdPlaceOfIssue2enumerationyesstate code
currencyCode5enumerationno
mccId5stringyes(numeric)
businessDescription4000stringyes

Business Details Definition

FieldSizeTypeRequiredComments
customerBillPriorToShipFlgn/abooleanno
depositReqForFulfillFlgn/abooleanno
whenCustomerChargedCd10enumerationno
refundPolicyCd10enumerationno
serviceProvidedInCd10enumerationno

Volume Details Definition

FieldSizeTypeRequiredComments
averageMonthlyVolume18.2decimalyes
highTicketAmount18.2decimalyes
averageTicketAmount18.2decimalyes

Blue Chex Volume Definition

The blueChexVolume object is required for merchants with the BlueChex add on. All fields must be provided.

FieldSizeTypeDescription
avgPerTransactionSalesAmount18.2DecimalAverage sales amount per BlueChex transaction.
maxPerTransactionSalesAmount18.2DecimalMaximum sales amount per BlueChex transaction.
avgPerTransactionCreditAmount18.2DecimalAverage credit (refund) amount per BlueChex transaction.
maxPerTransactionCreditAmount18.2DecimalMaximum credit (refund) amount per BlueChex transaction.
avgPerMonthSalesAmount18.2DecimalAverage monthly sales amount for all BlueChex transactions.
maxPerMonthSalesAmount18.2DecimalMaximum monthly sales amount for all BlueChex transactions.
avgPerMonthCreditAmount18.2DecimalAverage monthly credit (refund) amount for all BlueChex transactions.
maxPerMonthCreditAmount18.2DecimalMaximum monthly credit (refund) amount for all BlueChex transactions.

Delivery Details Definition

FieldSizeTypeRequiredComments
dlvry0To7DaysPct3numericno0-100%
dlvry15To30DaysPct3numericno0-100%
dlvry8To14DaysPct3numericno0-100%
dlvryOver30DaysPct3numericno0-100%

Mode of Transaction Details Definition

FieldSizeTypeRequiredComments
eCommercePct3numericyes0-100%
keyedPct3numericyes0-100%
mailOrderPct3numericyes0-100%
swipedPct3numericyes0-100%

Pricing Definition

FieldSizeTypeRequiredComments
flatPricingn/aflat pricingyes

FieldSizeTypeRequiredComments
icPlusPricingn/aicplus pricingyes

Flat Pricing Definition

FieldSizeTypeRequiredComments
amex.esaQualDiscountPct7.3decimalyesOnly valid if amexProgramAssetCd is ESA
amex.optBlueQualDiscountPct7.3decimalyesOnly valid if amexProgramAssetCd is OPTBLUE
discover.qualCreditDiscountPct7.3decimalyes
mastercard.qualCreditDiscountPct7.3decimalyes
visa.qualCreditDiscountPct7.3decimalyes

IC-Plus Pricing Definition

FieldSizeTypeRequiredComments
amex.optBlueQualDiscountPct7.3decimalyesOnly valid if amexProgramAssetCd is ESA
discover.qualCreditDiscountPct7.3decimalyes
mastercard.qualCreditDiscountPct7.3decimalyes
visa.qualCreditDiscountPct7.3decimalyes

Fees Definition

FieldSizeTypeRequiredComments
achBatchFee7.3decimalyes
addressVerifFee7.3decimalyes
annualMembershipFee8.2decimalyes
appFee8.2decimalyes
authFee7.3decimalyes
chargebackFee8.2decimalyes
dataBreachFee8.2decimalyes
ddaRejectFee8.2decimalyes
earlyCancelFee8.2decimalyes
minProcessFee8.2decimalyes
monthlyEquipmentRentalFee8.2decimalno
pciAnnualFee8.2decimalyes
pciNonComplianceFee8.2decimalyes
regProdMonthlyFee8.2decimalyes
retrievalFee8.2decimalyes
statementFee8.2decimalyes
tranFee7.3decimalyes
voiceAuthFee7.3decimalyes
wirelessActivationFee8.2decimalyes
wirelessFee8.2decimalyes
duesAndAssessmentsFlgn/abooleanno
passthruInterchgCostsFlgn/abooleanno

Custom Field Definition

FieldSizeTypeRequiredComments
userFieldNumbern/anumericyesThe index of the custom field being set. Must be a number between 1-10
customFieldValue100stringyesRequired if the merchant's partner has made the custom field at this index required

Owner Site User Definition

FieldSizeTypeRequiredComments
firstName300stringyes
lastName300stringyes
email300stringyes

Address Definition

FieldSizeTypeRequiredComments
address1200stringyes
address2200stringno
city300stringyes
countryCd2enumerationno
stateCd2enumerationno
zip15stringyes

Billing Plan Definition

FieldSizeTypeRequiredComments
billingPlanId11NumbernoThe id of the billing plan, should be null when creating a new plan
merchId11NumberyesThe mid the billing plan is being created for
profileId20NumberyesThe profile being billed
acctId3NumbernoThe account id within the profile to use. If not provided when creating a billing plan, the default account will be used. This field is always returned when retrieving a billing plan.
amountNumberyesThe amount to bill per time period
timeSpanNumberyes1 for daily, 2 for weekly, 3 for monthly, or 4 for yearly
everyNumberyesBill the customer every x time periods
untilCondition1CharacteryesC for cancelled, N for number of payments, D for date
untilNumPaymentsNumberSee CommentsRequired if untilCondition = N
untilDate8StringSee CommentsRequired if untilCondition = D. Date format: MMDDYYYY
currencySymbol1CharacteryesThe currency symbol for the transaction
startDate8StringyesDate format: MMDDYYYY
billingPlanName30StringyesDisplay name
optionsArrayyesThe email_receipt option should be provided with a value of 0 for no or 1 for yes. See example JSON.
planSatus1CharacternoThe billing plan status. A for active or C for cancelled.
billingPlanSchedulesArray of Billing Plan SchedulesnoAn array of the payments in the billing plan. This cannot be set, it is only returned when fetching a billing plan. This array will always contain all past payments. In addition, it will also contain future scheduled payments (up to 1000 when untilCondition = N or D, or one year of payments when untilCondition = C)

Billing Plan Schedule Definition

FieldSizeTypeRequiredComments
billingPlanScheduleIdNumberyesThe id of the billing plan schedule entry.
actualAmountNumbernoThe amount that was actually billed, if this payment was processed.
actualPaymentDateDatenoThe date this payment was made, if it was processed.
paymentStatusStringyesScheduled, Cancelled, Paid, or Failed.
retrefStringnotThe transaction id, if it was processed.
scheduledAmountNumberyesThe amount scheduled to be billed.
scheduledPaymentDateDateyesThe date the transaction is scheduled for

Enumeration Definition

Bank Account Type Codes

Path

https://api-uat.cardconnect.com/lookup/bankAcctTypes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Ownership Type Codes

Path

https://api-uat.cardconnect.com/lookup/ownershipTypes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Country Codes

Path

https://api-uat.cardconnect.com/lookup/countryCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

State Codes

Path

https://api-uat.cardconnect.com/lookup/stateCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

When Customer Charged Codes

Path

https://api-uat.cardconnect.com/lookup/whenCustomerChargedCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Refund Policy Codes

Path

https://api-uat.cardconnect.com/lookup/refundPolicyCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Service Provided In Codes

Path

https://api-uat.cardconnect.com/lookup/serviceProvidedInCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Front End Platform Codes

Path

https://api-uat.cardconnect.com/lookup/frontEndPlatformCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Back End Platform Codes

Path

https://api-uat.cardconnect.com/lookup/backEndPlatformCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Discover Program Codes

Path

https://api-uat.cardconnect.com/lookup/discoverProgramCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Amex Program Asset Codes

Path

https://api-uat.cardconnect.com/lookup/amexProgramAssetCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Shipping Method Codes

ValueComments
STANDARDStandard ground shipping
EXPEDITEDExpedited shipping

Attachment Type Codes

Path

https://api-uat.cardconnect.com/lookup/attachmentTypeCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Bill To Codes

Path

https://api-uat.cardconnect.com/lookup/billToCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Bill To Detail Codes

Path

https://api-uat.cardconnect.com/lookup/billToDetailCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Billing Frequency Codes

Path

https://api-uat.cardconnect.com/lookup/billingFrequencyCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Order Status Codes

Path

https://api-uat.cardconnect.com/lookup/orderStatusCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Shipping Carrier Codes

Path

https://api-uat.cardconnect.com/lookup/shippingCarrierCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Shipping Method Codes

Path

https://api-uat.cardconnect.com/lookup/shippingMethodCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Equipment Supplier Codes

Path

https://api-uat.cardconnect.com/lookup/equipmentSupplierCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Equipment Type Codes

Path

https://api-uat.cardconnect.com/lookup/equipmentTypeCodes

Method

GET

Consumes

application/json

Produces

application/json

Response Body Content

Errors

When there is an error in the request, there will be a non-null errors array in the response body. If there are multiple field validation errors, there will be multiple error objects in the errors array. See the example below.

Error Definition

FieldTypeComments
codeStringThe error code (see codes below)
messageStringThe error message
errorFieldStringThe field that caused the error
statusStringThe HTTP Status Code