Make a sale

A sale is a transaction where a purchase amount is authorized and settled simultaneously. A tip amount can be added 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.

Examples of businesses where sale transactions occur are:

• Quick service restaurant, where customers select a tip amount before completing a transaction.
• Retail store, where tips are not expected.

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

Prerequisites

• POS is connected to the device using a network or cloud connection.
• Clover device is idle; that is, no payment is being taken.

Take a simple payment

To start the payment flow on a Clover device:

1. Construct a request with the minimum required data, that is, the amount to be charged in cents and an externalPaymentId.

{
  "amount": 2000,
  "externalPaymentId": "{idString}"
}

2. Send a POST request to the /v1/payments endpoint.
3. Required. Include the required headers for your request.

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

The response includes two properties that indicate a sale transaction: CLOSED state indicates 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
  }
}

3. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Take 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 payment. In this example, the customer is charged $35.

{
  "amount": 3500,
  "externalPaymentId": "{idString}",
  "receipt_email": "[email protected]"
}

2. 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 appears, 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
  }
}

3. To return to the welcome screen, send a POST request to the /v1/device/welcome endpoint.

Handle payment timeouts

After the device receives a payment request, the customer has 60 seconds to present their card. After 60 seconds, the transaction times out.

1. Do one of the following:

• During the next 60 seconds, tap the green OK button to resume the transaction.
• If the transaction is not resumed, the transaction is canceled. A failure message is sent.

2. 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"
}

Cancel a sale in progress

1. On the payment screen, the customer or employee can tap Exit to cancel the sale.
   When the payment is canceled, a failure message is sent.
2. 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.

Void 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"
}