Testing Error Conditions

In default operation, the Sandbox mimics the live PayPal site as closely as possible, which means that an error can be replicated only by creating the exact conditions and sequence of events to raise an error. This positive test environment is well-suited for testing logic that follows the typical error-free path; however, it can be difficult to raise error conditions and test logic to handle errors.

The Sandbox can be set to allow negative testing, which enables you to simulate an error. You can test against the following kinds of errors:

l	errors that result from calling a PayPal API

l	address verification and credit card validation errors that occur when using Virtual Terminal or calling DoDirectPayment.

IMPORTANT:

Negative testing is only available for Version 2.4 and later of PayPal APIs.

You raise an error condition by setting a value in a field passed to an API or setting a value in a field submitted to Virtual Terminal. The value triggers a specific error condition. Negative testing is available only in the Sandbox; you cannot force or simulate an error on the live site.

You must create a Business test account and enable negative testing; otherwise, setting a value in the API or transaction will not raise an error unless the error would be raised in the default positive test environment. To enable negative testing, set Test Mode to Enabled. The following screen shows two Business accounts. The first test account enables negative testing; the second account disables negative testing.

To test Virtual Terminal, you must set risk controls for address verification and credit card security, respectively, to Decline or Accept and Report depending on the kind of negative testing you want to perform. If you do not set the appropriate risk controls, default processing occurs, which is to accept the transaction.

Severe error conditions, such as bad arguments or invalid login, preempt negative testing because the error cannot be handled by either negative testing or positive testing. In these cases, the error condition for positive testing is raised, regardless of whether the account was enabled for negative testing.

API Testing

For APIs, you trigger an error condition by setting a field to the value of the error you want to trigger. The value you specify depends on the kind of field:

l	for amount-related fields, specify a value as a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error 10755

l	for other kinds of fields, specify the actual PP API error; for example, 10755 triggers PP API error 10755

The following table identifies the API, 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:

Table 7.1

API Fields That Trigger Error Conditions

API Name	NVP Field Name	SOAP Element	Description
RefundTransaction	AMT	Amount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error code 10755.
GetTransaction Details	TRANSACTIONID	TransactionID	Specify the error code to trigger as all digits in the field; for example, an ID of 10755 triggers PP API error code 10755.
TransactionSearch	INVNUM	InvoiceID	Specify the error code to trigger as all digits in the field; for example, an ID of 10755 triggers PP API error code 10755.
DoDirectPayment	AMT	OrderTotal	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error code 10755.
SetExpressCheckout	MAXAMT	MaxAmount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error code 10755.
GetExpressCheckout Details	TOKEN	Token	Specify the error code to trigger as all digits in the field; for example, a token value of 10755 triggers PP API error code 10755.
DoExpressCheckout	TOKEN	Token	Specify the error code to trigger as all digits in the field; for example, a token value of 10755 triggers PP API error code 10755.
DoCapture	AMT	Amount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 106.23 triggers PP API error code 10623.
DoVoid	AUTHORIZATIONID	AuthorizationID	Specify the error code to trigger as all digits in the field; for example, an ID of 10623 triggers PP API error code 10623.
DoReauthorization	AMT	Amount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 106.23 triggers PP API error code 10623.
DoAuthorization	AMT	Amount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 106.23 triggers PP API error code 10623.
MassPay	EMAILSUBJECT	EmailSubject	Specify the error code to trigger as all digits in the field; for example, a subject of 10755 triggers PP API error code 10755.
BillUser	AMT	Amount	Specify the error code to trigger as all digits in a number with two digits to the right of the decimal point; for example, 107.55 triggers PP API error code 10755.
BAUpdate Version 2.4	MPID	MpID	Specify the error code to trigger as all digits in the field; for example, an ID of 10755 triggers PP API error code 10755.
BAUpdate Version 3.0	REFERENCEID	ReferenceID	Specify the error code to trigger as all digits in the field; for example, an ID of 10755 triggers PP API error code 10755.
AddressVerify	—	—	Not supported for negative testing.

Note:

If the trigger value is not a valid error code for the API being tested, positive testing occurs for the request, which might result in another error occurring.

Negative Testing Using an Amount-Related Trigger Field

Consider an example that sets up testing for error 10623 for DoAuthorization, in which the error code is specified in the AMT field:

METHOD=DoAuthorization
&TRANSACTIONID=O-1GU0288989807143B&
AMT=106.23&
TRANSACTIONENTITY=Order&
VERSION=2.4&
USER=username&
PWD=password&
SIGNATURE=signature

