Take Cash Payments

A seller can receive cash payments from a buyer (see Take Payments) and applications can record these payments using CreatePayment. In a CreatePayment request, in addition to the amount of money to accept for the payment, you provide the cash payment details including:

source_id. Set this field to CASH.
cash_details (CashPaymentDetails). Use this field to specify the buyer-supplied amount.

The following example CreatePayment request specifies:

amount_money and tip_money. A total of $1.50 to collect.
cash_details specifies that the buyer supplied $2 cash.

Create payment

After receiving the request, Square records the payment and returns a Payment object in the response as shown:

{
   "payment":{
      "id":"Bg049luXa4AtNdLLxDStc1c6GKSZY",
      "created_at":"2021-01-21T22:31:47.030Z",
      "amount_money":{
         "amount":100,
         "currency":"USD"
      },
      "tip_money":{
         "amount":50,
         "currency":"USD"
      },
      "status":"COMPLETED",
      "source_type":"CASH",
      "location_id":"S8GWD5R9QB376",
      "order_id":"8xzuTVOviOd8H5ArDptC58RKtjIZY",
      "total_money":{
         "amount":150,
         "currency":"USD"
      },
      "capabilities":[
         "EDIT_TIP_AMOUNT",
         "EDIT_TIP_AMOUNT_UP",
         "EDIT_TIP_AMOUNT_DOWN"
      ],
      "cash_details":{
         "buyer_supplied_money":{
            "amount":200,
            "currency":"USD"
         },
         "change_back_money":{
            "amount":50,
            "currency":"USD"
         }
      }, 
      "receipt_number":"Bg04",
      "receipt_url":"https://squareupsandbox.com/receipt/preview/Bg049luXa4AtNdLLxDStc1c6GKSZY",
      "version_token":"1QWj4OvtiHELSaSaKCs6H29QOb6xkvOF0KWkHoiceE75o"
   }
}

Note that cash_details in the response includes change_back_money. The API computes this amount based on total_money and buyer_supplied_money.

Note

You can use a recorded cash payment to pay for an order. If you're using the PayOrder endpoint (Orders API), you must set autocomplete to false in the preceding CreatePayment request. This sets the resulting Payment status to APPROVED as required by the PayOrder endpoint. For more information about paying for orders, see Orders integration.

Docs

Take Cash Payments

Note