Process a payment with Level 2 or 3 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://<<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 QorCommerce 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 | No |
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_cardset totrueand 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.