Submitting Level 2 and Level 3 Data with Transactions

In the response, look specifically for the payment.bin.method, payment.bin.type, and payment.bin.category values. These values will help you determine if the card brand network supports lower interchange rates or Level 2 or Level 3 data submissions before submitting the additional data with a payment transaction.

{
  "response": {
    "data": [
      {
        "payment": {
          "bin": {
            "bin": "123456",
            "method": 2,
            "type": "credit",
            "category": "business",
            "name": "Big Bank",
            "address": "123 Golden Ave",
            "city": "Denver",
            "state": "CO",
            "country": "USA",
            "zip": "12345",
            "locationType": "branch",
            "newBin": "123455",
            "website": "https://website.com/",
            "phone": "5555555555",
            "transferEnabled": 0,
            "numberLength": 0,
            "debitOverCreditEnabled": 0,
            "billPayEnabled": 0,
            "pinlessSupport": "none"
          }
        },
        "token": "01234ab56c7890d1e293b456cfd7f8be"
      }
    ],
    "details": {},
    "errors": []
  }
}

The following table describes the parameters in the payment.bin object:

To submit Level 2 transaction data using the Create Payments page:

1. Navigate to the Create Payment page under Payments

2. Enter all applicable data. Then, under Customer Details, select Submit this transaction as LEVEL 2 PROCESSING to reveal Level 2 fields.

3. Enter the TAX and ORDER NUMBER values.

   • Note: If the entity is tax-exempt, you may enter 0. See the steps below to enable tax-exempt status.

   • Note: If you are not a tax-exempt entity, you must adhere to Visa, Mastercard, and local government sales tax rates and regulations to receive lower Level 2 interchange rates.  

4. (Optional) Follow the steps below to also include Level 3 data.

5. Click Process Payment to complete the submission.

Enable Tax-Exempt Status using the Portal

Non-profit and Governmental entities that qualify for tax-exempt status can apply this setting to their platform entity. This provides the proper mapping for Level 2 data submission when tax amounts are set to 0%.

Important!

To display the Parameters tab and Auto Tax Exempt Enabled parameter for your Groups, contact your Partner Success Manager to enable visibility.

1. Access the Groups page under the Management section.

2. Select the desired group (or add a new Group if needed) and enter the Group Profile page.

3. Select the Parameters tab, then click ADD PARAMETERS.

4. Click the edit icon in the upper-right corner, then select Auto Tax Exempt Enabled and confirm.

5. Return to the Group Profile page, then click ADD MEMBERS to add the Merchant as a Member.

6. Click Save to complete the Merchant enrollment in the Tax Exempt Group.

Tax Exempt Exceptions:

A tax-exempt merchant can qualify for Level 3 rates for both MasterCard and Visa.

Important!

Visa does not allow tax-exempt Merchants to qualify for Level 2 interchange regardless of MCC code.

To submit Level 3 transaction data using the Create Payments page:

1. Complete steps 1–3 from the Level 2 submission section above.

2. Select Submit this transaction as LEVEL 3 PROCESSING (All fields must be completed) to reveal Level 3 fields.

3. Enter the SHIPPING AMOUNT, DUTY AMOUNT, and ORDER DISCOUNT value.

4. Under Order Items, enter the DESCRIPTION, COMMODITY CODE, PRODUCT CODE, ITEM PRICE, ITEM DISCOUNT, QUANTITY, UNIT OF MEASURE, and ITEM TOTAL for each item.

5. (Optional) Add additional Order Items as needed by clicking Add Item at the bottom of each new item form. Each additional item must have all the fields above for Level 3 Transaction Processing.

6. Click Process Payment to complete the submission.

To submit Level 2 transaction data using the /txns endpoint, send the following request:

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

{
   "merchant": "{yourMerchantID}",
   "token": "01234ab56c7890d1e293b456cfd7f8be",
   "origin": 2,
   "type": 2,
   "order": "INVOICE#1",
   "total": 7799,
   "tax": 100
}

