Negative testing for REST API

Important: Negative testing in the sandbox is in beta. It might have bugs or issues.

To ensure that you handle error scenarios correctly, negative testing lets you force flows through specific error conditions.

Test procedure

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

Note: Negative testing is available only in the sandbox. You cannot force or simulate error conditions in the live PayPal environment.

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:

  • Use the v1/payments/payment or v1/payments/payment/payment_id/execute API endpoint.
  • Add a key to the PayPal-Mock-Response request header in your API call.

Note: You can complete negative testing for only create payment and execute approved PayPal payment.

Test API error handling routines

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

Request header Type Example
PayPal-Mock-Response JSON PayPal-Mock-Response: {"mock_application_codes":"INSTRUMENT_DECLINED"}

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

Test with negative testing

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

cURL request

From the command line, run this command:

curl -v \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer Access-Token" \
  -H "PayPal-Mock-Response:{\"mock_application_codes\":\"INSTRUMENT_DECLINED\"}"


Header Value
Content-Type application/json
Authorization Bearer Access-Token
To get an access token, see get an access token.)
PayPal-Mock-Response {"mock_application_codes":"error name"}


The response is:

  "message": "The specified instrument was either declined by the processor or bank or it cannot be used for this payment.",
  "information_link": "",
  "details": "If the buyer's funding source has insufficient funds, restart the payment and prompt the buyer to choose another payment method that is available on your site."