SDK alternatives for the QuickBooks Payments API

We don’t have complte SDKs for the QuickBooks Payments API. Our current QuickBooks Online SDKs don’t fully support the QuickBooks Payments API.

However, there are a few ways you can set up a basic implementation for the QuickBooks Payments API via .NET, Java, and PHP.

Note

Note: If you’re integrating your app with the QuickBooks Payments API only (and not the QuickBooks Online Accounting API), use a US-based QuickBooks Online sandbox environment during development. It includes a default merchant account for testing.
Step 1: Create an app

If you haven’t already, create a new app and select the payments scope so your app can connect to the Payments API.

Step 2: Implement authentication

Follow the steps for .NET, Java, or PHP:

.NET

Java

PHP

.NET

To implement OAuth 2.0 for .NET, use the Intuit.Ipp.OAuth2PlatformClient library. Then follow these steps to get a token for OAuth 2.0. You can also follow the OAuth2-Dotnet-Payments sample to see an example implementation.


Learn more about setting up authorization with OAuth 2.0.

Note

Note: While most QuickBooks Payments API entities require OAuth 2.0 tokens for the QuickBooks Online companies your app sends requests for, the token entity itself doesn’t require OAuth 2.0 tokens.
Step 3: Call the Payments API

To call the Payments API in a .NET environment, use the HTTP Request object to make HTTP calls to the Payments REST API endpoints.


Use the current payments scope to get an OAuth 2.0 token for the end-users QuickBooks Online companies connected to your app. You can use any http client library to add the appropriate header for requests to the Payments API.


The following is an example of how to create a charge transaction:

  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
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
public async System.Threading.Tasks.Task paymentsApiCall(string access_token, string refresh_token, string realmId)
{
   try
   {
      if (realmId != "")
      {
         output("Making Payments API call.");

         // Get card token
         string cardToken = getCardToken();

         // Charge card using card token
         JObject cardChargeResponse = executePaymentsCharge(cardToken, realmId,
            access_token, refresh_token);
         output("Payments call successful.");
         lblPaymentsCall.Visible = true;
         lblPaymentsCall.Text = "Payments Call successful";
      }
   }
   catch (Exception ex)
   {
      if (ex.Message == "UnAuthorized-401")
      {
         output("Invalid/Expired Access Token.");

         // If 401 token expiry, then perform token refresh
         await performRefreshToken(refresh_token);
         if ((dictionary.ContainsKey("accessToken")) && (dictionary.ContainsKey("accessToken"))
            && (dictionary.ContainsKey("realmId")))
         {
            await paymentsApiCall(dictionary["accessToken"], dictionary["refreshToken"],
               dictionary["realmId"]);
         }
      }
      else
      {
         output(ex.Message);
      }
   }
}

/// <summary>
/// Get card token
/// </summary>
/// <returns>string</returns>

public string getCardToken()
{
   string cardToken="";
   JObject jsonDecodedResponse;
   string cardTokenJson = "";
   // Payments sandbox URL used here. Change to Prod URL (https://api.intuit.com/)
   // if prod keys are used in the config.
   string paymentsBaseUrl = PaymentsBaseUrl;
   string cardTokenEndpoint = "quickbooks/v4/payments/tokens";
   string uri= paymentsBaseUrl+ cardTokenEndpoint;

   // Build the request
   string cardTokenRequestBody = "{\"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\"}}";

   // Send the request (Token API call does not require Authorization header.
   // Other Payments API calls do)
   HttpWebRequest cardTokenRequest = (HttpWebRequest)WebRequest.Create(uri);
   cardTokenRequest.Method = "POST";
   cardTokenRequest.ContentType = "application/json";
   cardTokenRequest.Headers.Add("Request-Id", Guid.NewGuid().ToString());//assign guid

   byte[] _byteVersion = Encoding.ASCII.GetBytes(cardTokenRequestBody);
   cardTokenRequest.ContentLength = _byteVersion.Length;
   Stream stream = cardTokenRequest.GetRequestStream();
   stream.Write(_byteVersion, 0, _byteVersion.Length);
   stream.Close();

   // Get the response
   HttpWebResponse cardTokenResponse = (HttpWebResponse)cardTokenRequest.GetResponse();
   using (Stream data = cardTokenResponse.GetResponseStream())
   {
      // Return XML response
      cardTokenJson= new StreamReader(data).ReadToEnd();
      jsonDecodedResponse = JObject.Parse(cardTokenJson);
      if (!string.IsNullOrEmpty(jsonDecodedResponse.TryGetString("value")))
      {
         cardToken = jsonDecodedResponse["value"].ToString();
      }
   }
   return cardToken;
}

/// <summary>
/// Execute Charge on the card
/// </summary>
/// <param name="cardToken"></param>
/// <param name="realmId"></param>
/// <param name="access_token"></param>
/// <param name="refresh_token"></param>
/// <returns>JObject</returns>

