In-Person
Braintree SandboxContact SalesGet Help
  • Braintree In-Person
  • About
    • Solution Architecture
    • Technical Overview
    • Solution Coverage
  • Hardware
    • Verifone P400
    • Verifone M400
    • Verifone E285
    • Verifone V400m
  • Get Started
    • Integration Checklist
    • Request Dev Kit
    • Configure Sandbox
    • Account Structure
  • Integration Guides
    • API Authentication
    • Setup Reader
    • Initiate a Sale or Refund
      • Initiate a Card Present Authorization
      • Level 2 and Level 3 Data Processing
      • Passing Lodging Data
    • Vaulting and Customers
    • PayPal and Venmo QRC
    • Display Information
    • Custom Prompts
    • Card Data Collection
    • GraphQL Error Handling
    • Offline Transactions
    • Additional API Calls
    • Receipt Printing API
    • Reporting and Reconciliation
    • Testing Your Integration
    • Ready for Launch?
  • Partner Considerations
    • Overview
  • Support
    • Reader Management System (RMS) - Available in Beta Only
    • Managing Firmware Updates
    • Troubleshooting
    • Network Connection Test
    • Support/Contact Us
  • Reference
    • Firmware Version Release Notes
    • Verifone Device Reference
    • EMV Receipt Reference
    • General Payments Terminology
    • GraphQL Docs
    • PayPal Braintree Sub-processors
    • FAQ
Powered by GitBook
On this page
  • Feature Overview
  • Level 2 Data Processing
  • Level 3 Data Processing
  • Important Tips for passing L2/L3 data

Was this helpful?

  1. Integration Guides
  2. Initiate a Sale or Refund

Level 2 and Level 3 Data Processing

This page is dedicated to the passing of L2/L3 data in your transaction requests sent to Braintree for in-person transactions.

PreviousInitiate a Card Present AuthorizationNextPassing Lodging Data

Last updated 9 months ago

Was this helpful?

Feature Overview

The passing of L2/L3 transaction data can help lower interchange fee costs for eligible MCC codes and eligible card types. This is primarily relevant for merchants who provide products and services to other businesses in a B2B sales environment. More information about can also be found at the general Braintree developer documentation site including on your Braintree merchant account.

Merchants who pass L2/L3 data will typically pass both L2 and L3 data in the same request. The below examples show the data being passed separately for example purposes only.

Level 2 Data Processing

Level 2 data is primarily tax information, and purchase order number. We allow for these data elements to be passed via the GraphQL API using the following input fields: purchaseOrderNumber, tax (with additional ) as seen in the below example of a card present charge request:

mutation RequestChargeFromInStoreReader($input: RequestChargeFromInStoreReaderInput!) {
    requestChargeFromInStoreReader(input: $input) {
        clientMutationId
        id
        status
        reader {
            id
            name                
            status
        }
    }
}
{
	"input": {
		"clientMutationId": "your client mutation ID",
		"readerId": "your reader ID",
		"transaction": {
			"amount": "any amount",            
            "orderId": "your order ID",
            "merchantAccountId": "your merchant account ID",
            "purchaseOrderNumber": "your purchase order number",
            "tax": {
                "taxExempt": true or false,
                "taxAmount": "any amount"
              },
              "discountAmount": "any amount"
		}
	}
}
{
    "data": {
        "requestChargeFromInStoreReader": {
            "clientMutationId": "abcsdfdf",
            "id": "aW5zdG9yZWNvzRkZjNmOWFhYTliZDFlM2EwZDMyN2FkI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg",
            "status": "COMPLETE",
            "reader": {
                "id": "aW5zdG9yZXJlYWRlcl83OWo1OWhjbiNWRVJJRk9ORS04MDUtOTcxLTIxNw",
                "name": "your reader name",
                "status": "ONLINE"
            }
        }
    },
    "extensions": {
        "requestId": "153ed8-1b51-4196-adcc-d4add18f"
    }
}

Once the transaction is completed on the reader you will need to perform your POS polling against the contextId returned synchronously in the charge request. See below example of context ID polling when passing L2 data.

