Display Information

This guide shows how to display information to your customers using the card reader screen.

Getting Started

The following Graph QL API mutations can be used to display text on the reader screen for your customers. This can be used for a range of business logic from displaying cart items, showing a shipping address confirmation (Note: you can also leverage Custom Prompts for a more automated version of this), or even a plain text welcome message.

Information Displays will not block subsequent reader interactions, meaning you can make repetitive display requests without first canceling a previous one. You can also make a requestChargeFromInStoreReader call while the reader is displaying information, and it will transition into a checkout flow.

The response of these API requests will include a contextId which can be used to cancel the information display.

Information Display requests will stay on the screen for 120 seconds or until canceled or overwritten by a subsequent reader interaction.

Request Text Display

This mutation will allow you to push plain text to the screen. This could be used for something like a shipping address confirmation, as shown in the below picture. The Braintree GraphQL API docs contain additional information about character limitations and formatting your request Text Display mutation.

Up to 255 characters of text can be displayed using this mutation

As of version 5.2.0 requestTextDisplay now supports the title, alignment, waitForNextRequest, displayTimeoutAPI variable fields

This example image includes the title variable which is supported as of version 5.2.0

GraphQL Mutation

mutation RequestTextDisplayFromInStoreReader($input: RequestTextDisplayFromInStoreReaderInput!) { 
    requestTextDisplayFromInStoreReader(input: $input) { 
        clientMutationId 
        id 
        reader { 
           id 
           name
           status 
        } 
        status 
    } 
}

GraphQL Variables

{
  "input": {
    "readerId": "your reader ID",
        "text": "Shipping Address:\n\n 123 Fake St.\n Newport Beach, CA \n USA" 
  }
}

Sample API Response

{
  "data": {
      "requestTextDisplayFromInStoreReader": {
          "clientMutationId": null,
          "id": "aW5zdG9yZWNvbnRleHRfIzhjMjgxM2ZiMWUwNDRmZTRiNDFiOWVjYmVjOTExY2YxI1ZFUklGT05FLTgwMy00MTUtMTY0I3VzLWVhc3QtMg",
          "reader": {
              "id": "aW5zdG9yZXJlYWRlcl8jaHo0YzYyeHp0OGZocjc2eSNWRVJJRk9ORS04MDMtNDE1LTE2NA",
              "name": "P400 Desk",
              "status": "ONLINE"
          },
          "status": "PENDING"
      }
  },
  "extensions": {
      "requestId": "57971749-2037-4421-b2ad-7c3f0a0a163a"
  }
}

Request Line Item Display

This mutation can be called each time the POS software adds an item to display the running cart totals to the customer.

As items are added, a scrolling container will automatically move to keep the most recently added items in view.

Adding new items to the display will require the POS to send all items in the cart and new running totals after each update.

Up to 249 items can be displayed using this mutation.

The displayItems are used for display formatting purposes only and are not passed downstream to the processors or saved in relation to the transaction. All calculations must be performed on the POS. Additional information about character limitations and formatting your mutation can be found in our Braintree GraphQL API docs.

GraphQL Mutation

mutation RequestItemDisplayFromInStoreReader($input: RequestItemDisplayFromInStoreReaderInput!) { 
    requestItemDisplayFromInStoreReader(input: $input) { 
        clientMutationId 
        id 
        reader { 
            id 
            name 
            status
        } 
        status 
    } 
}

GraphQL Variables

{ 
    "input": { 
        "readerId": "{{BT_reader_id}}", 
        "displayItems": [ 
            {  
                "kind": "CHARGE",  
                "description": "Red shirt", 
                "quantity": 1, 
                "amount": "21.00" 
            }, 
            { 
                "kind": "CHARGE",  
                "description": "Khaki pants", 
                "quantity": 2, 
                "amount": "80.00" 
            },
            {
                "kind": "DISCOUNT",
                "description": "BOGO pants sale",
                "amount": "40.00"
            },
            { 
                "kind": "CHARGE",  
                "description": "Blue cardigan", 
                "quantity": 1, 
                "amount": "22.00"
            },
            { 
                "kind": "CHARGE",  
                "description": "Denim jeans", 
                "quantity": 1, 
                "amount": "73.00"
            },
            {
                "kind": "DISCOUNT",
                "description": "20% off",
                "amount": "14.60"
            },
            {
                "kind": "LINE_BREAK"
            },
            {
                "kind": "TEXT",
                "description": "Thanks for your loyalty!"
            },
            {
                "kind": "DISCOUNT",
                "description": "Loyalty discount",
                "amount": "5.00"
            }
        ], 
        "tax": "9.89",
        "discountAmount": "59.60", 
        "amount": "136.40" 
    } 
} 

Sample API Response

{
    "data": {
        "requestItemDisplayFromInStoreReader": {
            "clientMutationId": null,
            "id": "aW5zdG9yZWNvbnRleHRfI2ZiNmY4MjgyMGEwODQ3NjBiNmZkNDdiNTg2MjU5NDU0I1ZFUklGT05FLTgwMy00MTUtMTY0I3VzLWVhc3QtMg",
            "reader": {
                "id": "aW5zdG9yZXJlYWRlcl8jaHo0YzYyeHp0OGZocjc2eSNWRVJJRk9ORS04MDMtNDE1LTE2NA",
                "name": "P400 Desk"
            },
            "status": "PENDING"
        }
    },
    "extensions": {
        "requestId": "0bf49170-db13-446a-83c8-b6b6d25c8bfa"
    }
}

Cancel Information Display

This mutation will allow you to cancel an information display and return to the screensaver.

GraphQL Mutation

mutation RequestCancelFromInStoreReader(
  $input: RequestCancelFromInStoreReaderInput!
) {
  requestCancelFromInStoreReader(input: $input) {
    id
    status
    reader {
      id
      name
      status
    }
  }
}

GraphQL Variables

{
  "input": {
    "inStoreContextId":  "{{last_braintree_instore_context}}"
  }
}

Sample API Response

{
  "data": {
      "requestCancelFromInStoreReader": {
          "id": "aW5zdG9yZWNvbnRleHRfIzQ3YTJiYzc3MWMwODRjYzM4NjFlMmI1ZmE3ZGQzNmFjI1ZFUklGT05FLTgwNC03NzUtMDg1I3VzLWVhc3QtMQ",
          "status": "CANCELLED",
          "reader": {
              "id": "aW5zdG9yZXJlYWRlcl8jZmFrZV9tZXJjaGFudCNWRVJJRk9ORS01NTUtNTU1LTU1NQ",
              "name": "POS Terminal #5",
              "status": "ONLINE"
          }
      }
  },
  "extensions": {
      "requestId": "1c58271e-7b5d-4911-9e57-b75db5e65310"
  }
}