Simulate negative responses with request headers

APICurrentLast updated: May 18th 2022, @ 4:02:27 pm

Request headers

Note: If you do not use the specific test values, the service returns the actual API responses.

You can use request headers to test the following Payments API and Orders API methods:

Set up your development environment

Before you can use request headers to simulate negative responses, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to use request headers to simulate negative responses.

Invoke negative testing

1.Enable negative testing.
2.Test API error handling routines.
3.Test with negative testing.

Enable negative testing

REST API apps use a request header to invoke negative testing in the sandbox. This header configures the sandbox into a negative testing state for transactions that include the merchant.

To enable negative testing:

  • Add a key to the PayPal-Mock-Response request header in your API call.

Test API error handling routines

To simulate an error, add a mock_application_codes value that equals the error code to test:

Request headerTypeExample
"mock_application_codes": "DUPLICATE_INVOICE_ID"

For the available error codes, see Payment API Error Messages and Orders API Error Messages.

Test with negative testing

With a valid access token, you can make REST API calls for negative testing.

Example request

curl -X POST \ \
  -H 'Authorization: Bearer <Access-Token>' \
  -H 'Content-Type: application/json' \
  -H 'PayPal-Mock-Response: {"mock_application_codes": "DUPLICATE_INVOICE_ID"}'


AuthorizationBearer <Access-Token>
See get an access token.
PayPal-Mock-Response{\"mock_application_codes\": \"<error_name>\"}

Example response

  "details": [
      "issue": "DUPLICATE_INVOICE_ID",
      "description": "Duplicate Invoice ID detected. To avoid a potential duplicate transaction your account setting requires that Invoice Id be unique for each transaction."
  "message": "The requested action could not be completed, was semantically incorrect, or failed business validation.",
  "debug_id": "70c28ae654da",
  "links": [
      "href": "",
      "rel": "information_link",
      "method": "GET"