The request invokes the following response:

TIMESTAMP=2007%2d04%2d04T03%3a10%3a19Z&
CORRELATIONID=447d121150529&
ACK=Failure&
L_ERRORCODE0=10623&
L_SHORTMESSAGE0=Maximum%20number%20of%20authorization%20allowed%20for%20the%20order%20is%20reached%2e&
L_LONGMESSAGE0=Maximum%20number%20of%20authorization%20allowed%20for%20the%20order%20is%20reached%2e&
L_SEVERITYCODE0=Error&
VERSION=2%2e400000&
BUILD=1%2e0006

Negative Testing Using a Non-Amount Trigger Field

Consider an example that sets up testing for error 10603 for DoVoid, in which the error code is specified in the AUTHORIZATIONID field:

METHOD=DoVoid&
AUTHORIZATIONID=10603&
VERSION=2.4&
USER=username&
PWD=password&
SIGNATURE=signature

The request invokes the following response:

TIMESTAMP=2007%2d04%2d04T03%3a10%3a22Z&
CORRELATIONID=51b0c5054dee6&
ACK=Failure&
L_ERRORCODE0=10603&
L_SHORTMESSAGE0=The%20buyer%20is%20restricted%2e&
L_LONGMESSAGE0=The%20buyer%20account%20is%20restricted%2e&
L_SEVERITYCODE0=Error
&VERSION=2%2e400000&
BUILD=1%2e0006

Negative Testing With Multiple Messages

Consider an example that sets up testing for error 10009 for RefundTransaction, which returns 14 possible error message sets:

METHOD=RefundTransaction&
TRANSACTIONID=asdf&
REFUNDTYPE=Partial&
AMT=100.09&
VERSION=2.4&
USER=username&
PWD=password&
SIGNATURE=signature

The request invokes the following response:

TIMESTAMP=2007%2d04%2d04T03%3a10%3a23Z&
CORRELATIONID=81ccc18eaec49&
ACK=Failure&
L_ERRORCODE0=10009&
L_SHORTMESSAGE0=Transaction%20refused&
L_LONGMESSAGE0=You%20can%20not%20refund%20this%20type%20of%20transaction&
L_SEVERITYCODE0=Error&
L_ERRORCODE1=10009&
L_SHORTMESSAGE1=Transaction%20refused&
L_LONGMESSAGE1=You%20are%20over%20the%20time%20limit%20to%20perform%20a%20refund%20on%20this%20transaction&
L_SEVERITYCODE1=Error&
L_ERRORCODE2=10009&
L_SHORTMESSAGE2=Transaction%20refused&
L_LONGMESSAGE2=Account%20is%20restricted&
L_SEVERITYCODE2=Error&
...
L_ERRORCODE13=10009&
L_SHORTMESSAGE13=Transaction%20refused&
L_LONGMESSAGE13=The%20partial%20refund%20amount%20must%20be%20less%20than%20or%20equal%20to%20the%20remaining%20amount&
L_SEVERITYCODE13=Error&
VERSION=2%2e400000&
BUILD=1%2e0006

Testing Using AVS Codes

You can simulate address verification by triggering an AVS error code when you call DoDirectPayment or use Virtual Terminal. To specify a code, place AVS_code in the NVP SHIPTOSTREET field or the Street1 SOAP element when you call DoDirectPayment, where code is an AVS code, or enter AVS_code in Address Line 1 when using Virtual Terminal. For example, if you set 123 AVS_A Street in the NVP SHIPTOSTREET field, AVS code A is set.

Note:

AVS_code is case sensitive; all characters must be uppercase. For example, AVS_A is valid trigger; avs_a is not.

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

Table 7.2

AVS Error Conditions and Triggers

AVS Code	Trigger	Description of Error
A	AVS_A	The address matches but no zip code is specified; results in an error if the “Partial Address Match” risk control is set.
B	AVS_B	The international address matches but no zip code is specified; results in an error if the “Partial Address Match” risk control is set.
D	AVS_D	Exact match (no error). The international address and postal code matches.
F	AVS_F	Exact match (no error). The UK address and postal code matches.
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.
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.
N	AVS_N	No address information; results in an error if the “No Address 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.
E	AVS_E	Not allowed for MOTO (internet/phone) transactions.
I	AVS_I	Service unavailable internationally; results in an error if the “Service Unavailable/Unsupported” risk control is set.
G	AVS_G	Service globally unavailable; results in an error if the “Service Unavailable/Unsupported” 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.

