Applies to: Payments API | Orders API
Learn how to record cash payments using the Payments API.
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 toCASH.cash_details(CashPaymentDetails). Use this field to specify the buyer-supplied amount.
The following example CreatePayment request specifies:
amount_moneyandtip_money. A total of $1.50 to collect.cash_detailsspecifies 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.