query ID($inStoreContextId: ID!) {
	node(id: $inStoreContextId) {
		... on InStoreContext {
			id
			status
			reader {
				id
				name
				status
			}
			transaction {
				id
				legacyId
				orderId
				status
                purchaseOrderNumber
                tax {
                    taxAmount
                    taxExempt
                }
				statusHistory {
					__typename
					... on PaymentStatusEvent {
						status
						timestamp
						terminal
						__typename
						... on AuthorizedEvent {
							processorResponse {
								authorizationId
								emvData
								message
								legacyCode
								retrievalReferenceNumber
							}
						}
						__typename
						... on GatewayRejectedEvent {
							gatewayRejectionReason
						}
						__typename
						... on FailedEvent {
							processorResponse {
								retrievalReferenceNumber
								emvData
								message
								legacyCode
							}
							networkResponse {
								message
								code
							}
						}
						__typename
						... on ProcessorDeclinedEvent {
							processorResponse {
								legacyCode
								message
								authorizationId
								additionalInformation
								retrievalReferenceNumber
								emvData
							}
							declineType
							networkResponse {
								code
								message
							}
						}
					}
				}
				merchantAddress {
					company
					streetAddress
					addressLine1
					extendedAddress
					addressLine2
					locality
					adminArea2
					region
					adminArea1
					postalCode
					countryCode
					phoneNumber
				}
				amount {
					value
					currencyIsoCode
				}
				merchantAccountId
				merchantName
				createdAt

				channel
				customFields {
					name
					value
				}
				paymentMethodSnapshot {
					__typename
                    ...on PayPalTransactionDetails{
                          authorizationId
                        captureId
                        paymentId
                         appUsedForScanning
                         payer {
                             payerId
                             email
                             }
                        payer{
                            firstName
                            cobrandedCardLabel
                            billingAgreementId
                                }
                                sellerProtectionStatus
                            }

            ... on VenmoAccountDetails {
            username
            venmoUserId
          }

					... on CreditCardDetails {
						origin {
							type
							details {
								__typename
								... on CardPresentOriginDetails {
									authorizationMode
									inputMode
									pinVerified
									terminalId
								}
								... on EmvCardOriginDetails {
									authorizationMode
									inputMode
									pinVerified
									terminalId
									applicationPreferredName
									applicationIdentifier
									terminalVerificationResult
									cardSequenceNumber
									applicationInterchangeProfile
									terminalTransactionDate
									terminalTransactionType
									cashbackAmount
									applicationUsageControl
									terminalCountryCode
									applicationCryptogram
									cryptogramInformationData
									cardholderVerificationMethodResults
									applicationTransactionCounter
									unpredictableNumber
									issuerActionCodeDefault
									issuerActionCodeDenial
									issuerActionCodeOnline
								}
							}
						}
						brandCode
						last4
						bin
						expirationMonth
						expirationYear
						cardholderName
                        uniqueNumberIdentifier
						binData {
							issuingBank
							countryOfIssuance
							prepaid
							healthcare
							debit
							commercial
						}
					}
				}
			}
		}
	}
}
{
    "inStoreContextId": "aW5zdG9yZWNvzRkZjNmOWFhYTliZDFlM2EwZDMyN2FkI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg"
}
{
    "data": {
        "node": {
            "id": "aW5zdG9yZWNvbnRleHjlhMzRkZjNRiZWFhYTliZDFlM2EwZDMyN2FkI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg",
            "status": "COMPLETE",
            "reader": {
                "id": "aW5zdG9yZXJlYW3c23OWo1OWhjbiNWRVJJRk9ORS04MDUtOTcxLTIxNw",
                "name": "your reader name",
                "status": "ONLINE"
            },
            "transaction": {
                "id": "dHJhbnNhY3RfYXZxY2d6a2o",
                "legacyId": "avqgzkj",
                "orderId": "your order ID",
                "status": "SUBMITTED_FOR_SETTLEMENT",
                "purchaseOrderNumber": "your PO Number",
                "tax": {
                    "taxAmount": "1.00",
                    "taxExempt": false
                },
                "statusHistory": [
                    {
                        "__typename": "SubmittedForSettlementEvent",
                        "status": "SUBMITTED_FOR_SETTLEMENT",
                        "timestamp": "2023-04-05T16:00:28.000000Z",
                        "terminal": false
                    },
                    {
                        "__typename": "AuthorizedEvent",
                        "status": "AUTHORIZED",
                        "timestamp": "2023-04-05T16:00:28.000000Z",
                        "terminal": false,
                        "processorResponse": {
                            "authorizationId": "KWYHXD",
                            "emvData": "9F240512345678908A023030",
                            "message": "Approved",
                            "legacyCode": "1000",
                            "retrievalReferenceNumber": "1234567"
                        }
                    }
                ],
                "merchantAddress": {
                    "company": null,
                    "streetAddress": null,
                    "addressLine1": null,
                    "extendedAddress": null,
                    "addressLine2": null,
                    "locality": "Braintree",
                    "adminArea2": "Braintree",
                    "region": "MA",
                    "adminArea1": "MA",
                    "postalCode": "02184",
                    "countryCode": null,
                    "phoneNumber": "5555555555"
                },
                "amount": {
                    "value": "970.00",
                    "currencyIsoCode": "USD"
                },
                "merchantAccountId": "your merchant account ID",
                "merchantName": "DESCRIPTORNAME",
                "createdAt": "2023-04-05T16:00:27.000000Z",
                "channel": null,
                "customFields": null,
                "paymentMethodSnapshot": {
                    "__typename": "CreditCardDetails",
                    "origin": {
                        "type": "IN_STORE_READER",
                        "details": {
                            "__typename": "EmvCardOriginDetails",
                            "authorizationMode": "ISSUER",
                            "inputMode": "CONTACTLESS",
                            "pinVerified": false,
                            "terminalId": "b316878e",
                            "applicationPreferredName": "Braintree Credit",
                            "applicationIdentifier": "A000000003101001",
                            "terminalVerificationResult": "0000000000",
                            "cardSequenceNumber": null,
                            "applicationInterchangeProfile": null,
                            "terminalTransactionDate": null,
                            "terminalTransactionType": null,
                            "cashbackAmount": null,
                            "applicationUsageControl": null,
                            "terminalCountryCode": null,
                            "applicationCryptogram": null,
                            "cryptogramInformationData": null,
                            "cardholderVerificationMethodResults": null,
                            "applicationTransactionCounter": null,
                            "unpredictableNumber": null,
                            "issuerActionCodeDefault": null,
                            "issuerActionCodeDenial": null,
                            "issuerActionCodeOnline": null
                        }
                    },
                    "brandCode": "VISA",
                    "last4": "8885",
                    "bin": "421212",
                    "expirationMonth": "12",
                    "expirationYear": "2025",
                    "cardholderName": "BRAINTREE TEST",
                    "uniqueNumberIdentifier": null,
                    "binData": {
                        "issuingBank": null,
                        "countryOfIssuance": null,
                        "prepaid": "UNKNOWN",
                        "healthcare": "UNKNOWN",
                        "debit": "UNKNOWN",
                        "commercial": "UNKNOWN"
                    }
                }
            }
        }
    },
    "extensions": {
        "requestId": "41343193-7ba6-4768-8a68-b46ec379"
    }
}

