Refund charges

You can integrate your app with the QuickBooks Payments API with the QuickBooks Online Accounting API so it can process payments and record the accounting in customers’ QuickBooks Online company files.

Sometimes, merchants using your app need to refund their customer’s purchase. Here’s how to use both APIs to process refunds and record the accounting in QuickBooks Online.

If you aren’t familiar with how refunds and voids work, take the time to review the various charge and refund statuses.

The examples in this guide assumes your app is fully set up to process and the payments you’re refunding are settled.

Refunds involve a few steps that follow a specific sequence:

• First, you need to send a refund request using the QuickBooks Payments API. This reverses the original credit card charge and sends the money back to the customer.
• Next, use the charges entity to create the refund.
• Finally, create a refund receipt to record the accounting so the merchant can reconcile their books.

Use these entities from the QuickBooks Online Accounting API and the QuickBooks Payments API.

QuickBooks Online Accounting entities

• refundReceipt
• customer

QuickBooks Online Payments entities

• charges

Create and send a refund request to the charges object.

The value for the id should be the ID of the charge you want to retrieve and refund. The id is generated when you first create the charge.

Operation: POST (from your server) https://api.intuit.com/quickbooks/v4/payments/charges/{id}/refunds

Content type: application/json

Sample request body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19

{
  "amount": 5.0,
  "description": "first refund",
  "id": "",
  "context": {
    "deviceInfo": {
      "macAddress": "",
      "ipAddress": "",
      "longitude": "",
      "phoneNumber": "",
      "latitude": "",
      "type": "",
      "id": ""
    },
    "tax": 0,
    "recurring": false
  },
  "created": ""
}

View sample response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
 "created": "2021-03-10T21:24:05Z",
 "status": "ISSUED",
 "amount": "5.00",
 "description": "first refund",
 "id": "XXXXXXXXXXX",
 "context": {
  "tax": "0.00",
  "reconBatchID": "420210310 1Q13249999999977036129AUTO04",
  "mobile": false,
  "paymentGroupingCode": "5",
  "txnAuthorizationStamp": "1615411445",
  "clientTransID": "amyxswe7",
  "deviceInfo": {
   "longitude": "",
   "latitude": "",
   "id": "",
   "type": "",
   "phoneNumber": "",
   "macAddress": "",
   "ipAddress": ""
  },
  "recurring": false
 },
 "type": "REFUND"
}

The charges request automatically starts the refund process. At this point, the refund is captured, but the accounting isn’t settled in the QuickBooks Online company’s books yet.

Review the response and capture the value of the id field. You’ll use this later on to issue the refund receipt via QuickBooks Online API.

If the refund charge request is successful and you get a success response (200) for the refund, you can use the refundReceipt entity to create a refund receipt via the QuickBooks Online Accounting API.

This handles the reconciliation and accounting for the refunded charge.

The refund receipt should include:

• At least one Line.SalesItemLineDetail sub-object.
• A reference to the customer object for the customer receiving the refund.
• Don’t create more than one refund receipt object with the same CreditCardPayment.CreditChargeResponse.CCTransId.

Here’s a sample request to create a refund receipt.

Operation: POST https://quickbooks.api.intuit.com/v3/company/<realmId>/refundreceipt

Content type: application/json

Sample request body

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

{
    "Line": [{
       "Id": "1",
       "LineNum": 1,
       "Description": "Sprinkler Pipes",
       "Amount": 80.0,
       "DetailType": "SalesItemLineDetail",
       "SalesItemLineDetail": {
          "ItemRef": {
             "value": "17",
             "name": "Sprinkler Pipes"
          },
          "UnitPrice": 4,
          "Qty": 20
       }
    }],
    "CustomerRef": {
          "value": "15",
          "name": "Pye's Cakes"
       },
    "CreditCardPayment": {
       "CreditChargeInfo": {
             "ProcessPayment": "true"
       },
       "CreditChargeResponse": {
             "CCTransId": "EKFOR97XK9UD"
       }
    },
    "TxnSource": "IntuitPayment",
    "DepositToAccountRef": {
         "value": "40",
         "name": "Checking"
 }
}

View Sample Response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63

{
    "RefundReceipt": {
       "domain": "QBO",
       "sparse": false,
       "Id": "930",
       "SyncToken": "0",
       "MetaData": {
          "CreateTime": "2014-04-25T09:40:43-07:00",
          "LastUpdatedTime": "2014-04-25T09:40:43-07:00"
       },
       "CustomField": [
          {
             "Name": "P.O. Number",
             "Type": "StringType"
          },
          {
             "Name": "Sales Rep",
             "Type": "StringType"
          }
       ],
       "DocNumber": "10033",
       "TxnDate": "2014-04-25",
       "DepartmentRef": {
          "value": "1",
          "name": "Garden Services"
       },
       "Line": [
          {
             "Id": "1",
             "LineNum": 1,
             "Amount": 420,
             "DetailType": "SalesItemLineDetail",
             "SalesItemLineDetail": {
                "ItemRef": {
                   "value": "33",
                   "name": "Concrete"
                },
                "TaxCodeRef": {
                   "value": "NON"
                }
             }
          },
          {
             "Amount": 420,
             "DetailType": "SubTotalLineDetail",
             "SubTotalLineDetail": {}
          }
       ],
       "TxnTaxDetail": {
          "TotalTax": 0
       },
       "TotalAmt": 420,
       "ApplyTaxAfterDiscount": false,
       "PrintStatus": "NeedToPrint",
       "Balance": 0,
       "PaymentRefNum": "To Print",
       "DepositToAccountRef": {
          "value": "40",
          "name": "Checking"
       }
    },
    "time": "2014-04-25T09:40:43.687-07:00"
}

If the refund receipt request is successful and you get a success response (200) the refund is complete.