Getting paid is always one of the best parts of running a business, and QuickBooks makes it easy to keep track of those payments. In this tutorial, we will simulate the Receive Payment functionality via the API to help you invoice, charge a card(securely) and record that a customer has made a payment.
NOTE
- Both com.intuit.quickbooks.accounting and com.intuit.quickbooks.paymentaccounting need to be enabled
- We will use the sandbox base url: https://sandbox-quickbooks.api.intuit.com
- Realm Id and Company Id are the same thing
STEPS
Create an Invoice
Create a Token
Create a Card Token
Create a Charge
Create a Sales receipt
Troubleshooting
Resources
Step 1: Create an Invoice using the Accounting API
To make this request you must:
- Have at least one sales item( item for sale)
- If Type=Inventory you must include the Quantity (Qty) in order to create an invoice.
- This article explains more in detail.
- If Type=Inventory you must include the Quantity (Qty) in order to create an invoice.
- Know the CustomerRef (Customer ID)
- If you do not know the ID you can query a customer to find the id
- SELECT * FROM Customer WHERE givenname = ‘REPLACEWITHCUSTOMERFIRSTNAME’
- Make a note of the Customer.Id value
- If you do not know the ID you can query a customer to find the id
REQUEST
POST https://sandbox-quickbooks.api.intuit.com/v3/company/<realmId>/invoice?minorversion=75
"Line": [
{
"DetailType": "SalesItemLineDetail",
"Amount": 500.00,
"SalesItemLineDetail": {
"ItemRef": {
"name": "Sprinkler Pipes",
"value": "17"
},
"Qty": 20
}
}
],
"CustomerRef": {
"value": "<insert customer id>"
}
}
RESPONSE
{
"Invoice": {
"AllowIPNPayment": false,
"AllowOnlinePayment": false,
"AllowOnlineCreditCardPayment": true,
"AllowOnlineACHPayment": true,
"domain": "QBO",
"sparse": false,
"Id": "193",
"SyncToken": "0",
"MetaData": {
"CreateTime": "2025-10-20T14:34:58-07:00",
"LastModifiedByRef": {
"value": "9341455063444183"
},
"LastUpdatedTime": "2025-10-20T14:34:58-07:00"
},
"CustomField": [],
"DocNumber": "2148",
"TxnDate": "2024-10-20",
"CurrencyRef": {
"value": "USD",
"name": "United States Dollar"
},
"LinkedTxn": [],
"Line": [
{
"Id": "1",
"LineNum": 1,
"Amount": 500.00,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "17",
"name": "Sprinkler Pipes"
},
"Qty": 20,
"ItemAccountRef": {
"value": "79",
"name": "Sales of Product Income"
},
"TaxCodeRef": {
"value": "NON"
}
},
"CustomExtensions": []
},
{
"Amount": 500.00,
"DetailType": "SubTotalLineDetail",
"SubTotalLineDetail": {}
}
],
"TxnTaxDetail": {
"TotalTax": 0
},
"CustomerRef": {
"value": "58",
"name": "<CUSTOMER NAME>"
},
"BillAddr": {
"Id": "46"
},
"ShipAddr": {
"Id": "46"
},
"FreeFormAddress": true,
"ShipFromAddr": {
"Id": "137",
"Line1": "Expressway Auto 2628 Mistletoe Dr. North Pole, AK 9970",
"Line2": "North Pole, AK 99700"
},
"DueDate": "2024-11-19",
"TotalAmt": 500.00,
"ApplyTaxAfterDiscount": false,
"PrintStatus": "NeedToPrint",
"EmailStatus": "NotSet",
"Balance": 500.00
},
"time": "2024-10-20T14:34:57.712-07:00"
}Step 2: Create a Card Token using the Payments API
This step will allow you to create a token that will allow you to “mask” the customer’s card details for privacy reasons and is the preferred method to capture this information.
We provide mock credit card info for testing and processing payments purposes.
- If you are using Postman you can create the request-Id parameter byi:
- Passing request-id: {{$randomUUID}} to auto-generate a unique UUID
- Take a note of the response value – that is your token that you will use in the next step
REQUEST
POST https://sandbox.api.intuit.com/quickbooks/v4/payments/tokens
{
"card": {
"name": "emulate=0",
"number": "4111111111111111",
"expMonth": "02",
"address": {
"postalCode": "94086",
"country": "US",
"region": "CA",
"streetAddress": "1130 Kifer Rd",
"city": "Sunnyvale"
},
"expYear": "2029",
"cvc": "123"
}
}
- The “name” parameter reflects the customer name on the card.
- Make sure the expYear parameter is a future year
RESPONSE
{
"value": "<token value>"
}
Step 3: Create and Capture a Charge using the Payments API
Using the response value from Step 2, send a request with the:
- Amount – amount/total of the transaction
- Currency – the currency the charge was made in
- Capture – set to true; default is false
- Token – response value from Step 2
- Context – additional information included in the request
- Mobile – was this charge made from a mobile device [ keyed, swiped, dipped or tapped on the merchant’s POS device]?
- isEcommerce – was this transaction made over the internet?
NOTE: mobile and isEcommerce cannot be the same value
REQUEST
POST /quickbooks/v4/payments/charges
{
"amount": "500.00",
"currency": "USD",
"capture": "true",
"token":"<token value from previous step",
"context": {
"mobile": "true",
"isEcommerce": "false" }
}
RESPONSE
{
"id": "MT11111111111",
"created": "2025-07-04T18:20:10Z",
"status": "CAPTURED",
"amount": "500.00",
"currency": "USD",
"token": "10164ea35c491a8478215c1c6a6d54ffe1801",
"card": {
"number": "xxxxxxxxxxxx1111",
"expMonth": "02",
"expYear": "2029",
"cvc": "xxx",
"name": "emulate=10301",
"address": {
"streetAddress": "1130 Kifer Rd",
"city": "Sunnyvale",
"region": "CA",
"country": "US",
"postalCode": "94086"
},
"cardType": "Visa"
},
"context": {
"mobile": true,
"isEcommerce": true,
"recurring": false,
"deviceInfo": {},
"clientTransID": "<clientTransIDvalue>"
},
"capture": true,
"authCode": "tst940",
"avsStreet": "Pass",
"avsZip": "Pass",
"cardSecurityCodeMatch": "NotAvailable"
}
Take note of the clientTransID value as you will need it for Step 4.
Step 4: Link the Payment to the Invoice using the Accounting API
For this final step, you will need to link the payment to the Invoice using the SalesReceipt endpoint.
- Line – all details should match the invoice created in Step 1
- Customer Ref – matches the customer of the invoice from Step 1
- CreditCardPayment
- Process Payment : set to true
- CC TransId : matches the clientTransId value from Step 3: Create a Charge
- TxnSource – Intuit Payment ; this signifies originating source of the payment transaction
REQUEST
POST https://sandbox-quickbooks.api.intuit.com/v3/company/<realm Id>/salesreceipt
{
"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": "<insert customer id>",
"name": "Denise Test"
},
"CreditCardPayment": {
"CreditChargeInfo": {
"ProcessPayment": "true"
},
"CreditChargeResponse": {
"CCTransId": "<clientTransIDvalue from previous step>"
}
},
"TxnSource": "IntuitPayment"
}
RESPONSE
{
"SalesReceipt": {
"domain": "QBO",
"sparse": false,
"Id": "151",
"SyncToken": "0",
"MetaData": {
"CreateTime": "2025-09-04T12:03:03-07:00",
"LastUpdatedTime": "2025-09-04T12:03:03-07:00"
},
"CustomField": [],
"DocNumber": "1044",
"TxnDate": "2025-09-04",
"CurrencyRef": {
"value": "USD",
"name": "United States Dollar"
},
"Line": [
{
"Id": "1",
"LineNum": 1,
"Description": "Sprinkler Pipes",
"Amount": 500.00,
"DetailType": "SalesItemLineDetail",
"SalesItemLineDetail": {
"ItemRef": {
"value": "17",
"name": "Landscaping:Sprinklers:Sprinkler Pipes"
},
"Qty": 20,
"ItemAccountRef": {
"value": "79",
"name": "Sales of Product Income"
},
"TaxCodeRef": {
"value": "NON"
}
},
"CustomExtensions": []
},
{
"Amount": 500.00,
"DetailType": "SubTotalLineDetail",
"SubTotalLineDetail": {}
}
],
"TxnTaxDetail": {
"TotalTax": 0
},
"TxnSource": "IntuitPayment",
"CustomerRef": {
"value": "<Customer Id Value>",
"name": "Denise Test"
},
"BillAddr": {
"Id": "96"
},
"ShipAddr": {
"Id": "96"
},
"FreeFormAddress": true,
"ShipFromAddr": {
"Id": "103",
"Line1": "123 Sierra Way",
"Line2": "San Pablo, CA 87999"
},
"TotalAmt": 500.00,
"ApplyTaxAfterDiscount": false,
"PrintStatus": "NeedToPrint",
"EmailStatus": "NotSet",
"Balance": 0,
"CreditCardPayment": {
"CreditChargeInfo": {
"ProcessPayment": true
},
"CreditChargeResponse": {
"CCTransId": "<clientTransIDvalue from previous step",
"Status": "Completed",
"CardSecurityCodeMatch": "NotAvailable",
"AvsStreet": "Fail",
"AvsZip": "Fail"
}
},
"DepositToAccountRef": {
"value": "4",
"name": "Undeposited Funds"
}
},
"time": "2025-09-04T12:03:02.972-07:00"
}
TROUBLESHOOTING
- Invalid Reference Id : An item in this transaction is set up as a category instead of a product or service.
- Error: “token is invalid. <Token value> not associated with payment data.”
- Tokens are only valid for 15 mins. You may need to generate a new token and update the value to create a charge
RESOURCES