Purchase - Use Level 2 or 3 Transaction Data

📘
Note:
To simplify your development and have consistency across the various Purchase requests - all Purchase API calls can also be reached at the following endpoint with any combination of the required Purchase... parameters :
https://{user.test_api_url}/v3/payment/sale/

Processing Level 3 corporate and purchase cards for business-to-business (B2B) and business-to-government (B2G) purchases qualifies for lower interchange rates. This is achieved in part by providing the issuing bank more information on what is being purchased, who is involved in the transaction, how the sale is taking place, and when.

Parameters

The following parameters are available to process a manually input credit card sale.

parameter	description	required
mid	the Merchant ID (MID) assigned by QorCommerce or your merchant service provider (MSP)	Yes
topt	Type Of Payment Transaction - set a value to simply tag and/or route a transaction to a pre-defined provider.	No
reference_id	A reference id that will be echo'd back in the message response.	No
amount	the total amount to process that MUST equal the sum of all total_amount parameter values in the items object array (see below)	Yes
service_charge	the amount of the total sum of this transaction that is made up of the service_charge	No
creditcard	the credit card number -or- card token	Yes
month	the card expiration month	Yes
year	the card expiration year	Yes
cvv	the card verification value	Yes
cardfullname	the name printed or embossed on the front of the credit card	Yes if store_card value is `true`
baddress	the card billing street address	No
baddress2	the card billing street 2 address	No
bcity	the card billing city name	No
bstate	the card billing state code	No
bzip	the card billing zip code	Yes
bcountry	the card billing country code default: US	No
currency	The currency to process. Defaults to USD if no value provided	No
invoiceid	the merchant invoice id associated with the sale	No
orderid	unique merchant order tracking number	Yes
ipaddress	The IP address of the client or server sending the request	No
cfirstname	the customer first name	No
clastname	the customer last name	No
cemail	the customer email address	No
cphone	the customer phone number	No
cwebaddress	the customer website	No
total_tax	the total tax amount applied to the sale	Yes
purchase_order	the purchase order associated with this sale	No
shipping_amount	the total shipping amount applied to the sale	No
shipping_zip	if items shipped or delivered, the shipping zip code	No
shipping_country	if items shipped or delivered, the shipping country code	No
line_items	an array of item objects sold (see line_item object parameters below)	Yes must have at least one item object
risk_score	risk score associated to this transaction ( if you are using a risk prevention system)	No
store_card	if `true` will store card in the Vault and return a card token	No
metadata	a set of key-value pairs that you can attach to a payment. This can be useful for storing additional information about the payment in a structured format.	No

Each object in the line_items array provides the following parameters

parameter	description	required
name	the name of the item	Yes
description	a description of the item	No
unit_price	the price per unit for the item	Yes
units_sold	the number of item units sold	Yes
unit_measurement	the unit of measurement	No
total_amount	the total amount of the item sale which should equal unit_price units_sold any taxes, discounts and/or fees	Yes
ucc	the item Universal Commercial Code	No
upc	the item Universal Product Code	N

📘
Note:
The request amount field MUST be equal to the sum of total_amount values for all objects in the items array or the transaction will be not be processed.

JSON example with manually entered card data

The following JSON example provides test values to process a sale with keyed/manual card data. You can copy and paste these values in the Body Params section below to be used by the Try It feature

{
  "transaction_data": {
      "mid": "887728202",
      "amount": "86.41",
      "creditcard": "4484070000000000",
      "cvv": "123",
      "month": "12",
      "year": "22",
      "bzip": "23443",
      "cardfullname": "Endframe Systems",
      "currency": "USD",
      "invoiceid": "INV-123123",
      "orderid": "124531541",
      "ipaddress": "0.0.0.0",
      "baddress": "1338 Westport Dr",
      "baddress2": "Suite 300",
      "bcity": "Santa Clara",
      "bstate": "CA",
      "bcountry": "US",
      "cfirstname": "Dinesh",
      "clastname": "Chugtai",
      "cemail": "[email protected]",
      "cphone": "415.343.1231",
      "cwebaddress": "endframe-sys.com",
      "tax_amount": 12.45,
      "purchase_order": "PO-123123",
      "shipping_zip": "33149",
      "shipping_country": "US",
      "items": [
          {
              "name": "Green Plasma Glue",
              "description": "the green, sticky glue guaranteed to stick",
              "ucc": "UCC-21366412",
              "upc": "UPC-634ab112",
              "unit_price": 14.25,
              "units_sold": 2,
              "unit_measurement": "each",
              "total_amount": "33.14"
          },
          {
              "name": "Black Hoodie",
              "description": "100% cotton hoodies",
              "ucc": "UCC-635345432",
              "upc": "UPC-24nn4532098",
              "unit_price": 49.00,
              "units_sold": 1,
              "unit_measurement": "each",
              "total_amount": "53.27"
          }
      ],
    "risk_score": 0,
    "store_card": 0
  }
}