public JObject executePaymentsCharge(string cardToken,string realmId,string access_token,string refresh_token)
{
   string cardChargeJson = "";
   JObject jsonDecodedResponse;
   // Payments sandbox URL used here. Change to Prod URL (https://api.intuit.com/)
   // if prod keys are used in the config.
   string paymentsBaseUrl = PaymentsBaseUrl;
   string cardChargeEndpoint = "/quickbooks/v4/payments/charges";
   string uri = paymentsBaseUrl + cardChargeEndpoint;

   // Build the request
   string cardChargeRequestBody = "{\"amount\": \"10.55\",\"token\":\""+ cardToken+ "\",
      \"currency\": \"USD\"}";

   // Send the request
   HttpWebRequest cardChargeRequest = (HttpWebRequest)WebRequest.Create(uri);
   cardChargeRequest.Method = "POST";
   cardChargeRequest.Headers.Add(string.Format("Authorization: Bearer {0}", access_token));
   cardChargeRequest.ContentType = "application/json";
   cardChargeRequest.Accept = "application/json";
   // Assign unique guid everytime
   cardChargeRequest.Headers.Add("Request-Id", Guid.NewGuid().ToString());

   byte[] _byteVersion = Encoding.ASCII.GetBytes(cardChargeRequestBody);
   cardChargeRequest.ContentLength = _byteVersion.Length;
   Stream stream = cardChargeRequest.GetRequestStream();
   stream.Write(_byteVersion, 0, _byteVersion.Length);
   stream.Close();

   // Get the response
   HttpWebResponse cardChargeResponse = (HttpWebResponse)cardChargeRequest.GetResponse();
   using (Stream data = cardChargeResponse.GetResponseStream())
   {
      // Return the XML response
      cardChargeJson = new StreamReader(data).ReadToEnd();
      jsonDecodedResponse = JObject.Parse(cardChargeJson);
   }
   return jsonDecodedResponse;
}

You can also visit the Default.aspx.cs page of the OAuth2-Dotnet-payments sample app to see this example in context.

Note

Note: As a best practice, use the token entity to create a charge. This is the preferred way to send credit card information and ensure PCI compliance. Calling the card endpoint directly may require you to get your app PCI-certified.
Java

To implement OAuth 2.0 for Java, follow these OAuth 2.0 examples for the QuickBooks Online Accounting API.


Learn more about setting up authorization with OAuth 2.0.

Note

Note: While most QuickBooks Payments API entities require OAuth 2.0 tokens for the QuickBooks Online companies your app sends requests for, the token entity itself doesn’t require OAuth 2.0 tokens.
Step 3: Call the Payments API

To call the Payments API in a Java environment, use Intuit’s Java Payments SDK. Follow the instructions to install the SDK, or use one of the following examples:


Follow install examples

Maven

Add the following dependency to the pom.xml file. Make sure to use the latest version of the SDK found here.

1
2
3
4
5
<dependency>
   <groupId>com.intuit.quickbooks-online</groupId>
   <artifactId>payments-api</artifactId>
<version>5.0.0</version>
</dependency>

Gradle

Add the following dependency to the build.gradle file. Make sure to use the latest version of the SDK found here.

1
compile("com.intuit.quickbooks-online:payments-api:5.0.0")

Install jars manually

Download the latest version of the jar from maven and add it to your project’s classpath.

1
payment-api.jar

Use tokens to create charges and objects

Use the current payments scope to get an OAuth 2.0 token for end-users’ QuickBooks Online companies connected to your app.


Create the RequestContext object. Follow the example in the sample code. Then pass it in the accessToken and environment:

1
2
3
RequestContext requestContext = new RequestContext.Builder(accessToken, Environment.SANDBOX).build();
//The above code automatically sets a unique requestid as well. To provide your custom //requestid use the below code-
RequestContext requestContext = new RequestContext.Builder(accessToken, Environment.SANDBOX).requestId(requestId).build();

Next, create the service object.


Follow the sample code to create a tokenService. You can also use this example to create other objects such as an eEcheck, charge, card, or bankAccount:

1
TokenService tokenService = new TokenService(requestContext);

Now do a create token request for a credit card:

1
2
3
4
5
Address address = new Address.Builder().region("CA").postalCode("94086").streetAddress("1130 Kifer Rd").city("Sunnyvale").country("US").build();

Card card = new Card.Builder().expYear("2020").expMonth("02").address(address).name("emulate=0").cvc("123").number("4111111111111111").build();

Token tokenRequest = new Token.Builder().card(card).build();

Call the TokenService to create the token:

1
Token token = tokenService.createToken(tokenRequest);

Get the token value:

1
token.getValue();

Now you’re ready to create a charge:

1
2
3
4
Charge chargeRequest = new Charge.Builder()
                  .amount(new BigDecimal("5.55")).token(token.getValue())
                  .currency("USD").context(context).build();
Charge charge = chargeService.create(chargeRequest);

Log important attributes

Capture the log intuit_tid and requestId for each request to simplify debugging.


For intuit_tid, use the following method:

1
token.getIntuit_tid();

For requestId, use the following method:

1
token.getRequestId();

Note

Note: As a best practice, use the token entity to create a charge. This is the preferred way to send credit card information and ensure PCI compliance. Calling the card endpoint directly may require you to get your app PCI-certified.
PHP

To implement OAuth 2.0 for PHP, follow these OAuth 2.0 examples for the QuickBooks Online Accounting API.


Learn more about setting up authorization with OAuth 2.0.

Note

Note: While most QuickBooks Payments API entities require OAuth 2.0 tokens for the QuickBooks Online companies your app sends requests for, the token entity itself doesn’t require OAuth 2.0 tokens.
Step 3: Call the Payments API

To call the Payments API in a PHP environment, use the HTTP Request object to make HTTP calls to the Payments REST API endpoints.


Use the current payments scope to get an OAuth 2.0 token for the end-users QuickBooks Online companies connected to your app. You can use any http client library to add the appropriate header for requests to the Payments API.

Note

Note: As a best practice, use the token entity to create a charge. This is the preferred way to send credit card information and ensure PCI compliance. Calling the card endpoint directly may require you to get your app PCI-certified.
Set up recurring billing

The QuickBooks Payments API does not directly support recurring billing. For a recommended workaround, see Recurring Billing with the QuickBooks Payments API.