On this page
No Headings
Last updated: May 21, 2026
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.
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:
107.55 to trigger the 10755 error.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:
API fields that trigger error conditions
| API Name | NVP Field | SOAP Element | Description |
|---|---|---|---|
BAUpdatev2.4 and later | MPID | MpID | Specify the full error code to trigger the error. For example, 10755 triggers error code 10755. |
BAUpdatev3.0 and later | REFERENCEID | ReferenceID | Specify the full error code to trigger the error. For example, 10755 triggers error code 10755. |
BillUser | AMT | Amount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 107.55 triggers error code 10755. |
DoAuthorization | AMT | Amount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 106.23 triggers error code 10623. |
DoCapture | AMT | Amount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 106.23 triggers error code 10623. |
DoDirectPayment | AMT | OrderTotal | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 107.55 triggers error code 10755. |
DoExpressCheckoutPayment | AMT | OrderTotal | Specify the full error code to trigger the error. For example, 105.39 triggers error code 10539. |
DoReauthorization | AMT | Amount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 106.23 triggers error code 10623. |
DoVoid | AUTHORIZATIONID | AuthorizationID | Specify the full error code to trigger the error. For example, 10623 triggers error code 10623. |
GetExpressCheckoutDetails | TOKEN | Token | Specify the full error code to trigger the error. For example, 10539 triggers error code 10539. |
GetTransactionDetails | TRANSACTIONID | TransactionID | Specify the full error code to trigger the error. For example, 10539 triggers error code 10539. |
MassPay | EMAILSUBJECT | EmailSubject | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 107.55 triggers error code 10755. |
RefundTransaction | AMT | Amount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 107.55 triggers error code 10755. |
SetExpressCheckout | MAXAMT | MaxAmount | Specify the error code to trigger as a numeric value with two digits to the right of the decimal point. For example, 107.55 triggers error code 10755. |
TransactionSearch | INVNUM | InvoiceID | Specify the full error code to trigger the error. For example, 10539 triggers error code 10539. |
UpdateAuthorization | TRANSACTIONID | TransactionID | Specify the full error code to trigger the error. For example, 11094 triggers error code 11094. |
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.
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= \ -d PWD= \ -d SIGNATURE= \ -d METHOD=DoAuthorization \ -d VERSION=100 \ -d TRANSACTIONENTITY=ORDER \ -d TRANSACTIONID=O-1N564174MM387483R \ -d AMT=106.10If 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=ErrorThe 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= \ -d PWD= \ -d SIGNATURE= \ -d METHOD=DoVoid \ -d VERSION=100 \ -d AUTHORIZATIONID=10603The 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=ErrorConsider 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= \ -d PWD= \ -d SIGNATURE= \ -d METHOD=RefundTransaction \ -d VERSION=100 \ -d TRANSACTIONID=6M473779DJ437830A \ -d REFUNDTYPE=Partial \ -d AMT=100.09As 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=NoneYou can use the negative testing setting to test Virtual Terminal or DoDirectPayment routines. The sandbox supports testing both AVS and CCS error types.
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:
AVS error codes
| AVC Code | Trigger Value | Description |
|---|---|---|
A | AVS_A | The address matches but no zip code is specified; results in an error if the "PartialAddress Match" risk control is set. |
B | AVS_B | The address matches but no zip code is specified; results in an error if the "PartialAddress Match" risk control is set. |
C | AVS_C | No address information for an international address; results in an error if the "No Address Match" risk control is set. |
D | AVS_D | Exact match (no error). The international address and postal code matches. |
E | AVS_E | Not allowed for MOTO (internet/phone) transactions. |
F | AVS_F | Exact match (no error). The UK address and postal code matches. |
G | AVS_G | Service globally unavailable; results in an error if the "Service Unavailable/Unsupported" risk control is set. |
I | AVS_I | Service unavailable internationally; results in an error if the "Service Unavailable/Unsupported" risk control is set. |
N | AVS_N | No address information; results in an error if the "No Address Match" risk control is set. |
P | AVS_P | The postal code matches but no address is specified; results in an error if the "Partial Address Match" risk control is set. |
R | AVS_R | Retry; results in an error if the "Service Unavailable/Unsupported" risk control is set. |
S | AVS_S | Service not supported; results in an error if the "Service Unavailable/Unsupported" risk control is set. |
U | AVS_U | Service unavailable; results in an error if the "Service Unavailable/Unsupported" risk control is set. |
W | AVS_W | The 9-digit zip code matches but no address is specified; results in an error if the "Partial Address Match" risk control is set. |
X | AVS_X | Exact match (no error). The complete address and 9-digit zip code matches |
Y | AVS_Y | Exact match (no error). The complete address and 5-digit zip code matches. |
Z | AVS_Z | The 5-digit zip code matches but no address is specified; results in an error if the "Partial Address Match" risk control is set. |
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= \ -d PWD= \ -d SIGNATURE= \ -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=fooThe 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=7161310Note: If you don't specify an AVS risk control value, PayPal returns AVS code X.
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:
AVS error codes
| AVC Code | Trigger Value | Description |
|---|---|---|
M | 115 | CVV2 matches (no error). |
N | 116 | CVV2 does not match. |
P | 120 | Transaction not processed. |
S | 123 | Service not supported. |
U | 125 | Service unavailable. |
X | 130 | No response. |
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= \ -d PWD= \ -d SIGNATURE= \ -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=fooThe 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