Card payments

Enhanced data

View as Markdown

To qualify for lower interchange rates in a business-to-business (B2B) or a business-to-government (B2G) card payment, merchants can add enhanced data to their payments.

Enhanced data is additional information about a transaction beyond the amount and card details. Mastercard, Visa, and American Express offer programs that give merchants lower interchange rates based on the amount of enhanced data the merchant provides.

ProgramCard brandEnhanced data
Level 2Mastercard and American ExpressTax amount and purchase order (PO) number. American Express also requires some line-item details.
Level 3MastercardDetails about each item, shipping information, duty amount, tax amount, and PO number.
Commercial Enhanced Data Program (CEDP)VisaDetails about each item, shipping information, duty amount, tax amount, and PO number.

Note: Card brands can update their requirements at any time. Even if you send all the required information, Payroc can’t guarantee that the transaction qualifies for a program.

Things to consider

  • Your processing terminal must support enhanced data.
  • Enhanced data applies only to commercial credit cards, for example, business cards and purchasing cards.
  • Enhanced data isn’t available for all merchant category codes (MCCs).
  • Merchants must apply to American Express before they can qualify for Level 2.
  • American Express supports up to 4 line-items for each transaction.
  • Mastercard and Visa support up to 50 line-items for each transaction.
  • TSYS and FDRC terminals support tax-exempt transactions.

Level 2

To qualify for Level 2, you need to add the following information to your payment request:

  • PO number
  • Tax amount
  • Subtotal

Note: American Express also requires some line-item details, for example, a description and a price for each unit.

The following table shows the API parameters you need to send in the Create Payment request to qualify for Level 2:

InformationAPI parameters
PO numbercustomer.referenceNumber
Taxorder.breakdown.taxes[].name
order.breakdown.taxes[].amount
order.breakdown.taxes[].taxRate
Subtotalorder.breakdown.subtotal
Line-item details (American Express only)order.breakdown.items[].productCode
order.breakdown.items[].description
order.breakdown.items[].unitOfMeasure
order.breakdown.items[].unitPrice
order.breakdown.items[].quantity

Example request

Mastercard

1{
2  "channel": "moto",
3  "processingTerminalId": "1234001",
4  "operator": "Jane",
5  "autoCapture": true,
6  "customer": {
7    "referenceNumber": "CustomerCode234567"
8  },
9  "order": {
10    "orderId": "OrderRef6543",
11    "amount": 4564,
12    "currency": "USD",
13    "breakdown": {
14      "subtotal": 4347,
15      "taxes": [
16        {
17          "type": "amount",
18          "name": "Sales Tax",
19          "amount": 217
20        }
21      ]
22    }
23  },
24  "paymentMethod": {
25    "type": "card",
26    "cardDetails": {
27      "entryMethod": "keyed",
28      "keyedData": {
29        "dataFormat": "plainText",
30        "cardNumber": "5001650000000000",
31        "expiryDate": "1230",
32        "cvv": "234"
33      },
34      "cardholderName": "Sarah Hazel Hopper"
35    }
36  }
37}

American Express

1{
2  "channel": "moto",
3  "processingTerminalId": "1234001",
4  "operator": "Jane",
5  "autoCapture": true,
6  "customer": {
7    "referenceNumber": "CustomerCode234567"
8  },
9  "order": {
10    "orderId": "OrderRef6543",
11    "amount": 2899,
12    "currency": "USD",
13    "breakdown": {
14      "subtotal": 2709,
15      "taxes": [
16        {
17          "type": "amount",
18          "name": "Sales Tax",
19          "amount": 190
20        }
21      ],
22      "items": [
23        {
24          "productCode": "PZA-001-LG",
25          "description": "Large Pepperoni Pizza",
26          "unitOfMeasure": "EA",
27          "unitPrice": 2709,
28          "quantity": 1
29        }
30      ]
31    }
32  },
33  "paymentMethod": {
34    "type": "card",
35    "cardDetails": {
36      "entryMethod": "keyed",
37      "keyedData": {
38        "dataFormat": "plainText",
39        "cardNumber": "378282246310005",
40        "expiryDate": "1230",
41        "cvv": "234"
42      },
43      "cardholderName": "Sarah Hazel Hopper"
44    }
45  }
46}

Level 3

To qualify for Level 3, you need to add all the information from Level 2 and the following information to your payment request:

  • Shipping information
  • Line-item details
  • Duty amount

The following table shows the API parameters you need to send in the Create Payment request to qualify for Level 3:

InformationAPI parameters
PO numbercustomer.referenceNumber
Taxorder.breakdown.taxes[].name
order.breakdown.taxes[].amount
order.breakdown.taxes[].taxRate
Subtotalorder.breakdown.subtotal
Shipping informationcustomer.shippingAddress.recipientName
customer.shippingAddress.address
order.breakdown.freightAmount
Line-item detailsorder.breakdown.items[].commodityCode
order.breakdown.items[].productCode
order.breakdown.items[].description
order.breakdown.items[].unitOfMeasure
order.breakdown.items[].unitPrice
order.breakdown.items[].quantity
order.breakdown.items[].discountRate
order.breakdown.items[].taxes[].name
order.breakdown.items[].taxes[].amount
order.breakdown.items[].taxes[].taxRate
Duty amountorder.breakdown.dutyAmount

Example request

