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.
Last updated
Was this helpful?
This page is dedicated to the passing of L2/L3 data in your transaction requests sent to Braintree for in-person transactions.
Last updated
Was this helpful?
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 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"
}
}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"
}
}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 .