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 Cloud 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.

Generate a bearer token before sending each request. For more information, see Generating a Bearer Token for Authentication.

Endpoints

Test:

POST https://terminalstest.cybersource.com/v1/cloud/transactions

Production:

POST https://terminals.cybersource.com/v1/cloud/transactions

Required Fields for a Custom Card Read

serialNumber: Set the value to the serial number of the terminal.
request.type: Set the value to
ReadCardRequest
.

REST Example: Custom Card Read

Request

{
  "serialNumber": "1850000000",
  "request": {
    "type": "ReadCardRequest"
  }
}

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."
}