Level 3 Data Processing

mutation RequestChargeFromInStoreReader($input: RequestChargeFromInStoreReaderInput!) {
    requestChargeFromInStoreReader(input: $input) {
        clientMutationId
        id
        status
        reader {
            id
            name                
            status
        }
    }
}
{
	"input": {
		"clientMutationId": "your client mutation ID",
		"readerId": "your reader ID",
		"transaction": {
			"amount": "150.00",            
            "orderId": "your order ID",
            "merchantAccountId": "your merchant account ID",
            "discountAmount": "2.22",
            "lineItems": [{
                  "quantity": "1",
                  "unitAmount": "4",
                  "name": "The New Line Item GDRJ",
                  "description": "This is the description 1",
                  "kind": "DEBIT",
                  "productCode": "the-mojave1",
                  "totalAmount": "50.00",
                  "discountAmount": "0.01",
                  "unitOfMeasure": "pcs",
                  "commodityCode": "123",
                  "unitTaxAmount": "1.01",
                  "taxAmount": "1.02",
                  "url": "your URL",
                  "imageUrl": "your image URL",
                  "itemType": "example digital"
                },
                {
                  "quantity": "2",
                  "unitAmount": "6",
                  "name": "The New Line Item XYZ",
                  "description": "This is the description 2",
                  "kind": "DEBIT",
                  "productCode": "the-mojave2",
                  "totalAmount": "100.00",
                  "discountAmount": "0.02",
                  "unitOfMeasure": "pcs",
                  "commodityCode": "123",
                  "unitTaxAmount": "1.01",
                  "taxAmount": "2.01",
                  "url": "your URL",
                  "imageUrl": "your image URL",
                  "itemType": "example digital"
                }
              ],
              "shipping": {
                "shippingAmount": "3",
                "shipsFromPostalCode": "54321-1234",
                "shippingAddress": {
                    "company": "Braintree",
                    "streetAddress": "123 Townsend St.",
                    "addressLine1": "123 Townsend St.",
                    "extendedAddress": "8th Floor",
                    "addressLine2": "8th Floor",
                    "firstName": "Dale",
                    "lastName": "Cooper",
                    "locality": "San Francisco",
                    "adminArea2": "San Francisco",
                    "region": "CA",
                    "adminArea1": "CA",
                    "postalCode": "94107",
                    "countryCode": "US"
                }
              }
		}
	}
}
{
    "data": {
        "requestChargeFromInStoreReader": {
            "clientMutationId": "abc1dfsdf",
            "id": "aW5zdG9yZWNvbGZhMDIxMDIxNjQ3MzE5ZjU1MzA1OTFiZjcyMDNjI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg",
            "status": "COMPLETE",
            "reader": {
                "id": "aW5zdG9yZXJlYWRlcl8jY3B3OWo1OWhjbiNWRVJJRk9ORS04MDUtOTcxLTIxNw",
                "name": "your reader name",
                "status": "ONLINE"
            }
        }
    },
    "extensions": {
        "requestId": "6c9c2e1-2ffe-4351-925a-f8940f9f4"
    }
}

