Practice processing payments with mock data

Before you publish your app and put it into production, it’s important to thoroughly test and make sure it can process payments and complete the sales cycle.

Use the mock credit card and eCheck data in this article to test in a sandbox company. This should verify that your app can properly accept, charge, and record payments in QuickBooks.

If you haven’t already, get a QuickBooks Online sandbox company and create a test app on the dev portal.

Requests sent to sandbox companies use an emulated version of QuickBooks Payments. Requests will behave like you sent them to our actual payment processing services. The mock data in this article only works in sandbox companies.

Since sandbox companies aren’t connected to QuickBooks Payments, you don’t need to worry about fees or compliance rules just yet. Feel free to make changes and adjust your code.

If you haven’t already, set up OAuth 2.0 for your test app. This is essential for requests to sandbox companies and production companies.

Access tokens are what let apps process requests on behalf of merchants via the QuickBooks Payments API.

If you haven’t already, learn how to create basic payments processing requests.

There’s no need to use a real credit card for testing. Use our mock credit card info instead.

Create and send charge requests to your sandbox company using a credit card as the payment method. Use the following test values in your request:

When you send the request, the sandbox company will emulate processing the payment and send the appropriate response.

The emulation won’t check AVS values, CVS values, account limits, or charge states. It will check credit card numbers against the test values and expiration dates against the current date.

If you’ve fully integrated your app with both the QuickBooks Online Accounting API and QuickBooks Payments API, the transaction and payment should appear in your sandbox company.

You can also use test card holder names to see if your app can handle different error states. We created these emulate=##### names to emulate specific errors.

Use these emulate=##### card holder names to generate error responses:

1
2
3
4
5
6
7
8

{
   "errors": [{
      "code": "PMT-6000",
      "type": "system_error",
      "message": "A temporary issue prevented this request from being processed.",
      "infoLink": "https://developer.intuit.com/app/developer/qbpayments/docs/develop/troubleshooting/error-codes"
   }]
}

1
2
3
4
5
6
7
8
9

{
   "errors": [{
      "code": "PMT-4000",
      "type": "invalid_request",
      "message": "card.number is invalid.",
      "detail": "card.number",
      "infoLink": "https://developer.intuit.com/app/developer/qbpayments/docs/develop/troubleshooting/error-codes"
   }]
}

 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

{
   "created": "2015-11-04T17:27:06Z",
   "status": "DECLINED",  <---EMULATED STATUS
   "amount": "10.55",
   "currency": "USD",
   "card": {
      "number": "xxxxxxxxxxxx1111",
      "name": "emulate=10401",  <---EMULATED NAME
      "address": {
         "city": "Sunnyvale",
         "region": "CA",
         "country": "USA",
         "postalCode": "94086",
         "streetAddress": "1130 Kifer Rd"
      },
      "cardType": "Visa",
      "expMonth": "02",
      "expYear": "2020"
   },
   "capture": true,
   "avsStreet": "Pass",
   "avsZip": "Pass",
   "cardSecurityCodeMatch": "NotAvailable",
   "id": "EIS8H1O39X76",
   "context": {
      "recurring": false,
      "isMobile": false
   },
   "authCode": "372060"
}

Here’s an example charge request using emulate=10301 for the card.name. This name generats an invalid card error:

Sample request body

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

{
    "amount": "10.55",
    "card": {
       "expYear": "2020",
       "expMonth": "02",
       "address": {
          "region": "CA",
          "postalCode": "94086",
          "streetAddress": "1130 Kifer Rd",
          "country": "US",
          "city": "Sunnyvale"
       },
       "name": "emulate=10301",
       "cvc": "123",
       "number": "4111111111111111"
    },
    "currency": "USD"
}

When you process charges in a sandbox company, it’s settled immediately. This means you can practice refunding, but not voids. Learn more about charge and refund states.

If you void a charge in a sandbox company, you’ll get error 10405.

Create and send charge requests to your sandbox company using eCheck as the payment method.

Use the following test values in your requests:

Test using different amounts. Each amount returns a specific charge state. Any other amount automatically returns a “PENDING” state.

When you send the request, the sandbox company will emulate processing the payment and send the appropriate response.

If you’ve fully integrated your app with both the QuickBooks Online Accounting API and QuickBooks Payments API, the transaction and payment should appear in your sandbox company.

If you’ve entered the $5.55 test amount in your sandbox company, you can also use specific amounts to practice refunds.

Each amount returns a specific charge state. Keep in mind, your sandbox company must already have the debited $5.55 eCheck amount for the test refund amounts to work correctly.

To get a “VOIDED” state, create a charge for an amount not listed in the table. Then issue a refund with the value of 0.

Follow the below steps to retrieve a payment receipt (PDF)

How to retrieve a sample payment receipt

In the sandbox environment, only sample payment receipt retrieval is supported. If the real client transaction ID is used to fetch payment receipt then an error will be returned.

Steps to retrieve the sample receipt (PDF) :

• To test the payment receipt API use our sample client transaction ID a.k.a. invoice number to return receipt PDF.
• Sample client transaction ID : test123abc

Client transaction ID should be alphanumeric. If client transaction ID is non alphanumeric then the API will return an invalid client transaction ID error.

Important

The client transaction ID can be retrieved from the create charge API response property clientTransID

Sample receipt PDF

This response can be generated using our test client transaction ID - test123abc

Sandbox URL - https://sandbox.api.intuit.com/quickbooks/v4/payments/receipt/test123abc

View Sample PDF

Sample Errors

• Response for client transaction ID a.k.a invoice number that does not belong to the company

  1 2 3 4 5 6 7 8 9 10 11 12

  { "RestResponse": { "Error": { "@RequestId": "edaddf17-0973-4b46-acd6-124b0d1eaef1", "ProcessedTime": "2023-08-06T19:51:09.552-07:00", "Problem": { "Message": "ERROR", "Desc": "invalid clientTxnId or companyId" } } } }

• Client transaction ID is not alphanumeric

  1 2 3 4 5 6 7 8 9 10 11 12

  { "RestResponse": { "Error": { "@RequestId": "edaddf17-0973-4b46-acd6-124b0d1eaef1", "ProcessedTime": "2023-08-06T19:51:09.552-07:00", "Problem": { "Message": "Invalid input", "Desc": "Invalid client transaction id" } } } }

Note : When retrieving a payment receipt, there may be some delay when the payment is received and the receipt is created. If the payment receipt is not created you will receive an invalid clientTxnId or companyId error. Try again after 20 minutes to retrieve the PDF.