Important!

Tax rates must be set according to status and regulation:

• If you are a tax-exempt entity, you may enter 0 in the tax field. See the steps below to enable tax-exempt status.

• If you are not a tax-exempt entity, you must adhere to Visa, Mastercard, and local government sales tax rates and regulations to receive lower Level 2 interchange rates.

Non-profit and Governmental entities that qualify for tax-exempt status can apply this setting to their platform entity. This option properly maps for Level 2 data submission when tax amounts are set to 0%.

Important!

• Tax-exempt status is available for Commercial Retail and Commercial Card-Not-Present transactions only.

• To enable the /parameters endpoint and autoTaxExemptEnabled parameter for your Groups, contact your Partner Success Manager.

To apply tax-exempt status to non-profit entity groups using the /parameters endpoint, send the following request:

POST /parameters HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

{
  "login": "{{yourLoginID}}",
  "org":" {{merchantsOrg/GroupID}}",
  "autoTaxExemptEnabled": "1",
  "inactive": "0",
  "frozen": "0"
}

Tax Exempt Exceptions:

A tax-exempt merchant can qualify for Level 3 rates for both MasterCard and Visa.

Important!

Visa does not allow tax-exempt Merchants to qualify for Level 2 interchange regardless of MCC code.

If you do not first contact your Partner Success Manager to enable access to the /parameters endpoint, you will receive the following error:

{
    "errors": [
        {
            "code": 23,
            "severity": 2,
            "msg": "Invalid request for this type of user authentication"
        }
    ]
}

Your successful response should look like the following:

{
    "id": "t1_par_1abc2d34ef5g6h7ij89kl01",
    "created": "2023-10-05T13:00:33.442Z",
    "modified": "2023-10-05T13:00:33.442Z",
    "creator": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "modifier": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "login": "t1_log_1abc2d34ef5g6h7ij89kl01",
    "org": "t1_org_1abc2d34ef5g6h7ij89kl01",
    "division": "t1_div_1abc2d34ef5g6h7ij89kl01",
    "partition": "t1__1abc2d34ef5g6h7ij89kl01",
    "autoTaxExemptEnabled": "1",
    "inactive": "0",
    "frozen": "0",
    "minTxnTotal": "null",
    "maxTxnTotal": "null",
    "maxTxnDailyTotal": "null",
    "maxTxnDailyNum": "null",
    "maxTxnMonthlyTotal": "null",
    "maxTxnMonthlyNum": "null",
    "maxSubscriptionFailures": "null",
    "minPayoutCreditTotal": "0001",
    "maxPayoutCreditTotal": "null",
    "minPayoutDebitTotal": "-0001",
    "maxPayoutDebitTotal": "null",
    "minAvailableFunds": "null",
    "minStatementDebitPayoutDelay": "5",
    "minFundsPayoutTotal": "500",
    "minPayoutDelay": "3",
    "minFirstPayoutDelay": "3",
    "payoutDelayIncludeOffDays": "0",
    "payoutIncludePending": "0",
    "amexEnabled": "0",
    "optBlueEnabled": "0",
    "discoverEnabled": "0",
    "discoverAcquiredEnabled": "0",
    "mc3dsEnabled": "0",
    "visa3dsEnabled": "0",
    "amex3dsEnabled": "0",
    "discover3dsEnabled": "0",
    "eCheckEnabled": "0",
    "fundingEnabled": "0",
    "debtRepaymentEnabled": "0",
    "verifyDisabled": "0",
    "verifyForBoardingNotRequired": "0",
    "verifyForPayoutNotRequired": "0",
    "refundReleasesReserve": "0",
    "vendorFeesEnabled": "0",
    "vendorFeesExternal": "0",
    "visaMisuseSettlement": "10",
    "visaMisuseTravelAutoSettlement": "20",
    "visaMisuseCardPresentReversal": "24",
    "visaMisuseCardNotPresentReversal": "168",
    "mcMisuseSettlement": "120",
    "minEcheckCaptureDelay": "0",
    "minDebitProcessingDelay": "5",
    "minBoardingOwnership": "0",
    "boardingExemptionsDisabled": "0",
    "mcMisuseCardPresentReversal": "24",
    "mcMisuseCardNotPresentReversal": "72",
    "mcMisuseTravelAutoReversal": "480",
    "boardingDisabled": "0",
    "autoReboardDays": "60",
    "surchargeEnabled": "0",
    "mcInstantPayoutsEnabled": "0",
    "visaInstantPayoutsEnabled": "0",
    "mcInstantPayoutMin": "0",
    "mcInstantPayoutMax": "7500000",
    "visaInstantPayoutMin": "0",
    "visaInstantPayoutMax": "5000000",
    "sameDayPayoutsEnabled": "0",
    "applePayEnabled": "0",
    "googlePayEnabled": "0",
    "sameDayPayoutsDailyMax": "null",
    "minSameDayPayoutCreditTotal": "null",
    "maxSameDayPayoutCreditTotal": "null",
    "minSameDayPayoutDebitTotal": "null",
    "maxSameDayPayoutDebitTotal": "null",
    "accountUpdaterEnabled": "0",
    "updateAllTokensEnabled": "0",
    "accountUpdaterFrequency": "30",
    "minDebitedAvailableFunds": "0",
    "getParametersEnabled": "0",
    "payoutCutoffTime": "null",
    "declineNotificationEmail": "0",
    "decisionMicroserviceEnabled": "0",
    "holdMessagesDisabled": "0",
    "txnDecisionMicroserviceEnabled": "0",
    "omniTokenEnabled": "0",
    "passTokenEnabled": "0",
    "debitGracePeriod": "null",
    "negativeBalanceLimit": "null",
    "negativeBalanceEmail": "0",
    "positiveBalanceEmail": "0"
}

