Note

Note about deprecation of TLS1.0 and TLS1.1

As we mentioned in our previous blog posts, we’re no longer supporting TLS1.0 and TLS1.1 starting June 1st, 2022. We’ll only support TLS1.2 or higher going forward. Refer to our blog for more details:

Basic schema and data formats for the QuickBooks Payments API

The QuickBooks Payments API is based on the REST framework. Here’s a quick guide for relevant REST features, operations, formats, and attributes.

General REST API info
BaseURLs for the QuickBooks Payments API

See the our current baseURLs </app/developer/qbpayments/docs/get-started/create-a-request>_.

URI formats for operations
Operation URI
Create and update POST baseURL/quickbooks/v4/resourceName
Read (single-entity) GET baseURL/quickbooks/v4/resourceName
Read (multi-entity) GET baseURL/quickbooks/v4/resourceName
Delete DELETE baseURL/quickbooks/v4/resourceName
URI component definitions
Component Description
baseURL Initial path to the URI. The Base URL section contains the list of available paths.
resourceName The name of the API entity you’re performing the operation for (i.e a bankaccount, charge, card, etc)
entityID The ID identifying the specific instance of the API entity.
Common request header fields

These are common HTTP header fields for requests.

Field name Description Required
Authorization Authentication credentials for HTTP authentication. Required for all requests. This represents the user’s permission to share access to their company data with your app. Learn more how to implement OAuth 2.0 and create this value. Required
Content-Length Length of the message (without the headers) according to RFC 2616. Required for POST operations
Content-Type The MIME type of the request body. Use application/json for all API interactions. Required for POST operations
Host The domain name of the server for the request. This is set by the request library in use. See Base URLs for valid values.  

See an example POST request

 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
POST https://sandbox.api.intuit.com/quickbooks/v4/payments/charges
Host: sandbox.api.intuit.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer eyJlbmMiOiJBMT************nexPfzFFw
Request-Id: 1234

{
  "amount": "10.55",
  "card": {
    "expYear": "2020",
    "expMonth": "02",
    "address": {
      "region": "CA",
      "postalCode": "94086",
      "streetAddress": "1130 Kifer Rd",
      "country": "US",
      "city": "Sunnyvale"
    },
    "name": "emulate=0",
    "cvc": "123",
    "number": "4111111111111111"
  },
  "currency": "USD",
  "context": {
        "mobile": "false",
        "isEcommerce": "true"
  }
}
Common server response header fields

These are common HTTP header fields for responses from our servers.

Field name Description
Cache-Control Specifies directives that must be obeyed by all caching mechanisms along the request-response chain.
Connection Control options for the current connection and list of hop-by-hop response fields.
Content-Type Defines the MIME type of the response.
Date Gives the date and time for service responses. Defined by RFC 7131 date/time format.
Expires Gives the date/time when the response is considered stale.
Keep-Alive Indicates of the HTTPS channel can be kept “alive” (open) to improve performance on subsequent requests. This is managed by the underlying networking library of the language.
Server

Specifies the server handling the request.

Tip: If there’s ever an issue, our support staff can quickly determine whether there are issues with a specific server.
Strict-Transport-Security A HSTS Policy informing the HTTP client how long to cache the HTTPS only policy, and whether this policy applies to subdomains.
Transfer-Encoding Specifies the encoding used to safely transfer the API response data to the app making the API call for the given entity. Current methods: chunked, compress, deflate, gzip, identity.

See an example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
Cache-Control : private
Connection : keep-alive
Content-Type : application/json;charset=UTF-8
Date : Wed, 31 Jan 2018 18:57:03 GMT
Expires : Wed, 31 Dec 1969 16:00:00 PST
Keep-Alive : timeout=5
Server : nginx
Strict-Transport-Security : max-age=15552000
Transfer-Encoding : chunked

{
  "created": "2018-01-31T18:48:25Z",
  "status": "SETTLED",
  "amount": "10.55",
...

}
Common IDs and resources

Here are detailed definitions of `common IDs and data fields used throughout our API </app/developer/qbpayments/docs/learn/learn-basic-field-definitions`_.

Character encoding

US versions of QuickBooks Online support ISO-8859-1 (extended ASCII) character encoding.

Non-US versions of QuickBooks Online support UTF-8 character encoding.

Updating on read-only attributes

Any value supplied in a read-only attribute is transient and will be silently overwritten by QuickBooks data services, as appropriate to the attribute. No error is returned.

Learn more about updating read only attributes.

Timestamps and time zones

Timestamps returned in QuickBooks Payments API response payloads and webhooks notifications are in DateTime format. This conforms to the iCal date/time format, as defined in RFC 2445.

The basic format is <date>T<time><UTC offset>

date The UTC date in the format YYYY-MM-DD.
time The UTC time in the format HH:MM:SS.
UTC offset The UTC offset to apply for time zone correction in the format +/-HH:MM.

Here’s an example timestamp: 2015-07-24T10:33:39-07:00.

This represents 03:33:39 on 24 July 2015, in a time zone west of UTC by 07:00 hours.

Limits and throttles

Below are limits and throttles currently in place for accessing QuickBooks Payments data services.

Multi-threading limits

Updates and additions to name list entities must be performed serially.

Updates and additions performed in a mutli-threaded enviroment may experience timing issues and lead to unexpected results.


Throttle limits

For production servers

QuickBooks Payments API endpoints are throttled at 500 requests per minute per realm ID.

For sandboxes and testing environments

Requests are throttled at 100 requests per minute per individual app.