Accepting purchase cards

Purchasing cards allows merchants to deliver additional data for a payment, such as tax amount, order number, purchase identifier, etc. Purchasing card support can be configured via the payment application. This allows merchants to provide txn details that are not inherently known to their Clover system.

Understanding purchasing cards

Purchasing cards provide two level types, including:

  • Level 1 card data is processed for most consumer transactions. It provides authorization and settlement information to cardholders.
  • Level 2 card data is processed for some business or corporate purchase cards that are used for B2B transactions. These cards can have lower processing expenses for merchants. Level 2 cards provide additional data for B2B transactions, such as order number, freight amount, source/destination postal codes, etc.

📘

NOTE

Level 2 card payment features are currently available only for VISA and MasterCard in the US. Updated information will be provided as Clover extends availability for more card brands and regions.

For Clover merchants that accept purchase cards, you can include the level2 object when creating charges or paying for orders. To check if a merchant is setup for purchase cards, send a GET request to the /v3/merchants/{mId}/ecomm_payment_configs endpoint. In the response, check that the purchase_card.supported value is true.

curl --request GET \
  --url 'https://sandbox.dev.clover.com/v3/merchants/ecomm_payment_configs' \
  --header 'accept: application/json'
{
  "purchase_card": {
    "supported": true,
  }
  ...
}

If a merchant is not configured for purchasing cards, the transaction is still processed, but any data passed in the level2 object is ignored and the following warning message is returned:
Purchase card Level2 Data disregarded, merchant account does not support purchase cards.

Setting level 2 data in a charge request

In the request body, set the required amount (in cents), source, and currency. When using a purchasing card, set the required fields in the level2 object. See the Charges API reference for a list of possible fields that you can set.

{
  "amount": 33400,
  "currency": "usd",
  "source": "clv_1TSTA399021D...",
  "level2": {
    "tax_amount": 2353,
    "tax_indicator": 1,
    "order_number": "21-200394",
    "discount_amount": 2200,
    "freight_amount": 37500,
    "duty_amount": 0,
    "destination_postal_code": "80919",
    "shipping_from_postal_code": "94145",
    "destination_country_code": 840,
    "product_description": "",
    "merchant_tax_id": ""
  }
}

📘

NOTE

Processing the level 2 data included with purchase cards depends on upstream systems being available when creating a payment. If a system is unavailable, the transaction is processed as a normal credit card payment and the following warning is returned:
Purchase card Level2 Data disregarded, purchase card support is currently unavailable.

Getting level 2 data for a charge

If a charge includes level 2 data, you can retrieve these details using the Get a single payment endpoint. To view the purchase-card-related information in the response's purchaseCardL2 object, add the purchaseCardL2 expansion .

curl --request GET \
  --url 'https://sandbox.dev.clover.com/v3/merchants/{mId}/payments/{paymentId}?expand=purchaseCardL2' \
  --header 'Accept: application/json'
{
  "id": "HBQ8V3PZH481E",
  "amount": 808
  "purchaseCardL2": {
    "taxIndicator": "NON_TAXABLE",
    "purchaseIdentifier": "19873208776",
    "discountAmount": 2200,
    "freightAmount": 30000,
    "dutyAmount": 333,
    "destinationPostalCode": "80919",
    "shipFromPostalCode": "80903",
    "destinationCountryCode": "840",
    "merchantTaxId": "****0153",
    "productDescription": "Bike",
    "paymentRef": {
      "id": "HBQ8V3PZH481E"
    }
  }
}

Did this page help you?