Using an SDK to integrate with the payments API

The QuickBooks Online SDKs do not support the Payments API; however, you can still integrate your app with the Payments API from your development environment.

For detailed information about the Payments API, see the Payments API. All of the tools, such as the sandbox and API Explorer, are available for creating and testing your app.

Note

Note

If you are integrating your app only with the Payments API, use the QuickBooks Online sandbox for the US development region, which includes a default merchant account, for development and testing.

.NET

To integrate the Payments API with your .NET app:

Create your app

Follow the guidelines described in Get started for setting up your account and creating your app. Be sure to select the Payments API when you create it.

Implement authentication

To implement OAuth 2.0, use the Intuit.Ipp.OAuth2PlatformClient library. For information on how to authenticate using OAuth 2.0, see Authentication and Authorization. The OAuth2-Dotnet-Payments sample app shows how to implement OAuth 2.0 for the Payments API.

Note

Note

Although all other endpoints require OAuth tokens for the company file you want to make payment against, the Tokens endpoint, which encapsulates a cardholder’s credit card or bank account information, does not require OAuth tokens.

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 com.intuit.api.payments scope to get the OAuth 2.0 token for the company that is authorized to make the payment, and add the appropriate header to make Payments API calls. Any HttpClient library can be used. The following is an example of how to execute a charge using OAuth 2.0. To see this example in context, see the Default.aspx.cs page of the OAuth2-Dotnet-payments sample app.

Note

Note

Use the Tokens endpoint to create a charge. This is the preferred option to send credit card information in order to ensure PCI compliance. Using the Card endpoint may require your application to be PCI-certified.

  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;
}

Java

To integrate the Payments API with your Java app:

Create your app

Follow the guidelines described in Get started for setting up your account and creating your app. Be sure to select the Payments API when you create it.

Implement authentication

To implement OAuth 2.0, see the OAuth 2.0 examples on how to implement OAuth 2.0 for the QuickBooks Online Accounting API. Make sure to use the com.intuit.quickbooks.payment scope to get the OAuth 2.0 token for the company that is authorized to make the payment.

Note

Note

Although all other endpoints require OAuth tokens for the company file you want to make payment against, the Tokens endpoint, which encapsulates a cardholder’s credit card or bank account information, does not require OAuth tokens.

Call the Payments API

To call the Payments API in a Java environment, use Intuit’s Java Payments SDK. The instructions below show you how to install the SDK and create a charge using token.

The SDK can be installed using one of the ways below-

Maven

Gradle

Install jars manually

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>
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")
Download the latest version of the jar from maven and add it to your project’s classpath.

1
payment-api.jar

Usage

Create the RequestContext object as shown below. Pass 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();

Create the Service object. The sample below shows how to create a TokenService, you can create other service objects - Echeck, Charge, Card, BankAccount in the same way.

1
TokenService tokenService = new TokenService(requestContext);

Prepare Token request create token 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 token

1
Token token = tokenService.createToken(tokenRequest);

Retrieve token value

1
token.getValue();

Create 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);

Logging important attributes

Makes sure to log intuit_tid and requestId for each of your request for easier debugging.

For logging intuit_tid, use the following method

1
token.getIntuit_tid();

For logging requestId, use the following method

1
token.getRequestId();

Note

Note

Use the Tokens endpoint to create a charge. This is the preferred option to send credit card information in order to ensure PCI compliance. Using the Card endpoint may require your application to be PCI-certified.

PHP

To integrate the Payments API with your PHP app:

Create your app

Follow the guidelines described in Get started for setting up your account and creating your app. Be sure to select the Payments API when you create it.

Implement authentication

To implement OAuth 2.0, see the OAuth 2.0 examples of how to implement OAuth 2.0 for the QuickBooks Online Accounting API. These may be useful for implementing the QuickBooks Payments API. For detailed information on how to authenticate using OAuth 2.0, see Authentication and Authorization.

Note

Note

Although all other endpoints require OAuth tokens for the company file you want to make payment against, the Tokens endpoint, which encapsulates a cardholder’s credit card or bank account information, does not require OAuth tokens.

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 com.intuit.api.payments scope to get the OAuth 2.0 token for the company that is authorized to make the payment, and add the appropriate header to make Payments API call. Any HttpClient library can be used. The following is an example of how to execute a charge using OAuth 2.0.

Note

Note

Use the Tokens endpoint to create a charge. This is the preferred option to send credit card information in order to ensure PCI compliance. Using the Card endpoint may require your application to be PCI-certified.

Recurring billing

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