Once the transaction is completed on the reader you will need to perform your POS polling against the contextId returned synchronously in the charge request. See below example of context ID polling when passing L3 data.

query ID($inStoreContextId: ID!) {
	node(id: $inStoreContextId) {
		... on InStoreContext {
			id
			status
			reader {
				id
				name
				status
			}
			transaction {
				id
				legacyId
				orderId
				status
                purchaseOrderNumber
                tax {
                    taxAmount
                    taxExempt
                }
                discountAmount
                shipping {
                    shippingAmount
                    shipsFromPostalCode
                    shippingAddress {
                    company
                    streetAddress
                    addressLine1
                    extendedAddress
                    addressLine2
                    firstName
                    lastName
                    locality
                    adminArea2
                    region
                    adminArea1
                    postalCode
                    countryCode
                    }
                }
				statusHistory {
					__typename
					... on PaymentStatusEvent {
						status
						timestamp
						terminal
						__typename
						... on AuthorizedEvent {
							processorResponse {
								authorizationId
								emvData
								message
								legacyCode
								retrievalReferenceNumber
							}
						}
						__typename
						... on GatewayRejectedEvent {
							gatewayRejectionReason
						}
						__typename
						... on FailedEvent {
							processorResponse {
								retrievalReferenceNumber
								emvData
								message
								legacyCode
							}
							networkResponse {
								message
								code
							}
						}
						__typename
						... on ProcessorDeclinedEvent {
							processorResponse {
								legacyCode
								message
								authorizationId
								additionalInformation
								retrievalReferenceNumber
								emvData
							}
							declineType
							networkResponse {
								code
								message
							}
						}
					}
				}
				merchantAddress {
					company
					streetAddress
					addressLine1
					extendedAddress
					addressLine2
					locality
					adminArea2
					region
					adminArea1
					postalCode
					countryCode
					phoneNumber
				}
				amount {
					value
					currencyIsoCode
				}
				merchantAccountId
				merchantName
				createdAt

				channel
				customFields {
					name
					value
				}
				paymentMethodSnapshot {
					__typename
                    ...on PayPalTransactionDetails{
                          authorizationId
                        captureId
                        paymentId
                         appUsedForScanning
                         payer {
                             payerId
                             email
                             }
                        payer{
                            firstName
                            cobrandedCardLabel
                            billingAgreementId
                                }
                                sellerProtectionStatus
                            }

            ... on VenmoAccountDetails {
            username
            venmoUserId
          }

					... on CreditCardDetails {
						origin {
							type
							details {
								__typename
								... on CardPresentOriginDetails {
									authorizationMode
									inputMode
									pinVerified
									terminalId
								}
								... on EmvCardOriginDetails {
									authorizationMode
									inputMode
									pinVerified
									terminalId
									applicationPreferredName
									applicationIdentifier
									terminalVerificationResult
									cardSequenceNumber
									applicationInterchangeProfile
									terminalTransactionDate
									terminalTransactionType
									cashbackAmount
									applicationUsageControl
									terminalCountryCode
									applicationCryptogram
									cryptogramInformationData
									cardholderVerificationMethodResults
									applicationTransactionCounter
									unpredictableNumber
									issuerActionCodeDefault
									issuerActionCodeDenial
									issuerActionCodeOnline
								}
							}
						}
						brandCode
						last4
						bin
						expirationMonth
						expirationYear
						cardholderName
                        uniqueNumberIdentifier
						binData {
							issuingBank
							countryOfIssuance
							prepaid
							healthcare
							debit
							commercial
						}
					}
				}
			}
		}
	}
}
{
    "inStoreContextId": "aW5zdG9yZWNvbGZhMDIxMDIxNjQ3MzE5ZjU1MzA1OTFiZjcyMDNjI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg"
}
{
    "data": {
        "node": {
            "id": "aW5zdG9yZWNvbnRleHRfIzk2xMDIxNjQ3MU1MzA1OTFiZjcyMDNjI1ZFUklGT05FLTgwNS05NzEtMjE3I3VzLXdlc3QtMg",
            "status": "COMPLETE",
            "reader": {
                "id": "your reader ID",
                "name": "your reader name",
                "status": "ONLINE"
            },
            "transaction": {
                "id": "dHJhbnNhY3R5fZnRmc3NiM3A",
                "legacyId": "ftfs3p",
                "orderId": "your order ID",
                "status": "SUBMITTED_FOR_SETTLEMENT",
                "purchaseOrderNumber": null,
                "tax": {
                    "taxAmount": null,
                    "taxExempt": false
                },
                "discountAmount": "2.22",
                "shipping": {
                    "shippingAmount": "3.00",
                    "shipsFromPostalCode": "54321-1234",
                    "shippingAddress": {
                        "company": "Braintree",
                        "streetAddress": "123 Townsend St.",
                        "addressLine1": "123 Townsend St.",
                        "extendedAddress": "8th Floor",
                        "addressLine2": "8th Floor",
                        "firstName": "Dale",
                        "lastName": "Cooper",
                        "locality": "San Francisco",
                        "adminArea2": "San Francisco",
                        "region": "CA",
                        "adminArea1": "CA",
                        "postalCode": "94107",
                        "countryCode": "USA"
                    }
                },
                "statusHistory": [
                    {
                        "__typename": "SubmittedForSettlementEvent",
                        "status": "SUBMITTED_FOR_SETTLEMENT",
                        "timestamp": "2023-04-05T16:33:22.000000Z",
                        "terminal": false
                    },
                    {
                        "__typename": "AuthorizedEvent",
                        "status": "AUTHORIZED",
                        "timestamp": "2023-04-05T16:33:22.000000Z",
                        "terminal": false,
                        "processorResponse": {
                            "authorizationId": "LXGYD5",
                            "emvData": "9F240512345678908A023030",
                            "message": "Approved",
                            "legacyCode": "1000",
                            "retrievalReferenceNumber": "1234567"
                        }
                    }
                ],
                "merchantAddress": {
                    "company": null,
                    "streetAddress": null,
                    "addressLine1": null,
                    "extendedAddress": null,
                    "addressLine2": null,
                    "locality": "Braintree",
                    "adminArea2": "Braintree",
                    "region": "MA",
                    "adminArea1": "MA",
                    "postalCode": "02184",
                    "countryCode": null,
                    "phoneNumber": "5555555555"
                },
                "amount": {
                    "value": "150.00",
                    "currencyIsoCode": "USD"
                },
                "merchantAccountId": "your merchant account ID",
                "merchantName": "DESCRIPTORNAME",
                "createdAt": "2023-04-05T16:33:21.000000Z",
                "channel": null,
                "customFields": null,
                "paymentMethodSnapshot": {
                    "__typename": "CreditCardDetails",
                    "origin": {
                        "type": "IN_STORE_READER",
                        "details": {
                            "__typename": "EmvCardOriginDetails",
                            "authorizationMode": "ISSUER",
                            "inputMode": "CONTACTLESS",
                            "pinVerified": false,
                            "terminalId": "b316878e",
                            "applicationPreferredName": "Braintree Credit",
                            "applicationIdentifier": "A000000003101001",
                            "terminalVerificationResult": "0000000000",
                            "cardSequenceNumber": null,
                            "applicationInterchangeProfile": null,
                            "terminalTransactionDate": null,
                            "terminalTransactionType": null,
                            "cashbackAmount": null,
                            "applicationUsageControl": null,
                            "terminalCountryCode": null,
                            "applicationCryptogram": null,
                            "cryptogramInformationData": null,
                            "cardholderVerificationMethodResults": null,
                            "applicationTransactionCounter": null,
                            "unpredictableNumber": null,
                            "issuerActionCodeDefault": null,
                            "issuerActionCodeDenial": null,
                            "issuerActionCodeOnline": null
                        }
                    },
                    "brandCode": "VISA",
                    "last4": "8885",
                    "bin": "421212",
                    "expirationMonth": "12",
                    "expirationYear": "2025",
                    "cardholderName": "BRAINTREE TEST",
                    "uniqueNumberIdentifier": null,
                    "binData": {
                        "issuingBank": null,
                        "countryOfIssuance": null,
                        "prepaid": "UNKNOWN",
                        "healthcare": "UNKNOWN",
                        "debit": "UNKNOWN",
                        "commercial": "UNKNOWN"
                    }
                }
            }
        }
    },
    "extensions": {
        "requestId": "45db111-a536-4c8f-acc4-7ddaeba57f"
    }
}

Important Tips for passing L2/L3 data

  • When data is passed in the incorrect format, the reader will initially accept the API request and prompt for card insert; however, an error will be thrown once the card is tapped, and the transaction will not be processed. The final context status would be "FAILED".

Level 3 data is primarily transaction line item information as well as discount and shipping information which can be passed to Braintree using the following input fields: shipping (with additional ), discountAmount, and lineItems (with additional ) as seen in the below example of a card present charge request:

The passing of L2/L3 data is NOT supported for , and if these API fields are passed for an offline transaction, it will result in an API error.

We do not support the passing of L2/L3 data when using the API mutation; however, you may pass this data when you send the request.

Make sure you are passing the L2/L3 data in the proper format according to the .

L2/L3 data processing
instructions for configuring your tax ID
TransactionTaxInput
TransactionShippingInput
TransactionLineItemInput
offline transactions
GraphQL API documentation
Request Authorize
separate capture