CardPointe

CardPointe is a direct merchant payment processor powered by CardConnect that enables standalone merchants to accept credit card, ACH (bank account), and digital wallet payments.

Supported Capabilities

Supported Transaction Types

ACH transactions support Sale, Refund, and Verify only. Auth, Capture, and Void requests with a bank account are rejected — use Sale instead of Auth + Capture, and refund an ACH transaction after settlement rather than voiding it.

Adding Merchant Credentials

To connect CardPointe, you'll need the following credentials from your CardPointe account:

📘

Credential Verification

Preczn automatically verifies your CardPointe credentials when you save them. If verification fails, you'll receive an "Invalid connection credentials" error. Double-check that your API username, password, and merchant ID are correct and that your account is active.

Configuration Methods

CardPointe credentials can be configured through three methods:

Dashboard Upload

Upload credentials directly through the merchant connection settings in the Preczn Dashboard.

1. Navigate to Merchants > select merchant > Connections
2. Click Add Connection and select CardPointe
3. Enter your API Username, API Password, and Merchant ID
4. Optionally enter your Site URL Prefix
5. Save the connection

Merchant Import

Include CardPointe credentials when importing merchants via CSV. Use the following column headers:

API Integration

Configure credentials programmatically using the merchant connections endpoint:

curl --request PATCH \
  --url https://api.preczn.com/v1/merchants/{merchantId}/connections/CardPointe \
  --header 'Authorization: Bearer {api_key}' \
  --header 'Content-Type: application/json' \
  --data '{
    "key": "{API Username}",
    "secret": "{API Password}",
    "mid": "{Merchant ID}",
    "urlPrefix": "{Site URL Prefix}"
}'

Request Fields

⚠️

No Spaces Allowed

The key, secret, mid, and urlPrefix fields cannot contain spaces. Requests with spaces in these fields will be rejected.

Site URL Prefix

CardPointe uses site-specific URLs to route API requests. The site URL prefix determines which CardPointe environment your transactions are sent to — for example, a prefix of site-uat resolves to https://site-uat.cardconnect.com. Test and live connections are configured separately, so make sure each connection's prefix points at the matching CardPointe environment.

How It Works

The site URL prefix can be configured at two levels:

1. Merchant connection — Set on the individual merchant's CardPointe connection
2. Platform connection — Set as a default on the platform-level CardPointe connection

Preczn resolves the request URL for every transaction as follows:

📘

When to Set URL Prefix

Most integrations should set the urlPrefix at the platform level so all merchants share the same CardPointe site. Only set it at the merchant level if a specific merchant uses a different CardPointe site than the rest of your portfolio.

Digital Wallets

CardPointe supports Apple Pay and Google Pay. Wallet payments are card transactions, so they follow the same flow as any other card payment on this connection — you send the wallet payload to Preczn exactly as you would for any other connection, and Preczn maps it to CardPointe's format.

Capture, Refund, and Void act on an existing transaction rather than on payment data, so they work normally against a wallet-funded sale or authorization — there is simply no wallet payload to send.

Google Pay works with both of its token formats. A device token (CRYPTOGRAM_3DS) is sent with its cryptogram, and a card-on-file token (PAN_ONLY) is sent as ordinary card data.

📘

Wallet Transactions Are Not Labelled in CardPointe

CardPointe's API has no wallet indicator field, so an Apple Pay or Google Pay transaction appears alongside ordinary card transactions in CardPointe's reporting with nothing marking it as a wallet payment.

If you need to tell them apart on the CardPointe side, send an identifying value in metadata — it is forwarded as a userfield. See Transaction Metadata below.

Transaction Metadata

Preczn forwards the metadata object on a transaction to CardPointe as userfields, making your custom transaction data available in CardPointe's reporting. See Metadata for the platform-wide rules that apply to the metadata object.

Sale, Auth, and Verify all reach CardPointe as authorization requests, so each one carries userfields — for both card and ACH transactions. Preczn does not send userfields on Capture, Refund, or Void requests; metadata sent at authorization stays attached to the transaction in CardPointe.

How Metadata Maps to Userfields

Each key/value pair in metadata becomes a single-key object in the userfields array, in the order the keys appear in your request.

Your Preczn request:

{
  "type": "sale",
  "amount": 1000,
  "currency": "USD",
  "metadata": {
    "orderRef": "ord-58213",
    "campaign": "spring-promo",
    "channel": "mobile-app"
  }
}

What Preczn sends to CardPointe:

{
  "userfields": [
    { "orderRef": "ord-58213" },
    { "campaign": "spring-promo" },
    { "channel": "mobile-app" }
  ]
}

When a transaction has no metadata, or metadata is empty, userfields is omitted from the CardPointe request entirely.

Size Limit

CardPointe limits userfields to 4,000 bytes once JSON-encoded (1 character = 1 byte). Preczn sends your metadata exactly as you supplied it and never shortens values to fit.

⚠️

CardPointe Discards Oversized Userfields

If the encoded userfields payload exceeds 4,000 bytes, CardPointe still accepts and approves the transaction — but silently discards every userfield. None of your metadata reaches CardPointe reporting, and no error is returned.

Your metadata is always stored on the Preczn transaction either way, and stays available through the Get Transaction endpoint.

Reaching the limit takes deliberately large metadata. Preczn accepts up to 20 keys, each key up to 20 characters and each value up to 255 characters. At those maximum lengths, 15 entries encode to 4,246 bytes and cross the limit, and a full 20 entries encode to 5,661 bytes. Typical metadata stays well under it.

📘

Custom Field Reporting Order

The CardPointe web application's custom-field transaction reporting expects userfields in the order configured for your merchant account. Preczn sends them in the order the keys appear in your metadata object and has no visibility into your CardPointe column configuration.

If you use that reporting feature, send your metadata keys in the same order as your configured columns.