Ineligible Merchant Types (MCCs) for Tax Exempt Level 2 Interchange Rates

To submit Level 3 transaction data using the /txns endpoint, send the following request:

POST /txns HTTP/1.1
Accept: application/json
Content-Type: application/json
Host: test-api.payrix.com
APIKEY: {apiKey}

{
   "merchant": "{yourMerchantID}",
   "token": "01234ab56c7890d1e293b456cfd7f8be",
   "origin": 2,
   "type": 2,
   "order": "INVOICE#1",
   "total": 7799,
   "tax": 100,
   "items": [
      {
         "item": "Line Item #1",
         "description": "Line Item Description"
         "quantity": 1,
         "price": 7799,
         "um": "EACH",
         "commodityCode": "1111999",
         "total": 5799,
         "discount": 2000,
         "productCode": "UPC12345"
      }
   ]
}

1. Under your <script> tag containing PayFields.fields add the following to add new Tax and Order fields to the PayFields

<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"}
    {type: "tax", element: "#tax"}
    {type: "order", element: "#order"}
  ];
</script>

2. Under a new <script> tag, add the API Key, Merchant ID, and Transaction Amount:

<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = {Transaction Amount};
  <!---- continued by Step 3 ----> 

3. Under the same <script> tag as Step 2, add the Order Field, Tax Field, and Billing Address:

<!---- preceeded by Step 2 ---->
  PayFields.config.order = {order number};
  PayFields.config.tax = {tax number};
  PayFields.config.billingAddress = {
    address: '123 Madison Street',
    city: 'New York',
    state: 'NY',
    zip: '12345',
    email: '',
    phone: '5555555555',
    address2: 'Suite 555',
    company: 'Essential Co',
    country: 'USA'
  };
  PayFields.config.invoiceResult = {Invoice Object}
</script>

4. Add each new applicable field to your HTML file using the following <div> format:

