Platform Docs

Accepting payments and tips

After generating a card token, you can use the source token to create a charge, create and pay for orders, and accept tips. Clover provides several sandbox test cards that can be used when developing your app.

Paying for a charge

If there is no order associated with a payment, simply create a charge by sending a POST request to the /v1/charges endpoint. This is useful for scenarios such as recurring subscriptions.

When you create a charge, Clover auto-creates a sample order. In the following example, set the amount (in cents), source, and currency unit details. Set authorization: Bearer to your OAuth-generated access_token.

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/charges \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"amount":1800,
  "currency":"usd",
  "source":"{token}"}'

In response, if the payment is successful using the tokenized card, a unique id (charge ID) is generated. The payment status value states whether the payment was successful.

Using the Auth & Capture model

Consider a use case where a customer purchases a green t-shirt from a Clover merchant's online shop. You can authorize the customer payment and then capture it when the merchant confirms that the green t-shirt is in stock and is ready for shipping.

An authorized payment is a confirmation (from the card-issuing institution) of the cardholder's ability to pay.

To authorize a customer payment, set the capture value to false with a POST request to the /v1/charges endpoint. Set authorization: Bearer to your OAuth-generated access_token.

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/charges \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"capture":false,
  "amount":1800,
  "currency":"usd",
  "source":"{token}"}'

In response, a unique id (charge ID) is generated.

📘

NOTE

If an authorized payment is left un-captured for seven days, the authorization is automatically reversed.

When the charge is ready for capture, send a POST request to the /v1/charges/{chargeId}/capture endpoint.

Paying for an order

Step 01: Creating an order

To create an order using your tokenized card, create the order with a POST request to the /v1/orders endpoint.

In the following example, set the name, address, and currency unit details for the order. Set authorization: Bearer to your OAuth-generated access_token. See the API reference for more information about other values you can set.

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/orders \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"currency":"usd",
  "customer":"{customer_uuid}",
  "email":"[email protected]",
  "items":[{
    "amount":1800,
    "currency":"usd",
    "description":"Test item #1",
    "quantity":1,"type":"sku"
  }],
  "shipping":{
    "address":{
        "city":"Sunnyvale",
      "country":"US",
      "line1":"415 N Mathilda Ave",
      "postal_code":"94085",
      "state":"California"
    },
  "name":"John Doe"}}'

In response, a unique id (order ID) is generated for the created order. The order status value is set to created.

{
  "id": "GX6GRZZPV43468", // order ID for the created order
  "object": "order",
  "amount": 1800,
  "tip_amount":200,
  "amount_returned": 0,
  "currency": "usd",
  "created": 1579108533000,
  ...
  customer & order item info
  ...
  "shipping": {
    "name": "John Doe",
    "address": {
    "line1": "415 N Mathilda Ave",
    "city": "Sunnyvale",
    "state": "CA",
    "postal_code": "94085",
    "country": "US"
    }
  },
  "status": "created" // order status
}

📘

NOTE

If you have already built applications using /v3 Clover endpoints (such as Inventory (/v3/merchants/{mId}/items) or Orders (/v3/merchants/{mId}/orders)), it is recommended that you continue using those endpoints. The /v1/orders endpoint is meant for streamlined app creation and does not include all of the same features.

Step 02: Paying for the created order

To pay for a created order, send a POST request to the /v1/orders/{orderId}/pay endpoint.

In the following example, set the orderId and source values. Set authorization: Bearer to your OAuth-generated access_token. If you include an email address in the request body, a web receipt for the order is sent automatically.

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/orders/{orderId}/pay \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"source":"{token}","email":"[email protected]"}'

📘

NOTE

In case you are adding a customer while creating an order, you can set the source value to the customer UUID while using the /v1/orders/{orderId}/pay endpoint to pay for the created order.

In response, if the payment is successful using the tokenized card, a unique id (charge ID) is generated. In addition, the order status value is set to paid.

Adding tips to charges and orders

You can use the tip_amount (in cents) value to add a tip before paying for a charge (/v1/charges) or an order (/v1/orders/{orderId}/pay). In the following example, an optional tip_amount value is added while paying for a charge:

curl --request POST \
  --url https://scl-sandbox.dev.clover.com/v1/charges \
  --header 'accept: application/json' \
  --header 'authorization: Bearer {access_token}' \
  --header 'content-type: application/json' \
  --data '{"amount":1800,
  "tip_amount":200,
  "currency":"usd",
  "source":"{token}"}'

Similarly, you can add a tip with a POST request to the /v1/orders/{orderId}/pay endpoint.

📘

NOTE

Tipping is available only for card-present transactions. In addition, to help merchants avoid chargebacks, tips are not adjustable and can only be included in the initial request. For instance, you cannot add a tip after an order receipt is printed.

Order calculations with tips

Always submit the charge or order amount and tip separately. In the above example, for a subtotal of $18 and a tip of $2:

Subtotal

Tip

Correct

"amount": 1800

"tip_amount": 200

Incorrect

"amount": 2000

"tip_amount": 200

Setting the transaction type indicator

When your app submits a charge, pays for an order, or creates a customer with a card on file, the ecomind parameter can be set to one of two values to indicate who initiated the payment. If no value is set, the default is ecom.

  • ecom - a payment where the customer enters their card details for a single transaction
  • moto - a payment where the merchant enters the customer's card details received over the phone or by mail

ecom

In this example, the customer uses an iframe-based app to submit a charge request for an online ecom payment.

moto

Alternatively, the customer could make their purchase over the phone and provide their card details to the merchant. In that case, the indicator should be set as moto because the merchant is entering the card information on the customer's behalf.

Updated 8 days ago


Accepting payments and tips


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.