Card Keyed Transaction

A Card Present (CP) keyed transaction lets you process payments when the cardholder is physically present at the merchant location — without requiring a physical payment terminal. The key distinction for a CP transaction is that both the cardholder and the payment card are physically present, not whether a terminal device was used.

Unlike terminal transactions that automatically populate posData values, keyed transactions require you to provide the correct posData fields in the API request to ensure accurate interchange classification and network routing.

Common use cases include:

In-Store Kiosk: A customer enters their card information directly into a self-service kiosk at the merchant location.
In-Store Web Application: A customer enters their card information on a payment webpage served at the merchant's physical location.
Attended Manual Entry: A cashier manually keys the card information while the customer and their card are physically present.

How it Works

Keyed CP transactions require you to set cardPresent to true and populate the posData object to accurately reflect the transaction environment. Two configurations are supported depending on whether you intend to capture the payment immediately or at a later time.

Keyed Authorization (Preauthorization)

Use this configuration when performing an authorization-only transaction that will be captured later. Set authorizationIndicator to "Undefined" and transactionStatus to "Preauthorization".

{
  "cardPresent": true,
  "authorizationIndicator": "Undefined",
  "posData": {
    "cardholderPresence": "Present",
    "deviceAttendance": "Attended",
    "deviceInputCapability": "KeyedOnly",
    "deviceLocation": "OnPremise",
    "panCaptureMethod": "Manual",
    "partialApprovalSupport": "Supported",
    "transactionStatus": "Preauthorization"
  }
}

Keyed Sale

Use this configuration when the transaction is intended to be finalized immediately. Set authorizationIndicator to "Final" and transactionStatus to "Normal".

{
  "cardPresent": true,
  "authorizationIndicator": "Final",
  "posData": {
    "cardholderPresence": "Present",
    "deviceAttendance": "Attended",
    "deviceInputCapability": "KeyedOnly",
    "deviceLocation": "OnPremise",
    "panCaptureMethod": "Manual",
    "partialApprovalSupport": "Supported",
    "transactionStatus": "Normal"
  }
}

Understanding Partial Approvals

The partialApprovalSupport field determines whether the issuing bank can approve a portion of the requested amount when the card has insufficient funds for the full transaction.

Value	Description	When to use
`Supported`	The issuer can approve a partial amount. Your application collects the remaining balance using another payment method.	Use when your application supports split-tender payments.
`NotSupported`	The transaction is declined if insufficient funds are available. No partial approval is returned.	Use when your application does not support multiple payment methods for a single transaction.

Example: Purchase amount is $100. Available funds on the card are $60. The issuer approves $60, and the merchant collects the remaining $40 using another payment method.

📘
Important Notes

Physical presence of the cardholder — not the use of a payment terminal — determines a CP transaction.

Kiosks, attended checkout stations, and in-store web applications all qualify as CP transactions when the customer is physically present.

Payment terminals automatically populate posData values. For manually keyed CP transactions, ensure the posData object accurately reflects how the transaction was performed.

Best Practices

Practice	Description
Always set `cardPresent: true` for CP transactions	Physical cardholder presence — not terminal use — determines a CP transaction. Setting `cardPresent: false` classifies the transaction as card-not-present, resulting in higher interchange rates.
Accurately reflect the transaction environment in `posData`	Each `posData` field must match the actual transaction context. Incorrect values cause interchange downgrades or network declines.
Use `Preauthorization` when capturing later	Set `transactionStatus` to `"Preauthorization"` for authorization-only transactions. Use `"Normal"` only when finalizing the payment immediately.
Handle partial approvals explicitly	If your application supports split-tender payments, set `partialApprovalSupport` to `"Supported"` and handle partial approval responses in your integration logic.

Common use cases include:

How it Works

Keyed Authorization (Preauthorization)

Keyed Sale

Understanding Partial Approvals

Best Practices

See Also