<div>     
  <label for="tax">Tax:</label>     
    <!-- Div for tax field iframe  -->     
    <div id="tax" class="form-row">     
    </div>   
</div>

Result: Example HTML File

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="text/javascript" src="https://test-api.payrix.com/payFieldsScript"></script>
  <title>PayFields Test</title>
</head>
<body>
<input type="button" id="submit" value="Pay"></input>
  <!-- Button needed for PayFrame -->
<script>
    PayFields.button = {element: "#submit", value: "Pay"};
</script>
<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"},
    {type: "tax", element: "#tax"},
    {type: "order", element: "#order"},
  ];
</script>
<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = 500;
  PayFields.config.order = {orderNumber};
  PayFields.config.tax = {taxNumber};
  PayFields.config.billingAddress = {
    address: '123 Madison Street',
    city: 'New York',
    state: 'NY',
    zip: '12345',
    email: '',
    phone: '5555555555',
    address2: 'Suite 555',
    company: 'Essential Co',
    country: 'USA'
  };
  PayFields.config.invoiceResult = {invoiceObject}
</script>
</body>
</html>

Submit Level 3 Data Using PayFields

1. Complete steps 1–3 above.

2. Under your <script> tag containing PayFields.fields add the following to include Discount, Shipping, Duty, and Item [details] Objects fields in your PayField:

<script>
  PayFields.fields = [
    {type: "discount", element: "#discount"},
    {type: "shipping", element: "#shipping"},
    {type: "duty", element: "#duty"},
    {type: "items", element: "#items"}    
  ];
</script>

3. Under your <script> tag containing PayFields.config add the following:

<script>
  PayFields.config.discount = {discount number};
  PayFields.config.additionalData.shipping = {shipping number};
  PayFields.config.additionalData.duty = {duty number};
  PayFields.config.items = {items Object}
</script>

4. Add each new applicable field to your HTML file using the following <div> format:

<div>     
  <label for="tax">Tax:</label>     
    <!-- Div for tax field iframe  -->     
    <div id="tax" class="form-row">     
    </div>   
</div>

Result: Example HTML File

<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8">
  <script type="text/javascript" src="https://test-api.payrix.com/payFieldsScript"></script>
  <title>PayFields Test</title>
</head>
<body>
<input type="button" id="submit" value="Pay"></input>
  <!-- Button needed for PayFrame -->
<script>
    PayFields.button = {element: "#submit", value: "Pay"};
</script>
<script>
  PayFields.fields = [
    {type: "number", element: "#number"},
    {type: "cvv", element: "#cvv"},
    {type: "name", element: "#name"},
    {type: "address", element: "#address"},
    {type: "expiration", element: "#expiration"},
    {type: "tax", element: "#tax"},
    {type: "order", element: "#order"},
    {type: "discount", element: "#discount"},
    {type: "shipping", element: "#shipping"},
    {type: "duty", element: "#duty"},
    {type: "items", element: "#items"}
  ];
</script>
<script>
  PayFields.config.apiKey = "ab123c4def5g6hijkl7890m12345no6p";
  PayFields.config.merchant = "t1_mer_123ab4c567defg8h90123i45";
  PayFields.config.amount = 500;
  PayFields.config.order = {orderNumber};
  PayFields.config.tax = {taxRatePercent};
  PayFields.config.discount = {discountNumber};
  PayFields.config.additionalData.shipping = {shippingNumber};
  PayFields.config.additionalData.duty = {duty number};
  PayFields.config.items = {items Object};
  PayFields.config.billingAddress = {
    address: '123 Madison Street',
    city: 'New York',
    state: 'NY',
    zip: '12345',
    email: '',
    phone: '5555555555',
    address2: 'Suite 555',
    company: 'Essential Co',
    country: 'USA'
  };
  PayFields.config.invoiceResult = {invoiceObject}
</script>
</body>
</html>