Negative testing for NVP/SOAP API

Enable negative testing

  1. Navigate to the Profile > Settings page of your merchant's test Business account (see Managing your Sandbox accounts for details).
  2. On the Profile tab, set Negative Testing to On.

This sets the Sandbox into the negative testing state for transactions that include the merchant. Without this configuration, the Sandbox does not raise error conditions unless the error is raised through normal transaction processing.

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:

You can force two types of API errors: those related to the transaction amount, and those not related to the amount.

  • 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:

API fields that trigger error conditions
API Name NVP Field SOAP Element Description
BAUpdate
v2.4 and later
MPID MpID Specify the full error code to trigger the error. For example, 10755 triggers error code 10755.
BAUpdate
v3.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=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

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:

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.

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:

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.

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