Keyed Card

Keyed card payments are card transactions where you manually enter the card number, expiration date, and security code instead of reading them from a magstripe, chip, or NFC device. They’re useful as a backup when hardware isn’t available and for scenarios like mail or telephone orders.

Prerequisites and limitations

• Prerequisites: Access to the PCE /payment API and a merchant account enabled for card payments.
• Limitations: Keyed transactions are considered higher risk than card-present EMV/NFC/swipe, which can mean higher processing fees and greater fraud exposure.

When to Use Keyed Card Payments

There are many scenarios where keyed payments make sense. Common examples include:

• No physical card present: The merchant doesn’t have the card in hand and receives card details directly from the cardholder — for example, phone orders.
• Customer self-entry online: The customer types their own card details into a web form for ecommerce or an online bill-pay page.
• Fallback when hardware fails: The card reader can’t detect the magstripe, chip, or NFC tap, so the merchant keys the card as a backup.
• Low-volume merchants without hardware: Keyed payments provide a simple and cost-effective way to accept cards without investing in terminals or readers.

Presentment Types for Keyed Transactions

“Presentment type” indicates how the card data was obtained. For keyed card information, the typical options are:

• Card Not Present (CNP) keyed The merchant doesn’t have the physical card. Card data is provided by the cardholder remotely (for example, by phone or an online form).

• Card Present keyed The merchant has the physical card in hand but manually keys the details instead of using a reader.

You should choose the presentment type that accurately reflects how you collected the card information, as this can affect risk and pricing.

Things to Keep in Mind

• Simple integration: No special hardware is required — just your application and the payment API.
• Higher risk and potential fees: Because keyed transactions are easier to fraudulently abuse, they often carry higher processing fees compared to swipe, EMV, or NFC.
• Greater fraud exposure: When you don’t physically verify the card (especially for Card Not Present), there’s an increased risk of chargebacks and fraud.
• Slower customer experience: Manually entering full card details takes longer and can slow down checkout for both staff and customers.

Make a Keyed Payment Request

Keyed transactions send card details directly in the cardAccount object on the /payment endpoint.

Endpoint

Steps

1. Set up the HTTP request

   • Use the POST method.
   • Call the /payment endpoint in the appropriate environment (sandbox or production).

2. Add authentication and headers

   • Send your username and password in the Authorization header using Basic auth.

     • Encode username:password as Base-64 and prefix with Basic .

   • Set the Content-Type header to application/json.

3. Provide card details in the request body

   In the cardAccount object, include the card number, expiration, and other required fields:

   JSON

   {
     "merchantId": "4xxx0",
     "tenderType": "Card",
     "amount": "0.01",
     "cardAccount": {
       "number": "4111xxxxxxxx1111",
       "expiryMonth": "02",
       "expiryYear": "22",
       "cvv": "123",
       "avsZip": "30004",
       "avsStreet": "1234"
     }
   }

   Typical fields:

   • merchantId: Your merchant identifier.
   • tenderType: "Card" for credit/debit card payments.
   • amount: Transaction amount.
   • cardAccount.number: Primary account number (PAN).
   • cardAccount.expiryMonth / cardAccount.expiryYear: Card expiration.
   • cardAccount.cvv: Card verification value (security code).
   • cardAccount.avsZip / cardAccount.avsStreet: AVS data to help with address verification.

4. (Optional) Return the full response

   • If supported for this endpoint in your environment, append ?echo=true to return the full payment object in the response rather than making a follow-up GET.

5. Verify the response

   • A successful keyed payment returns HTTP 201 Created.
   • The payment object’s status field should be Approved when the transaction is approved.
   • Use test cards and documented negative test scenarios to validate declines and error handling.