Level 3 Data API

Level 3 Restrictions

  • Level 3 data can only be added to approved transactions pre-settlement.
  • Level 3 data can only be added to transactions that are Level 3 eligible.
    • This can be determined by performing a GET on /transactions/{transactionId} and referencing the level3Eligible field:
      {
        response: {
          processor: {
            level3Eligible: true
          }
        }
      }
  • Level 3 data is not supported on refunds.
  • level 3 data may only be added to a a transaction that does not already have level 3 data associated with it.
    • To modify existing Level 3 data, first perform a DELETE to /transactions/{transactionId}/level3. Once the Level 3 data has been removed, you may POST new data to /transactions/{transactionId}/level3.
To force the level3Eligible field to false on a transaction in our PayJunctionLabs.com testing environment, process a transaction with amountBase set to $1.03. You can then trigger the validation error returned when attempting to add level 3 data to an ineligible transaction with POST /transactions/{transactionId}/level3.

API

POST /transactions/{transactionId}/level3

Fields

Required Field Name Format Description Used By Notes
  amountDuty Decimal - ex. 10.00 The total amount associated with the import of the purchased items. Mastercard - Optional
Visa - Optional
 
  amountFreight Decimal - ex. 10.00 The total amount associated with the freight or shipping portion of the transaction total. Mastercard - Optional
Visa - Optional
 
  summaryCommodityCode A/N - 4 Characters International description code of the overall goods or services being supplied. Visa - Required If set, commodityCode should be set.
  destinationZip A/N - Max Length 10 The Postal/Zip code of the address where the purchased items will be delivered. Mastercard - Optional
Visa - Optional
Mastercard & Visa: Recommended for best rate.
  shipFromZip A/N - Max Length 10 The Postal/ZIP code of the address where the purchased items will be shipped from. Mastercard - Optional
Visa - Optional
Mastercard: Recommended for best rate.
* items[]
  • List of JSON Object (See: "Item Fields" and "Usage" sections below).
  • Minimum of 1 item is required.
  • Maximum of 99 items are allowed.
List containing the details for the items purchased.    

Item Fields

Required Field Name Format Description Used By Notes
  amountDiscount Decimal - ex. 10.00 The total discount amount applied against the line item total. Defaults to 0 if not set. Mastercard - Optional
Visa - Optional
 
  amountTax Decimal - ex. 10.00 The amount of any value added taxes which may be associated with the purchased item. Defaults to 0 if not set. Mastercard - Required
Visa - Required
 
* amountTotal Decimal - ex. 10.00 The total amount of the individual item, typically calculated as price muliplied by quantity. Mastercard - Required
Visa - Required
 
* amountUnitCost Decimal - ex. 10.0000
Note: These fields allows up to 4 decimal precision
The cost amount per unit of the purchased item. Visa - Required  
  commodityCode A/N - Max Length 12 The description code of the individual good or service being supplied. It is recommended to use a National or International list of standardized codes. Visa - Required If set, summaryCommodityCode should be set
* description A/N - Max Length 35 The description of the items being supplied. Mastercard - Required
Visa - Required
 
* discountIndicator DISCOUNTED or NOT_DISCOUNTED Indicates whether a discount was applied to the purchase price of the individual item. Mastercard - Required If DISCOUNTED, amountDiscount and discountRate should be set.
  discountRate Decimal - ex. 10.00 (which equates to 10.00%) Percent discount rate of the purchased item. Defaults to 0 if not set. Mastercard - Optional  
* grossNetIndicator GROSS or NET Indicates whether amountTotal included the tax amount.
  • GROSS: amountTotal includes tax i.e. the total price paid for the item
  • NET: amountTotal does not include tax i.e. the pre-tax price.
Mastercard - Required  
* productCode A/N - Max Length 12 The merchant-defined description code of the item being purchased. Mastercard - Required
Visa - Required
 
* quantity Decimal - ex. 10.0000
Note: This field allows up to 4 decimal precision.
The quantity of the item(s) being purchased. Mastercard - Required
Visa - Required
 
  taxRate Decimal - ex. 10.00 (which equates to 10.00%) Percent tax rate of the applicable item. Defaults to 0 if not set. Mastercard - Required
Visa - Optional
If set, amountTax should be set.
* unitOfMeasure A/N - Max Length 12 Code for units of measurement as used in international trade. Mastercard - Optional
Visa - Required
 

Usage

curl -X POST https://api.payjunction.com/transactions/{transactionId}/level3 \
-u "login:password" \
-H "Accept: application/json" \
-H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY" \
-d destinationZip=93101 \
-d items[]="{\"amountTotal\": 1.00, \"amountUnitCost\": 1.00, \"quantity\": 1.0000, \"description\": \"a description\", \"grossNetIndicator\": \"GROSS\", \"discountIndicator\": \"NOT_DISCOUNTED\", \"productCode\": \"productCode\", \"unitOfMeasure\": \"OZ\"}" \
-d items[]="{\"amountTotal\": 1.00, \"amountUnitCost\": 1.00, \"quantity\": 1.0000, \"description\": \"a description\", \"grossNetIndicator\": \"GROSS\", \"discountIndicator\": \"NOT_DISCOUNTED\", \"productCode\": \"productCode\", \"unitOfMeasure\": \"OZ\"}"

Error Handling

{
  "errors" : [ {
    "message" : "size must be between 0 and 10",
    "parameter" : "destinationZip",
    "type" : "invalid"
  }, {
    "message" : "This field is invalid.",
    "parameter" : "items[1].discountIndicator",
    "type" : "invalid"
  } ]
}

DELETE /transactions/{transactionId}/level3

On successful delete, returns HTTP Response 204 No Content.

Usage

curl -X DELETE https://api.payjunction.com/transactions/{transactionId}/level3 \
-u "login:password" \
-H "Accept: application/json" \
-H "X-PJ-Application-Key: YOUR_PRODUCTION_APP_KEY"

GET /transactions/{transactionId}/level3

Usage

curl -X GET https://api.payjunction.com/transactions/{transactionId}/level3 \ -u
"login:password" \ -H "Accept: application/json" \ -H "X-PJ-Application-Key:
YOUR_PRODUCTION_APP_KEY"

Example Response

{
  "amountDuty" : "1.11",
  "amountFreight" : "2.22",
  "destinationZip" : "93101",
  "shipFromZip" : "91737"
  "items" : [ {
    "amountDiscount" : "0.00",
    "amountTax" : "2.17",
    "amountTotal" : "9.87",
    "amountUnitCost" : "2.2200",
    "commodityCode" : "9504500000",
    "description" : "description",
    "discountIndicator" : "NOT_DISCOUNTED",
    "discountRate" : "0.00",
    "grossNetIndicator" : "NET",
    "productCode" : "812872019123",
    "quantity" : "1.0000",
    "taxRate" : "8.75",
    "taxType" : "941",
    "unitOfMeasure" : "EA"
    }, {
    "amountDiscount" : "0.00",
    "amountTax" : "2.17",
    "amountTotal" : "9.87",
    "amountUnitCost" : "2.2200",
    "commodityCode" : "9504500000",
    "description" : "description2",
    "discountIndicator" : "NOT_DISCOUNTED",
    "discountRate" : "0.00",
    "grossNetIndicator" : "NET",
    "productCode" : "812872019123",
    "quantity" : "1.0000",
    "taxRate" : "8.75",
    "taxType" : "941",
    "unitOfMeasure" : "EA"
  } ]
}