Test error handling

By default, the sandbox mimics the live PayPal site as closely as possible and you must replicate specific error conditions in your test calls by creating the exact conditions needed to trigger the errors. The sandbox is a positive test environment by default. This is an efficient way to test your program because it follows an error-free path.

Test API error handling routines

Raise an error condition by setting a specific parameter to the error code value you want to trigger.

Select the parameter to use from the following table. Use the error codes in API error codes to trigger an error.

For example, use 10755 to trigger an "unsupported currency" error. The actual value that you pass and the field that you use to trigger the error depends on the error that you want to trigger:

• To trigger an error condition on an amount-related field, specify a error code value as a number with two digits to the right of the decimal point. For example, specify a value of 107.55 to trigger the 10755 error.
• To trigger errors on fields that are not amount related, specify the error code in whole. For example, use a value of 10539 to trigger a "payment declined" error.

The following table identifies the API operation, the NVP name or SOAP element of the field that triggers the error, and a description of how to set the value in the field:

Note: If the trigger value is not a valid error code for the API being tested, positive testing occurs for the request. In such a case, a different error might occur.

Test amount-related errors

Consider an example that tests an authorization error (#10610) for DoAuthorization. The error is related to the transaction amount, so we specify the error code in the AMT field:

curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=yourUID \ -d PWD=yourPSWD \ -d SIGNATURE=yourSig \ -d METHOD=DoAuthorization \ -d VERSION=100 \ -d TRANSACTIONENTITY=ORDER \ -d TRANSACTIONID=O-1N564174MM387483R \ -d AMT=106.10

If Negative testing is enabled for the sandbox Business account, you receive an error message similar to the following (wrapped for readability):

TIMESTAMP=2013%2d08%2d13T00%3a29%3a00Z
  &CORRELATIONID=78d43b44c9e0e
  &ACK=Failure
  &VERSION=100
  &BUILD=7161310
  &L_ERRORCODE0=10610
  &L_SHORTMESSAGE0=Amount%20limit%20exceeded%2e
  &L_LONGMESSAGE0=Amount%20specified%20exceeds%20allowable%20limit%2e
  &L_SEVERITYCODE0=Error

Test non-amount-related errors

The following example shows how to force an error code that's not related to a transaction amount. We'll use a DoVoid call to trigger error #10603, the buyer account is restricted. As noted in the table, we need to use the AUTHORIZATIONID field to trigger an error in DoVoid.

The DoVoid reverses (or releases) an order or an authorization that a merchant has made with a customer. Here's a call that generates an error in negative testing mode:

curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=yourUID \ -d PWD=yourPSWD \ -d SIGNATURE=yourSig \ -d METHOD=DoVoid \ -d VERSION=100 \ -d AUTHORIZATIONID=10603

The call triggered the #10603 error, as we see in the following response:

TIMESTAMP=2013%2d08%2d13T19%3a53%3a09Z&CORRELATIONID=cfcf54037bca8
  &ACK=Failure
  &VERSION=100
  &BUILD=7161310
  &L_ERRORCODE0=10603
  &L_SHORTMESSAGE0=The%20buyer%20is%20restricted%2e
  &L_LONGMESSAGE0=The%20buyer%20account%20is%20restricted%2e
  &L_SEVERITYCODE0=Error

Test errors that return multiple responses

Consider an example that triggers the RefundTransaction error #10009, an error that returns 14 different error sets. This is an amount type of error, so we set the trigger in the AMT input field:

curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=yourUID \ -d PWD=yourPSWD \ -d SIGNATURE=yourSig \ -d METHOD=RefundTransaction \ -d VERSION=100 \ -d TRANSACTIONID=6M473779DJ437830A \ -d REFUNDTYPE=Partial \ -d AMT=100.09

As you can see from the following response (truncated for clarity), the sandbox returns all the possible error code sets. A robust application gracefully handles all the possible variations.

TIMESTAMP=2013%2d08%2d13T20%3a16%3a56Z
  &CORRELATIONID=196d832d49033
  &ACK=Failure
  &VERSION=100
  &BUILD=7161310
  &L_ERRORCODE0=10009
  &L_ERRORCODE1=10009
  &L_ERRORCODE2=10009
  &L_ERRORCODE3=10009
  &L_ERRORCODE4=10009
  &L_ERRORCODE5=10009
  &L_ERRORCODE6=10009
  &L_ERRORCODE7=10009
  &L_ERRORCODE8=10009
  &L_ERRORCODE9=10009
  &L_ERRORCODE10=10009
  &L_ERRORCODE11=10009
  &L_ERRORCODE12=10009
  &L_ERRORCODE13=10009
  &L_ERRORCODE14=10009
  &L_SHORTMESSAGE0=Transaction%20refused
  &L_SHORTMESSAGE1=Transaction%20refused
  &L_SHORTMESSAGE2=Transaction%20refused
...
  &L_SHORTMESSAGE13=Transaction%20refused
  &L_SHORTMESSAGE14=Transaction%20refused
  &L_LONGMESSAGE0=You%20can%20not%20refund%20this%20type%20of%20transaction
  &L_LONGMESSAGE1=You%20are%20over%20the%20time%20limit%20to%20perform%20a%20refund%20on%20this%20transaction
...
  &L_LONGMESSAGE13=This%20transaction%20has%20already%20been%20fully%20refunded
  &L_LONGMESSAGE14=The%20partial%20refund%20amount%20must%20be%20less%20than%20or%20equal%20to%20the%20remaining%20amount
  &L_SEVERITYCODE0=Error
  &L_SEVERITYCODE1=Error
...
  &L_SEVERITYCODE13=Error
  &L_SEVERITYCODE14=Error
  &REFUNDSTATUS=None
  &PENDINGREASON=None

Test Virtual Terminal and DoDirectPayment error handling

You can use the negative testing setting to test Virtual Terminal or DoDirectPayment routines. The sandbox supports testing both AVS and CCS error types.

Test AVS errors

Generate an address verification error using the trigger value for the AVS error you want to test.

For Virtual Terminal, enter the trigger value into the Address Line 1 field of the Virtual Terminal display.

For DoDirectPayment calls, specify the code in the STREET field of the call (use Street1 for SOAP calls). For example, in all cases, use the following value to trigger the AVS code A: 123 AVS_A Street

Note: The AVS code value is case sensitive (all characters must be uppercase). For example, AVS_A is valid trigger whereas avs_a is not.

This table identifies valid AVS codes, corresponding triggers, and a description of each error condition:

Test an AVS code using DoDirectPayment

Consider an example that sets up testing for AVS code A along with an API error code #10755 in a DoDirectPayment call. Code A indicates "no zip code is specified" and results in an error if the "Partial Address Match" risk control is set, whether or not other errors occur:

curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=yourUID \ -d PWD=yourPSWD \ -d SIGNATURE=yourSig \ -d METHOD=DoDirectPayment \ -d VERSION=100 \ -d CREDITCARDTYPE=VISA \ -d ACCT=4683075410516684 \ -d EXPDATE=112007 \ -d CVV2=808 \ -d AMT=107.55 \ -d FIRSTNAME=Designer \ -d LASTNAME=Fotos \ -d IPADDRESS=255.55.167.002 \ -d STREET=1234%20AVS_A%20Street \ -d CITY=San%20Jose \ -d STATE=CA \ -d COUNTRY=United%20States \ -d ZIP=95110 \ -d COUNTRYCODE=US \ -d SHIPTONAME=Lenny%20P.%20Rico \ -d SHIPTOSTREET=1234%20Easy%20Street \ -d SHIPTOSTREET2=Apt%2022%20bis \ -d SHIPTOCITY=New%20Orleans \ -d SHIPTOSTATE=LA \ -d SHIPTOCOUNTRY=US \ -d SHIPTOZIP=70114 \ -d PAYMENTACTION=Authorization \ -d FIZBIN=foo

The request invokes the following response:

TIMESTAMP=2013%2d08%2d13T20%3a16%3a56Z
  &CORRELATIONID=a7cbf2d4d83dc
  &ACK=Failure
  &L_ERRORCODE0=10555
  &L_SHORTMESSAGE0=Filter%20Decline
  &L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e
  &L_SEVERITYCODE0=Error
  &L_ERRORCODE1=10755
  &L_SHORTMESSAGE1=Unsupported%20Currency%2e
  &L_LONGMESSAGE1=This%20transaction%20cannot%20be%20processed%20due%20to%20an%20unsupported%20currency%2e
  &L_SEVERITYCODE1=Error
  &VERSION=100
  &BUILD=7161310

Note: If you don't specify an AVS risk control value, PayPal returns AVS code X.

Test CVV errors

You can simulate credit card validation by triggering a CVV error from Virtual Terminal or by making a DoDirectPayment call.

Specify the CVV code you want to generate by specifying the trigger value value in the CVV2 field of the call. From Virtual Terminal, enter the trigger value into Card Security Code field when completing form.

The following table identifies valid CVV codes, corresponding triggers, and a description of each error condition:

Test a CVV Code Using DoDirectPayment

Consider an example that sets up testing for CCV code N in DoDirectPayment, which indicates a mismatch in the card validation code:

curl https://api-3t.sandbox.paypal.com/nvp \ -s \ --insecure \ -d USER=yourUID \ -d PWD=yourPSWD \ -d SIGNATURE=yourSig \ -d METHOD=DoDirectPayment \ -d VERSION=100 \ -d CREDITCARDTYPE=VISA \ -d ACCT=4683075410516684 \ -d EXPDATE=112007 \ -d CVV2=116 \ -d AMT=1.55 \ -d FIRSTNAME=Designer \ -d LASTNAME=Fotos \ -d IPADDRESS=255.55.167.002 \ -d STREET=1234%20AVS_A%20Street \ -d CITY=San%20Jose \ -d STATE=CA \ -d COUNTRY=United%20States \ -d ZIP=95110 \ -d COUNTRYCODE=US \ -d SHIPTONAME=Lenny%20P.%20Rico \ -d SHIPTOSTREET=1234%20Easy%20Street \ -d SHIPTOSTREET2=Apt%2022%20bis \ -d SHIPTOCITY=New%20Orleans \ -d SHIPTOSTATE=LA \ -d SHIPTOCOUNTRY=US \ -d SHIPTOZIP=70114 \ -d PAYMENTACTION=Authorization \ -d FIZBIN=foo

The request invokes the following response:

TIMESTAMP=2013%2d08%2d13T20%3a16%3a56Z
  CORRELATIONID=2499856319532
  &ACK=Failure
  &L_ERRORCODE0=15004
  &L_SHORTMESSAGE0=Gateway%20Decline
  &L_LONGMESSAGE0=This%20transaction%20cannot%20be%20processed%2e%20Please%20enter%20a%20valid%20Credit%20Card%20Verification%20Number%2e
  &L_SEVERITYCODE0=Error
  &VERSION=100
  &BUILD=7161310