On This Page

Custom Card Read

Use this information to obtain data from custom cards such as gift cards, loyalty program cards, and employee cards when the app is in Local mode. This service cannot be used to perform payment functions.

IMPORTANT

Custom Card Read is supported for non-PCI cards only. To use this service, the card type must be on your allowlist. To add a card type to your allowlist, contact your implementation manager.

To retrieve the card data, swipe the card’s magnetic stripe through the payment device. The custom card read-only function reads and returns the raw card identifier to your app or point-of-sale (POS) system. You can then use the raw data within your app or POS system.

These are examples of how you might use the Custom Card Read feature:

Custom gift card:
Use the card number to check a balance or process a payment in your private gift card network.

Employee card:
Use the card number to look up an employee's profile or account.

Endpoints

The endpoint is the same for the test and production environments.

Test:

wss://{terminal IP address:port number}/

Production:

wss://{terminal IP address:port number}/

Required Fields to Perform a Custom Card Read

type: Set the value to
ReadCardRequest
.

REST Example: Custom Card Read

Request

{
   "type" : "ReadCardRequest"
}

Mid-Transaction Status Updates

During the transaction, you might receive one or more update responses indicating the current status of the transaction. You can choose to display these updates on your point-of-sale (POS) system.

{
   "type": "OperationStatusResponse",
   "message": "Status update to display."
}

Response to a Successful Request

{
  "type": "ReadCardResponse",
  "message": "Read Card Successfully",
  "cardDetails": {
    "expiryMonth": 12,
    "expiryYear": 2025,
    "track1": "%B4111111111111111^DOE/JOHN^2512101?",
    "track2": "4111111111111111=25121010000?",
    "cardNumber": "4111111111111111"
  }
}

Response to an Unsuccessful Request

When the request is unsuccessful, you receive an error response with details.

{
   "type": "ErrorResponse",
   "message": "Error message to display.",
   "developerDescription": "Detailed description of error."
}