1{
2  "channel": "moto",
3  "processingTerminalId": "1234001",
4  "operator": "Jane",
5  "autoCapture": true,
6  "customer": {
7    "referenceNumber": "CustomerCode234567",
8    "shippingAddress": {
9      "recipientName": "Sarah Hazel Hopper",
10      "address": {
11        "address1": "2 Example Ave.",
12        "city": "Chicago",
13        "state": "Illinois",
14        "country": "US",
15        "postalCode": "60056"
16      }
17    }
18  },
19  "order": {
20    "orderId": "OrderRef6543",
21    "amount": 4899,
22    "currency": "USD",
23    "breakdown": {
24      "subtotal": 2709,
25      "freightAmount": 1500,
26      "dutyAmount": 500,
27      "taxes": [
28        {
29          "type": "amount",
30          "name": "Sales Tax",
31          "amount": 190
32        }
33      ],
34      "items": [
35        {
36          "commodityCode": "5812-0111",
37          "productCode": "PZA-001-LG",
38          "description": "Large Pepperoni Pizza",
39          "unitOfMeasure": "EA",
40          "unitPrice": 2709,
41          "quantity": 1,
42          "discountRate": 5.0,
43          "taxes": [
44            {
45              "type": "amount",
46              "name": "Sales Tax",
47              "amount": 190
48            }
49          ]
50        }
51      ]
52    }
53  },
54  "paymentMethod": {
55    "type": "card",
56    "cardDetails": {
57      "entryMethod": "keyed",
58      "keyedData": {
59        "dataFormat": "plainText",
60        "cardNumber": "5001650000000000",
61        "expiryDate": "1230",
62        "cvv": "234"
63      },
64      "cardholderName": "Sarah Hazel Hopper"
65    }
66  }
67}

CEDP

Visa replaced its Level 2 and Level 3 programs with CEDP, which checks the quality of the enhanced data that you send.

To qualify for CEDP, you need to send the same information as Level 3. You also need to make sure that you don’t send dummy data or placeholder data. For more information, see Data quality best practices.

The following table shows the API parameters you need to send in the Create Payment request to qualify for CEDP:

InformationAPI parameters
PO numbercustomer.referenceNumber
Taxorder.breakdown.taxes[].name
order.breakdown.taxes[].amount
order.breakdown.taxes[].taxRate
Subtotalorder.breakdown.subtotal
Shipping informationcustomer.shippingAddress.recipientName
customer.shippingAddress.address
order.breakdown.freightAmount
Line-item detailsorder.breakdown.items[].commodityCode
order.breakdown.items[].productCode
order.breakdown.items[].description
order.breakdown.items[].unitOfMeasure
order.breakdown.items[].unitPrice
order.breakdown.items[].quantity
order.breakdown.items[].discountRate
order.breakdown.items[].taxes[].name
order.breakdown.items[].taxes[].amount
order.breakdown.items[].taxes[].taxRate
Duty amountorder.breakdown.dutyAmount

Example request

1{
2  "channel": "moto",
3  "processingTerminalId": "1234001",
4  "operator": "Jane",
5  "autoCapture": true,
6  "customer": {
7    "referenceNumber": "CustomerCode234567",
8    "shippingAddress": {
9      "recipientName": "Sarah Hazel Hopper",
10      "address": {
11        "address1": "2 Example Ave.",
12        "city": "Chicago",
13        "state": "Illinois",
14        "country": "US",
15        "postalCode": "60056"
16      }
17    }
18  },
19  "order": {
20    "orderId": "OrderRef6543",
21    "amount": 4899,
22    "currency": "USD",
23    "breakdown": {
24      "subtotal": 2709,
25      "freightAmount": 1500,
26      "dutyAmount": 500,
27      "taxes": [
28        {
29          "type": "amount",
30          "name": "Sales Tax",
31          "amount": 190
32        }
33      ],
34      "items": [
35        {
36          "commodityCode": "5812-0111",
37          "productCode": "PZA-001-LG",
38          "description": "Large Pepperoni Pizza",
39          "unitOfMeasure": "EA",
40          "unitPrice": 2709,
41          "quantity": 1,
42          "discountRate": 5.0,
43          "taxes": [
44            {
45              "type": "amount",
46              "name": "Sales Tax",
47              "amount": 190
48            }
49          ]
50        }
51      ]
52    }
53  },
54  "paymentMethod": {
55    "type": "card",
56    "cardDetails": {
57      "entryMethod": "keyed",
58      "keyedData": {
59        "dataFormat": "plainText",
60        "cardNumber": "4539858876047062",
61        "expiryDate": "1230",
62        "cvv": "234"
63      },
64      "cardholderName": "Sarah Hazel Hopper"
65    }
66  }
67}

Data quality best practices

To help merchants avoid common data quality issues, Visa provides the following guidelines:

FieldDoDon’t
order.breakdown.items[].descriptionUse specific product names, especially for subscriptions.Use generic names, blanks, repeated business names, or single characters.
order.breakdown.items[].productCodeUse actual stock keeping units (SKU) or meaningful descriptors.Submit tax codes, card products, or random data.
order.breakdown.items[].taxes[].amountProvide the correct tax amount, or if the transaction is tax-exempt, send a value of 0.Provide incorrect or uniform tax values that don’t match jurisdiction rules.
order.breakdown.taxes[].amountProvide the correct tax amount, or if the transaction is tax-exempt, send a value of 0.Provide incorrect or uniform tax values that don’t match jurisdiction rules.