Making a sale

A sale is a customer transaction where the purchase amount is authorized and settled at the same time. While a tip amount can be added, it is permitted only before the transaction is authorized and settled.

If a sale is not voided within 25 minutes, the merchant funding process begins for this sale. At this point, the merchant can still refund the customer.

Typical businesses where sale transactions occur include:

  • Quick service restaurants, where customers select a tip amount before completing the transaction with a payment
  • Retail stores, where tips are not expected

When a customer is ready to pay for their order, use the /v1/payments endpoint to start the transaction on the Clover device.

Prerequisites

  • The POS is connected to the device using a network or cloud connection
  • The Clover device is in an idle state (that is, no payment is being taken)

Taking a simple payment

To start the payment flow on the Clover device, do the following:

  1. Construct a request with the minimum required data (the amount to be charged in cents and an externalPaymentId).
{
  "amount": 2000,
  "externalPaymentId": "{idString}"
}
  1. Send a POST request to the /v1/payments endpoint. Be sure to include the required headers for the request you are making.

The payment flow is started for the specified amount. After the payment is complete, a success message is returned.

The response includes two properties that combined indicate a sale transaction. The state is CLOSED, meaning the transaction was captured by the payment gateway, and the type is AUTH.

{
  "payment": {
    "amount": 2000,
    "cardTransaction": {
      "authCode": "729168",
      "cardType": "VISA",
      "cardholderName": "Card Holder",
      "entryType": "EMV_CONTACT",
      "extra": {
        "authorizingNetworkName": "VISA",
        "applicationIdentifier": "A0000000031010",
        "cvmResult": "PIN",
        "applicationLabel": "5649534120435245444954"
      },
      "last4": "0010",
      "referenceId": "108100502390",
      "state": "CLOSED",
      "transactionNo": "000290",
      "type": "AUTH"
    },
    "createdTime": 1616427189908,
    "employee": {
      "id": "DFLTEMPLOYEE"
    },
    "externalPaymentId": "32-470-941-0752",
    "id": "75MYGBEV8EM3Y",
    "offline": false,
    "order": {
      "id": "BZ0GN8ADGTPKJ"
    },
    "result": "SUCCESS",
    "taxAmount": 0
  }
}
  1. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Taking a payment with customer information

You can pass additional data in a payment request to simplify the payment flow. If you specify the customer's email address in the receipt_email field, the receipt is automatically sent and the receipt selection screen is skipped.

  1. Construct a request for the payment. In this example, the customer will be charged $35.
{
  "amount": 3500,
  "externalPaymentId": "{idString}",
  "receipt_email": "[email protected]"
}
  1. Send a POST request to the /v1/payments endpoint.

The payment flow is started for the specified amount. After the payment is complete, a success message is returned and the receipt is sent to the specified address.

{
  "payment": {
    "amount": 3500,
    "cardTransaction": {
      "authCode": "420265",
      "cardType": "VISA",
      "cardholderName": "Card Holder",
      "entryType": "EMV_CONTACT",
      "extra": {
        "authorizingNetworkName": "VISA",
        "applicationIdentifier": "A0000000031010",
        "cvmResult": "PIN",
        "applicationLabel": "5649534120435245444954"
      },
      "last4": "0010",
      "referenceId": "108100502400",
      "state": "CLOSED",
      "transactionNo": "000291",
      "type": "AUTH"
    },
    "createdTime": 1616429206552,
    "employee": {
      "id": "DFLTEMPLOYEE"
    },
    "externalPaymentId": "55-794-543-7545",
    "id": "R2KJ8FCD40MN0",
    "offline": false,
    "order": {
      "id": "EAK1WKS5E2NST"
    },
    "result": "SUCCESS",
    "taxAmount": 0
  }
}
  1. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Payment timeouts

After a payment request is received by the device, the customer has sixty seconds to present their card. If they don't, the transaction times out. During the next sixty seconds, the transaction can be resumed by tapping the green OK button. If the transaction is not resumed, the transaction is canceled. A failure message is sent. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

{
  "code": "processing_error",
  "message": "The payment request was canceled.",
  "requestId": "96696",
  "requestType": "PAY",
  "type": "api_error"
}

Canceling a sale in progress

On the payment screen, the customer (or employee) can cancel the sale by tapping exit. When the payment is canceled, a failure message is sent. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

{
  "code": "processing_error",
  "message": "The payment request was canceled.",
  "requestId": "96705",
  "requestType": "PAY",
  "type": "api_error"
}

To cancel a sale from the POS application, send an empty JSON body as a POST request to /v1/device/cancel.

Voiding a sale transaction

A sale can only be voided if no more than 25 minutes have passed. To void a sale, build a request listing the voidReason and send it as a POST request to /v1/payments/{paymentId}/void.

A successful void response includes the original payment data, the merchant-provided voidReason, and the voidStatus.

{
  "payment": {
   ...
  },
  "paymentId": "TNVWSFOR23CYT",
  "voidReason": "USER_CANCEL",
  "voidStatus": "SENT_TO_SERVER"
}

Did this page help you?