JSON example with card track data

The following JSON example provides test values to process a sale using track data. You can copy and paste these values in the Body Params section below to be used by the Try It feature

{
      "mid": "887728202",
      "amount": "86.41",
   "trackdata":"%B5544044490909090^SMITH/JOHN%20A^1904101084730001000000850000000?;5544044490909090=19041010847385000001?",
      "currency": "USD",
      "invoiceid": "INV-123123",
      "orderid": "124531541",
      "ipaddress": "0.0.0.0",
      "cfirstname": "Dinesh",
      "clastname": "Chugtai",
      "cemail": "[email protected]",
      "cphone": "415.343.1231",
      "cwebaddress": "endframe-sys.com",
      "tax_amount": 12.45,
      "purchase_order": "PO-123123",
      "shipping_zip": "33149",
      "shipping_country": "US",
      "items": [
          {
              "name": "Green Plasma Glue",
              "description": "the green, sticky glue guaranteed to stick",
              "ucc": "UCC-21366412",
              "upc": "UPC-634ab112",
              "unit_price": 14.25,
              "units_sold": 2,
              "unit_measurement": "each",
              "total_amount": "33.14"
          },
          {
              "name": "Black Hoodie",
              "description": "100% cotton hoodies",
              "ucc": "UCC-635345432",
              "upc": "UPC-24nn4532098",
              "unit_price": 49.00,
              "units_sold": 1,
              "unit_measurement": "each",
              "total_amount": "53.27"
          }
      ],
    "store_card": 0
}

JSON example with a card token

The following JSON example provides test values to process a sale using a token. You can copy and paste these values in the Body Params section below to be used by the Try It feature

{
      "mid": "887728202",
      "amount": "86.41",
      "creditcard":"000044$5x6hOpZ3",
      "currency": "USD",
      "invoiceid": "INV-123123",
      "orderid": "124531541",
      "ipaddress": "0.0.0.0",
      "cfirstname": "Dinesh",
      "clastname": "Chugtai",
      "cemail": "[email protected]",
      "cphone": "415.343.1231",
      "cwebaddress": "endframe-sys.com",
      "tax_amount": 12.45,
      "purchase_order": "PO-123123",
      "shipping_zip": "33149",
      "shipping_country": "US",
      "items": [
          {
              "name": "Green Plasma Glue",
              "description": "the green, sticky glue guaranteed to stick",
              "ucc": "UCC-21366412",
              "upc": "UPC-634ab112",
              "unit_price": 14.25,
              "units_sold": 2,
              "unit_measurement": "each",
              "total_amount": "33.14"
          },
          {
              "name": "Black Hoodie",
              "description": "100% cotton hoodies",
              "ucc": "UCC-635345432",
              "upc": "UPC-24nn4532098",
              "unit_price": 49.00,
              "units_sold": 1,
              "unit_measurement": "each",
              "total_amount": "53.27"
          }
      ]
}

Store Card Option

You can store the credit card information provided in the manual card input or card track data in the QorCommerce Secure Vault by setting the store_card parameter to true. The response will provide a token value representing the credit card that you can associate with your customer and/or a contract to use for a future payment in place of credit card data when needed.

BIN Check Option

When sale requests from this endpoint are received with Level 3 data, QorCommerce will pass to the host for processing. If the card does not qualify for Level 3 processing, the host will process the request at the interchange rate assigned to the card category.

To ensure only Level 3 qualified cards are processed with a request, you can do one of the following:

Use our #endpoint:zbktnQqG4YjNqgwKY and verify the card category prior to sending the Level 3 request.
Add the query parameter check_l3_card set to true and QorCommerce will perform a BIN Check to determine if the card qualifies as a Level 3 purchase or corporate card. If yes, it will process the request as normal. If the card does not qualify QorCommerce will not process the request and return an error code with a message indicating the card does not qualify for Level 3 Processing.

Response Codes

Link to details on related response codes.

Payment Response Codes