Braintree Sandbox Contact Sales

Card Data Collection

This page discusses using the Card Data Collection feature, which allows you to collect raw card track data for Non-PCI cards that adhere to ISO-7813 format.

Feature Overview

The Card Data Collection feature is designed to allow merchants to use Braintree card readers to read magstripe track data from non-PCI scoped cards. For example, these would include 3rd party (non-cobranded) gift cards (ex: SVS, Givex, Valuelink, etc...) and (non-cobranded) closed-loop private label cards (ex: Bread Financial/ADS, Synchrony, CitiBank, etc...) as long as they adhere to ISO 7813 format. This feature is architected to give full control of the flow and experience to the API caller (typically a POS system). Braintree does not send the collected card data to any 3rd party card issuer, it is up to the API caller to do so from the POS or another system.

Braintree will never return PCI card data if a PCI-scoped card is swiped on the Braintree reader.

Setup and Configuration

To use this feature, Braintree must have your non-PCI card BIN ranges configured on the Braintree gateway account. Please work with your Braintree Solutions Engineer or Integration Engineer to configure this before use.

For sandbox testing purposes, we will require the full card numbers of your non-PCI cards used for testing or at least the first 8 digits of the test cards.

Initiate a request to collect card data

To begin this flow, you would first use the requestNonPCICardDataFromInStoreReader API mutation to initialize the reader for a card swipe. Within this request, you can control the messaging displayed on the reader swipe prompt by using the title, textAreaOne, and textAreaTwo API variable fields. This is where you would indicate the transaction type (ex: Gift Card or Private Label Credit Card, etc...) as well as the amount to be charged/redeemed and any other call to action for your customer, such "please swipe". You may also use the waitForNextRequest variable to indicate whether you want to display a processing spinner screen after the swipe. Once Braintree reads the card data, it is checked to make sure the card is not within a known PCI BIN range (if it is, an error will be returned). As long as the card is recognized as a non-PCI card and falls within the merchant account configured BIN ranges, Braintree will allow for the API caller to retrieve the entire track 1 and track 2 card data.

Example card data collection request:

mutation RequestNonPciCardDataFromInStoreReader($input: RequestNonPciCardDataFromInStoreReaderInput!) {
    requestNonPciCardDataFromInStoreReader(input: $input) {
        clientMutationId
        id
    }
}

After the reader is initialized, your application must wait for the customer to interact with it (i.e. swipe a card) and card data to be read. Your application should use the node query to poll on a 2-second interval between responses for the current status of the payment using the Context.id received at request initialization and monitor the InStoreContext.statusfield as the request goes through the lifecycle. The result of this polling will be to retrieve the track 1 and track 2 data read from the swiped card.

Example card data collection query:

query ID($contextId: ID!) {
  node(id: $contextId) {
    ... on RequestNonPciCardDataInStoreContext {
      __typename
      id
      status
      cardData {
        ... on NonPciFinancialCardMagneticStripeData {
            track1
            track2
        }
      }
      reader {
        id
        name
        status
      }
    }
  }
}

Note that magstripe track data returned in the response may vary depending on the card formatting. Braintree returns whatever track data is retrievable from the card.

Displaying the transaction result

Since Braintree is not actually processing the transaction, it is up to the API caller to display the transaction result for the customer. You may do this by utilizing the requestTextDisplay API mutation using the title and text API variable fields. For example, you may choose to display a title with Approved or Thank You for Your Purchase! and a text with You have redeemed $44 from your gift card for today's purchase. This messaging is entirely customizable by the API caller according to the use case and the operation being performed, this includes any error messaging that you want to display to your customer.

When showing the transaction result, it is suggested to avoid displaying any customer PII data.

Tips when Integrating Card Data Collection

  • Card Data Collection is NOT supported for offline processing

  • The cards being swiped must be ISO 7813 formatted

  • The cards being swiped must not conflict with a known PCI-scoped BIN range

  • You'll need to have your Braintree account configured with your defined card BIN ranges

  • When using Card Data Collection, the response data tied to the context ID is retrievable for about 10 minutes

  • When using Card Data Collection, the response data tied to the context ID will be deleted after the first successful retrieval

Data Processing

Please refer to our page on PayPal Braintree Sub-processors to understand what other entities may come in contact with data collected through our Card Data Collection feature

PreviousCustom PromptsNextGraphQL Error Handling

Last updated