Level 3 Data - Restrictions
- Level 3 data can only be added to approved transactions, pre-settlement.
- Level 3 data is not supported on refunds.
- Level 3 data can only be added to 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.
- 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
} }
}
- This can be determined by performing a GET on /transactions/{transactionId} and referencing the level3Eligible field:
level3Eligible=true in the transaction response data indicates that Level 3 data can be added to the transaction, it is not a confirmation or guarantee of qualification for Level 3 interchange rates.
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.
Level 3 Data - 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 | Initial 4 digits of the commodityCode. | 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 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 multiplied 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 | |
| debitCreditIndicator | DEBIT or CREDIT | Indicates whether the item is a positive or negative amount. DEBIT - The item amount is a positive amount. CREDIT - The item amount is a negative amount. |
Mastercard - Optional Visa - Optional |
Defaults to DEBIT if not 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. |
| discountTreatment | TAX_POST_DISCOUNT or TAX_PRE_DISCOUNT | Indicates whether tax amount was calculated before or after the discount was applied to the item amount total. | Mastercard - Optional Visa - Optional |
Triggers validation error if discountTreatment is set and discountIndicator is not set to DISCOUNTED | |
| 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.
|
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 \
--data-urlencode items\[\]="{\"amountTotal\": 1.00, \"amountUnitCost\": 1.00, \"quantity\": 1.0000, \"description\": \"a description\", \"grossNetIndicator\": \"GROSS\", \"discountIndicator\": \"NOT_DISCOUNTED\", \"productCode\": \"productCode\", \"unitOfMeasure\": \"OZ\"}" \
--data-urlencode items\[\]="{\"amountTotal\": 1.00, \"amountUnitCost\": 1.00, \"quantity\": 1.0000, \"description\": \"a description\", \"grossNetIndicator\": \"GROSS\", \"discountIndicator\": \"NOT_DISCOUNTED\", \"productCode\": \"productCode\", \"unitOfMeasure\": \"OZ\"}"
Example Request in the "Labs Demo" account:
curl -i -X POST https://api.payjunctionlabs.com/transactions/31/level3 \
-u "pj-ql-01:pj-ql-01p" \
-H "Accept: application/json" \
-H "X-PJ-Application-Key: 70ef7234-c45d-472b-92b8-e8f494901a84" \
-d destinationZip=93101 \
--data-urlencode items\[\]="{\"amountTotal\": 1.00, \"amountUnitCost\": 1.00, \"quantity\": 1.0000, \"description\": \"a description\", \"grossNetIndicator\": \"GROSS\", \"discountIndicator\": \"NOT_DISCOUNTED\", \"productCode\": \"productCode\", \"unitOfMeasure\": \"OZ\"}" \
--data-urlencode 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"
} ]
}
NOTE: A successful request only returns a HTTP 200 response (no message body). If you need to see the saved date, please use the GET command.