Note:

The specified AVS code is set, regardless of whether a PP API error code is set. If no AVS code is specified or the AVS risk control is not specified, AVS code X is returned.

Testing an AVS Code Using Virtual Terminal

Consider an example of testing for AVS code A using Virtual Terminal. You enter AVS_A in the Address Line 1 field:

Figure 7.1

Entering an AVS code in the Address Line 1 field

When you attempt to process the transaction, the following message appears:

Figure 7.2

AVS error message from Virtual Terminal

Testing an AVS Code Using DoDirectPayment

Consider an example that sets up testing for AVS code A and error code 10755 in DoDirectPayment, for which AVS 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:

METHOD=DoDirectPayment&
CREDITCARDTYPE=VISA&
ACCT=4683075410516684&
EXPDATE=112007&
CVV2=808&
AMT=107.55&
FIRSTNAME=Designer&
LASTNAME=Fotos&
IPADDRESS=255.55.167.002&
STREET=1234%20AVS_A%20Street&
CITY=San%20Jose&
STATE=CA&
COUNTRY=United%20States&
ZIP=95110&
COUNTRYCODE=US&
SHIPTONAME=Louise%20P.%20Flowerchild&
SHIPTOSTREET=1234%20Easy%20Street&
SHIPTOSTREET2=Apt%2022%20bis&
SHIPTOCITY=New%20Orleans&
SHIPTOSTATE=LA&
SHIPTOCOUNTRY=US&
SHIPTOZIP=70114&
PAYMENTACTION=Authorization&
FIZBIN=foo&
VERSION=2.4&
USER=username&
PWD=password&
SIGNATURE=Aq9tJJ3ndj7r32JgX.qAzqOoC1JJAM7erWun-CUZYFDtxffpKWU4ERQG

The request invokes the following response:

TIMESTAMP=2007%2d04%2d04T03%3a35%3a10Z&
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=2%2e400000&
BUILD=1%2e0006

Testing Using CVV Codes

You can simulate credit card validation by triggering a CVV error code when you call DoDirectPayment or use Virtual Terminal. To specify a CVV code, place a trigger value in the NVP CVV2 field or the CVV2 SOAP element when you call DoDirectPayment, or enter the trigger in Card Security Code when using Virtual Terminal.

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

Table 7.3

CVV Error Conditions and Triggers

CVV Code	Trigger	Description of Error
M	115	CVV2 matches (no error).
N	116	CVV2 does not match.
U	125	Service unavailable.
S	123	Service not supported.
P	120	Transaction not processed.
X	130	No response.

Note:

The specified CVV2 code is set, regardless of whether a PP API error code is set. If no CVV2 code is specified, M is returned.Virtual Terminal only displays the CVV2 error if the risk control blocks the payment.

Testing a CVV Code Using Virtual Terminal

Consider an example of testing for CVV code N using Virtual Terminal. You enter 116 in the Card Security Code field:

Figure 7.3

Entering a CVV code in the Card Security Code field

When you attempt to process the transaction, the following message appears:

Figure 7.4

CVV error message from Virtual Terminal

Note:

Other errors are also reported in addition to CVV code N.

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

METHOD=DoDirectPayment&
CREDITCARDTYPE=VISA&
ACCT=4683075410516684&
EXPDATE=112007&
CVV2=116&
AMT=1.55&
FIRSTNAME=Designer&
LASTNAME=Fotos&
IPADDRESS=255.55.167.002&
STREET=1234%20Easy%20Street&
CITY=San%20Jose&
STATE=CA&
COUNTRY=United%20States&
ZIP=95110&
COUNTRYCODE=US&
SHIPTONAME=Louise%20P.%20Flowerchild&
SHIPTOSTREET=1234%20Easy%20Street&
SHIPTOSTREET2=Apt%2022%20bis&
SHIPTOCITY=New%20Orleans&
SHIPTOSTATE=LA&
SHIPTOCOUNTRY=US&
SHIPTOZIP=70114&
PAYMENTACTION=Authorization&
FIZBIN=foo&
VERSION=2.4&
USER=username&
PWD=password&
SIGNATURE=signature

The request invokes the following response:

TIMESTAMP=2007%2d04%2d04T03%3a35%3a12Z&
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=2%2e400000&
BUILD=1%2e0006