DXML

Submitting Transactions in the Direct Model
Version 1
www.worldpay.com
Table Of Contents
Table Of Contents
AboutThisGuide ..................................................................................................................................1 Copyright............................................................................................................................................1 Introduction............................................................................................................................................2 WhatisXMLDirect? .........................................................................................................................2 BeforeYouStart .....................................................................................................................................4 Introduction........................................................................................................................................4 ErrorMessages,InvalidXML ..........................................................................................................6 StructureofanXMLDirectOrder.......................................................................................................8 Introduction........................................................................................................................................8 XMLandDocumentTypeDeclaration...........................................................................................8 MerchantandServicespecificInformation ...................................................................................8 OrderDescriptionandAmount ......................................................................................................9 OrderContent ....................................................................................................................................9 PaymentDetailsandSessionInformation ...................................................................................10 ShopperInformation .......................................................................................................................11 XMLDirectOrderExample ...........................................................................................................12 ResponsefromthePaymentService .................................................................................................15 Introduction......................................................................................................................................15 ReplytoanXMLDirectOrder.......................................................................................................15 PostinganXMLOrder ........................................................................................................................17 Introduction......................................................................................................................................17 SettinguptheConnection..............................................................................................................17 Submittinga3DSecureOrder..........................................................................................................18 Introduction......................................................................................................................................18 TheProcessFlow .............................................................................................................................18 XMLMessagesandHTMLRedirect .............................................................................................20 TestEnvironment ............................................................................................................................24 Appendices...........................................................................................................................................26 Introduction......................................................................................................................................26 PaymentMethodCodes .................................................................................................................26 ISOCurrencyCodes........................................................................................................................28 AcquirerResponseCodes...............................................................................................................31 ISOCountryCodes..........................................................................................................................34
ii
Table Of Contents
CVC/CVVChecksandResponses.................................................................................................49 TestingTransactions........................................................................................................................50 XMLErrorCodes.............................................................................................................................52
iii
About this Guide
About This Guide
ThisguidedescribesthespecificationsofXMLorderssenttotheWorldPaysysteminthe XMLDirectmodel.Theintendedaudienceisthemerchantstechnicalstafforthe merchantssystemintegrator. BecausealmostallcommunicationbetweenthemerchantssystemandtheWorldPay PaymentServiceisrealisedthroughpredefinedXMLmessagesovertheInternetusing standardprotocols,youwillneedbasicXMLprogrammingskillsandknowledgeof HTTP(S).Furthermore,itisrecommendedthatyouarefamiliarwiththebasicsofthe Paymentsystem.Whereapplicable,thisdocumentreferstotherelateddocumentation withfurtherdetails.
Copyright
2008WorldPay.Allrightsreserved. Whileeveryefforthasbeenmadetoensuretheaccuracyoftheinformationcontainedin thispublication,theinformationissuppliedwithoutrepresentationorwarrantyofany kind,issubjecttochangewithoutnoticeanddoesnotrepresentacommitmentonthepart ofWorldPayLtd.WorldPayLtd,therefore,assumesnoresponsibilityandshallhaveno liability,consequentialorotherwise,ofanykindarisingfromthismaterialoranypart thereof,oranysupplementarymaterialssubsequentlyissuedbyWorldPayLtd.WorldPay Ltdhasmadeeveryefforttoensuretheaccuracyofthismaterial.
SubmittingTransactionsintheDirectModelPage1
Introduction
Introduction
What is XML Direct?

Merchantswhocollectandstoretheirshopperspaymentdetailsontheirownplatform canusetheXMLDirectmodelasaneffectivepaymentprocessinggateway.Withthis model,themerchantcollectsbothorderandpaymentdetailsandthencommunicatesthe relevantpaymentdetailsonaperorderbasiswithWorldPay,forprocessing.
Security
AcoreissueassociatedwithusingtheXMLDirectmodelissecurity.Thecollectionand storageofpaymentinformation,suchas,cardnumbersandcardholdernamesmusttake placeinasecureenvironment.
Payment Card Industry Data Security Standard (PCI DSS)

PCIDSSisaglobalCardSchemeinitiativethataimstoensurethateveryentitythat handles,storesorprocessescardholderdatadoessoinasecuremanner.MasterCardand Visahavecombinedtheirownsecuritystandardsforcardholderdatacreatinganaligned program,whichisnowendorsedbyAmericanExpress,JCBandDiners.MuchofPCIDSS relatestothetechnologyinvolvedincapturingandprocessingcarddataandthisis particularlyrelevanttothosemerchantswhoprocessandcapturecardholderdataontheir ownsystemsratherthanthosewhousethesecureWorldPaypaymentpages. Formoreinformation,pleaserefertoPCIDSSandtothePCISecurityStandardsCouncil at:www.pcisecuritystandards.org.Ifyouwantanyhelptogaincompliancethissitealso listsPCIapprovedQualitySecurityAssessors(QSA)whocanprovidetechnicaladvice (chargeable).
3-D Secure Authentication

Youcanreduceyourexposuretofraudandincreaseconfidenceinonlineshoppingby implementing3DSecureAuthenticationwiththeDirectModel.Theadditionalsecurity benefitsandliabilityshiftsofauthenticatedtransactionsarecurrentlyonlysupportedby cardswithintheVisaandMasterCardbrands. From30thJune2008,MasterCardrequiresthatyourwebsite implements3DSecureauthenticationinorderforyoutocontinue acceptingMaestropayments.Pleasealsonotethatatsomepointin thefutureweexpectthatthismandatewillbeappliedtoallVisa andMasterCardtransactions.
Introduction
Thebenefitsofthe3DSecureprocessaretheenhancedsecurityavailablewhen performinganauthenticatedtransactionaswellastheshiftofliabilityintheeventof fraudulenttransactions.Authenticationshouldstrengthenyourexistingantifraud strategyandhelpprotectyourbusiness,butbearinmindthatcoverageofauthentication programmesiscurrentlylimitedtoInternettransactions.Thismeansthatauthentication programmesdonotcoverfax,mail,orphoneorders,nordotheycoverallcardtypes. Forfurtherdetailsaboutauthentication,refertotheCardholderAuthenticationguide.
Before You Start
Before You Start
Introduction
Fromatechnical/ITviewpoint,settingupasuccessfulconnectionbetweenyoursystem andtheWorldPaypaymentsystem,involvesthefollowingmajorsteps: ordercreation:automatingthecreationofanXMLdocumentthatconformswith therulesspecifiedintheWorldPayDocumentTypeDefinition(DTD),fromorder datacapturedfromyourshoppersbyyoursystems.Thistopiciscoveredindetail inthisguide. Ordercreationcanbeachievedinanumberofdifferentways dependingonthescriptinglanguagethatyouareusing.Thisguide providesanoverviewonly.WorldPaycannotadviseonhowto specificallycreateanXMLorderusingASPorPHP,orhowto establishthesecureconnection.
accountsettings:beforesendingtestorderstothePaymentServicecheckand,if necessary,updatesettingsthatcontrolaspectsofhowtheserviceworks.For example,settingadelaybetweenauthorisationandcapture. ordersubmission:settingupanHTTP(S)connectionbetweenyoursystemandours andautomatingthesendingofXMLordersoverthatconnection.Thistopicis coveredinthisguide. paymentresponse:automatethereceptionandprocessingofrepliesfromour system.Youhaveachoiceofhowyouautomatethereceptionofrepliesusingone ofthefollowingtwomethods. o HTTP(S)PaymentResponsefeature(callback)whenenabled,WorldPay willsendanHTTPPOSTofthepaymentinformationfromourservertoa URLonyourserverviaHTTP(S).Fordetails,refertothe(HTML) PaymentResponseguide. OrderNotificationswhenenabled,youcanreportonpaymentstatus changesofindividualpayments.Usingthisfunctionalityyoucanselect thechannel(protocol)andformat.Ordernotificationscanbesentthrough twodifferentchannels:email(SMTP)andHTTP(S)andindifferent formats:CGI,textandXML.
modifyandqueryorderdata:administertransactionsremotely,thatis,fromoutside (andinadditionto)WorldPaysMerchantAdministrationInterface(MAI).You haveachoiceofhowyouworkremotelyusingoneofthefollowing:
Before You Start
WorldPaysRemoteAdministrationfeature.Thisfeatureenablesyouto completeatransactionafteracapturedelay,orrefundacaptured transaction. OrderModificationsandInquiries.Thisfunctionalityautomatesthe creationofXMLstatementsthatconformtotherulesasspecifiedinthe WorldPayDTD,tomodifyandqueryorderdatainoursystem.This serviceenablesyoutocancel,captureorrefundthepaymentthatbelongs toanorder,ortoaddabackofficecodetoanorder.Additionally,by sendinganXMLorderinquiryyoucanactivelyinquireaboutthecurrent paymentstatusofanexistingorder.
Pleasenotethefollowingbeforeproceeding.
Account Settings
Anumberofthesettingsthataffectthewaytheserviceworks,canonlybemodifiedvia ouronlineadministrationtool,theMerchantAdministrationInterface.Mostsettingscan beamendedfromwithintheInstallationpageoftheMerchantAdministrationInterface. Thisincludesthesettingsforadministratingthereceptionandprocessingofrepliesfrom theWorldPaysystem. Notetoremember:youhaveaseparateMerchantAdministrationInterfaceforyour ProductionenvironmentandforyourTestenvironment.Youcanlogintoboth,via:
http://www.worldpay.com/admin
AnychangestosettingsmustbemadeintheProduction environmentintheMerchantAdministrationInterface.Thesettings canthenbecopiedovertotheTestenvironment.
Connect Using Login Name and XML Password

WhensettinguptheHTTP(s)connectionoverwhichyouwillsendXMLorders, remembertouseavalidloginandpassword. Yourloginnameistherelevantmerchantcode(tolookupthemerchantcode(s)allocated toyourorganisation,logintotheMerchantAdministrationInterfaceandrefertothe statusboxinthelefthandsideofthepage). TheXMLpasswordisyourInvisibleAuthpassword.Thisissetupbydefaultby WorldPay.IftherearemultipleinstallationsusedbyyourAdministration,thenthe passwordisthatofthelowestInstallationID. YourXMLpasswordcanonlybechangedbyWorldPay.Ifyou needtochangeyourpassword,pleasecontactCustomerServicesat: customerservices@worldpay.com.
Before You Start
Error Messages, Invalid XML

ReceivingInvalidXMLerrormessages?Noorderscreated?WonderingwhyyourXML isinvalid?ThemostcommoncauseoferrorwhenpostingXMLtothePaymentService isincorrectlyformedXML. MostoftheincorrectXMLissueswillberesolvedbyusinganindustrystandardparser. XMLmessagesshouldbeparsedpriortosendingthemtotheWorldPayPaymentService anduponreceipt.Thisensuresthatthemessagessentarevalidandmessagesreceivedare correctlyinterpreted.Whenparsing,pleaseensurethatyouareusinganindustry standardParserthatparsesthemessageagainsttheDocumentTypeDefinition(DTD) (refertoReferencetheDTDbelow).Donotrelyonaselfbuiltparser.Pleasereferto http://www.xml.orgforfurtherdetailsonXMLandparsers. ForexamplesofXMLerrorsmessagesoursystemmayreturn,pleaserefertotheappendix XMLErrorCodes. XMLmessagesmustadheretothefollowingrulesinordertobeaccepted.
Use Valid Syntax

AllXMLmessagessenttothesystemmustbewellformedandvalid.FortheXMLtobe wellformed,itmustadheretoanumberofrules,including: everystarttagmusthaveamatchingendtag elementsmustnotoverlap theremustbeexactlyonerootelement attributevaluesmustbequoted anelementmaynothavetwoattributeswiththesamename commentsandprocessinginstructionsmaynotappearinsidetags nounescaped[<]or[&]signsmayoccurintheelementsorattributescharacter data.
Reference the DTD

AvalidXMLmessagemustalwaysincludeareferencetotheDTD,soitcanbe automaticallycomparedwithitinordertocheckifallthereferencesusedarecorrect. TheDTDisspecifiedintheheaderoftheXMLmessageandwilllookasfollows:
<?xml version="1.0"? encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
Use Declared Elements Only

Everyelement,attributeandentityintheXMLthatyousend,mustbedeclaredinthe DTD(DocumentTypeDefinition). XMLelementscanbedeclaredtocontain: nametokens(NMTOKEN)
Before You Start
parsedcharacterdata(PCDATA) characterdata(CDATA)orconstants.
TheDTDcanbefoundat:http://dtd.worldpay.com/paymentService_v1.dtd
Name Tokens
AnXMLnametokenconsistsofalphanumericand/orideographiccharactersandthe punctuationmarks[_],[],[.],and[:].Noothercharactersareallowed.AnXMLname tokenmaynotcontainwhitespaces. Ifanattributeisdeclaredtocontainanametokenorlistofnametokens,thevaluesof theseattributesmustbelegalXMLnametokens.Belowyoucanfindanexampleofthis:
<!ELEMENT amount EMPTY> <!ATTLIST amount value NMTOKEN #REQUIRED currencyCode NMTOKEN #REQUIRED exponent (0 | 2 | 3 ) #REQUIRED debitCreditIndicator (debit | credit ) 'credit' >
Avalidinstanceofanamountelementlookslikethis:
<amount value="4938" currencyCode="SEK" exponent="2" />
PCDATA
InaPCDATA(ParsedCharacterDATA)blockintheXMLmessagethefollowingspecial charactersshouldnotbeincluded:[&],[<],[>]and[].Ifyouneedtousethesecharacters withinaPCDATAblockyoushouldspecifythemasfollows: &=& >=> <=< =" Forexample,forthedescriptionelementwhichisdeclaredtocontainPCDATA <!ELEMENTdescription(#PCDATA)>avalidexamplewouldbe:
<description>Your Holland & Holland Catalogue</description>
CDATA
InaCDATA(CharacterDATA)blockitisallowedtoincludeanydata/charactersaslong asitadherestothespecifiedencodinganddoesnotcontainthecharactersequence: ]]>. ACDATAblockmustbeenclosedbetweenthestarttag<[CDATA[andtheendtag]]>. Forexample:
<[CDATA[This text has not been parsed & still can be used]]>
Structure of an XML Direct Order
Introduction
OrderssubmittedtotheWorldPaysystemarerequiredtobevalidXMLfilesasspecified inthisguideandintheDocumentTypeDefinition(DTD),availableat:
http://dtd.worldpay.com
XMLfilesarevalidiftheyarewellformed,thatis,theyhaveacorrectXMLsyntax,and conformtoaDocumentTypeDefinition. Thetopicscoveredinthischapterare: XMLandDocumentTypeDeclaration MerchantandServicespecificInformation OrderDescriptionandAmount OrderContent PaymentDetailsandSessionInformation ShopperInformation XMLOrderExample
Notefordetailsofsubmittinga3DSecurepaymentrequest,pleaserefertothechapter Submittinga3DSecureOrder.
XML and Document Type Declaration

ToprocessanXMLDirectorderthesubmissionmustbeginwithanXMLdeclarationand adocumenttypedeclaration,containingtherootelementpaymentServiceandthe referencetoourpublicDTD:
<?xml version="1.0"?> <!DOCTYPE paymentService PUBLIC "-//worldpay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd">
Merchant and Service-specific Information

ThepaymentServicerootelementhastworequiredattributes:theversionnumberof thePaymentServiceDTDandyourmerchantcode.Themerchantcodeisissuedby WorldPayandisalwaysincapitals. AnexampleformerchantcodeWPACC11112222is:
<paymentService version="1.4" merchantCode="WPACC11112222"> <submit> ... </submit> </paymentService>
ThepaymentServiceelementcontainsthechildelement<submit>toclassifytheXML messageasasubmission.
Order Description and Amount

Withinthesubmitelement,theorderelementanditscontentdescribethegoodsor servicesthatarebeingordered. Theorderelementhastworequiredattributes: anorderCodeattributewhosevaluemustbeunique.Ordercodescanbeupto64 characterslong;neitherspaces,quotesnorthe<and>charactersareallowed. YoumayusetheorderCodeattributetocontainaCartIDaslongasitisunique.Ifa CartIDisnotunique,thenwerecommendyouuseeither: thedescriptionelement(seebelow)toentertheCartID;or usetheorderCodeattributebutappendauniquenumbertoastaticCartID.
aninstallationidattribute.ThisshouldbeyourXMLInvisibleinstallationidthatyou havereceivedfromWorldPay. Anorderwithapreviouslyusedordercodecannotbeprocessed correctlyandyouarelikelytoreceiveerrormessagesandencounter problemswithreporting.
Thefirsttwochildelementsoftheorderelementaredescriptionandamount.The descriptionelementshouldcontainasimpleonelinedescriptionoftheorderandcan beupto255characterslong.Theamountelementhastheattributes:value(nodecimal pointorcomma),thecurrencyCode(ISO4217code)andexponent(specifieswherethe decimalpointorcommashouldbeplaced,countingfromtheright).Theamountvalueis thetotalamounttheshopperisexpectedtopay.Alistofcurrencycodesandtheir respectiveexponentscanbefoundintheappendixISOCurrencyCodes.

<order orderCode="T0211010" installationId="12345"> <description>20 English Roses from MYMERCHANT Webshops</description> <amount currencyCode="GBP" exponent="2" value="5000"/> ... </order>
Order Content
ThethirdchildelementoftheorderelementisorderContent.Youcandeliverthe ordercontentinHTMLformat.WhensupplyingHTMLordercontenttheonlyHTMLtags allowedarethetagspermittedbetweenthe<body>and</body>tagsofavalidHTML document!Noformofscriptingisallowedintheordercontent. Theordercontentmustbelessthan10kilobytesandshouldalwaysbeincludedina CDATAsectiontoavoidparsingproblems.
<orderContent> <![CDATA[content here]]> </orderContent>
Theordercontentmaycontain: ordercode product(s)and/orservice(s)ordered itemprice totalamount shopperbillingaddress shoppershippingaddress contactdetailsmerchant thefactthatWorldPayprocessesthepayment thefactthatthenameWorldPaymayappearontheshoppersbankorcreditcard statements.
Payment Details and Session Information

ThefourthorderchildelementispaymentDetailsandcontainsthedetailsofthe selectedpaymentmethod.Eachpaymentmethodhasitsownsetofsubelementsand attributes.PleaserefertothespecificationsofthepaymentDetailselementintheDTD foranuptodatelistofavailablepaymentmethodcodesfortheDirectmodelandtheir childelements.ThepaymentmethodcodesarelistedintheappendixPaymentMethod Codes. Inadditiontotheregularpaymentdetailsyouneedtoprovideinformationaboutthe shopperbrowsersessioninthepaymentDetailschildelementsession,containingthe shopperIPAddress and session id. WorldPayusesthepaymentdetailsandsessioninformationforrisk assessment.Theyareamandatoryelementina3DSecure transaction.
AnexampleofthepaymentDetailsforaVISApayment,whereVISA-SSListhe paymentmethodcode,is:
<paymentDetails> <VISA-SSL> <cardNumber>4444333322221111</cardNumber> <expiryDate> <date month="09" year="2009"/> </expiryDate> <cardHolderName>J. Shopper</cardHolderName> <cvc>123</cvc> <cardAddress> <address> <firstName>John</firstName> <lastName>Shopper</lastName> <street>47A Queensbridge Rd</street>  <postalCode>CB94BQ</postalCode> <city>Cambridge</city> <countryCode>GB</countryCode> <telephoneNumber>01234567890</telephoneNumber> </address> </cardAddress> </VISA-SSL> <session shopperIPAddress="123.123.123.123" id="0215ui8ib1" /> </paymentDetails> <shopper> <shopperEmailAddress>jshopper@myprovider.int</shopperEmailAddress> </shopper> <shippingAddress> <address> <firstName>John</firstName> <lastName>Shopper</lastName> <street>47A Queensbridge Rd<street/>  <postalCode>CB94BQ</postalCode> countryCode>GB</countryCode> <telephoneNumber>01234567890</telephoneNumber> </address> </shippingAddress> </order> </submit> </paymentService>
TheCDATAsectionintheorderContentelementcontainsacompleteinvoiceinHTML. Theimagebelowshowswhatthisordercontentlookslikewhenviewedwithaweb browser.
Figure 1: Example HTML order content as viewed with a browser.
Response from the Payment Service
Introduction
WhenthePaymentServicehasreceivedavalidorderwithpaymentdetailsitwillsend theinformationtothefinancialinstitutions(acquirers)forauthorisation.Theresultofthe authorisationrequestisreportedtoWorldPayonlineaseitherAUTHORISEDor REFUSED.IntheXMLDirectmodel,WorldPaysendsanXMLresponsetoyoursystem thatcontainsthepaymentstatusoftheorder. WhenparsingWorldPaysreplyitisimportantthatyouuseanindustrystandardXML parser.Donotdependonahomemadeone,whichmaynotbeabletocorrectlyinterpret themessagesreceivedfromWorldPay.ForvariousplatformsdifferentXMLparsersexist. Pleaserefertohttp://www.xml.org. Thetopicscoveredinthischapterarelistedbelow. ReplytoanXMLDirectOrder
Notefordetailsofrepliesinresponsetoa3DSecurepaymentrequest,pleaserefertothe chapterSubmittinga3DSecureOrder.
Reply to an XML Direct Order

TheexamplebelowshowsapossibleXMLreplyfromWorldPayforasuccessful authorisationoftheexampleorder,shownearlier.
<?xml version="1.0"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService merchantCode="WPACC11112222" version="1.4"> <reply> <orderStatus orderCode="T0211010"> <payment> <paymentMethod>VISA-SSL</paymentMethod> <amount value="1400" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/> <lastEvent>AUTHORISED</lastEvent> <CVCResultCode description="APPROVED"/> <balance accountType="IN_PROCESS_AUTHORISED"> <amount value="1400" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/> </balance> <cardNumber>4444********1111</cardNumber> </payment> </orderStatus> </reply> </paymentService>
Inthereply,thepaymentelementholdstherelevantpaymentdetailsandstatus information.ItschildelementspaymentMethodandamountcontainthepayment methodusedandtheamount,includingthecurrency,itsexponentandthe debitCreditIndicatorthatindicatestheamountispositive. ThepaymentstatusisspecifiedbythelastEventelement.ACVCresultdescriptionis reportedthroughtheCVCResultCode element.Thebalanceelementreportsonthe balanceintheIN_PROCESS_AUTHORISEDaccount.Forcreditcardpaymentsthefirst andlastfourdigitsofthecardnumberarereturnedinthecardNumberelement. AlwaysrefertotheWorldPayDTDforanuptodatelistofchildelementsandattributes ofthereplyelement.
Posting an XML Order
Posting an XML Order
Introduction
TosubmitanXMLorderyouhavetosetupanHTTP(S)connectiontothePayment Service.HowyoucreateaconnectionwiththeWorldPayserverdependsonthe specificationsofyourplatform. Thetopicscoveredinthischapterarelistedbelow. o SettinguptheConnection
Setting-up the Connection

OnceyouhavesetuptheconnectiontothePaymentServiceusingavalidloginand password,yoursystemhastoposttheXMLorder. MakesuretheHTTPcontenttypeistext/xml!Itisimportanttocheckthatcontentlength isspecifiedcorrectly.Notspecifyingthecontentlengthwillnotcreateerrors,whilespecifyingit incorrectlywill. TheURLstopostorderstoare: o Testenvironment:https://secure test.ims.worldpay.com/jsp/merchant/xml/paymentService.jsp Production/Liveenvironment: https://secure.ims.worldpay.com/jsp/merchant/xml/paymentService.jsp
Submitting a 3-D Secure Order
Introduction
Thischapterdescribeshowyoushouldimplement3DSecureAuthenticationusingthe XMLDirectmodel.ThisprocessinvolvesprovidingrepliestotwoXMLmessagesand redirectingtheshoppertoanauthenticationpage.Thispageisprovidedandhostedby theshoppersCardIssuer.PleasenotethatourTestEnvironmentenablesyoutotestyour implementation. Implementinga3DSecureAuthenticationisdescribedinthefollowingtopics: TheProcessFlowadiagramshowingtheflowofinformationduringthe authenticationprocess XMLMessagesandHTMLRedirectexamplesoftheXMLmessagesandtheHTML redirectpage o o o o o InitialOrderMessage(arrow2indiagram) InitialOrderReplyMessage(arrow3indiagram) RedirectShoppertoIssuer(arrow4indiagram) SecondOrderMessage(arrow6indiagram) SecondOrderReplyMessage(arrow8indiagram)
TestEnvironmenthowtousethetestenvironment
The Process Flow

Thefigurebelowdescribestheflowofmessagesbetweenthedifferententitiesinvolved.
Figure: The Process Flow 1. 2. 3. theshopperplacesanorderwiththemerchant themerchantsendsanXMLmessagewithorderinformationtooursystem,refer toInitialOrderMessage(arrow2) WorldPayverifythatthecardisparticipatingin3DSecureareplymessageis sentbacktothemerchanttorequestpayerauthentication,refertoInitialOrder ReplyMessage(arrow3) themerchantredirectstheshoppertotheissuersiteforauthenticationusing informationinthereplymessage,pleaserefertoRedirecttheShoppertoIssuer (arrow4) theauthenticationresponseissenttotheshopper,andthepayerauthentication responseisthenpostedtothemerchantssite themerchantincludestheauthenticationresponseintheoriginalXMLorder messageandsendsittoWorldPay,pleaserefertoSecondOrderMessage(arrow 6) iftheauthenticationresponseshowsthattheshopperfailedtoauthenticate themselves,thenthemerchantwillreceiveeitheraRefusedmessagefrom WorldPayiftheRiskManagementModule(RMM)isactivatedoriftheRMMis notactivatedthenyouwillreceivethe3DSecurereferralmessageagain(step3) iftheauthenticationresponseshowsthattheshopperwasauthenticatedthenwe verifythattheauthenticationresponsebelongstotheauthenticationrequestand proceedwithauthorisationexchangewiththeacquirer,includingthe3DSecurity Authenticationinformation afterreceivingtheresponsefromtheacquirer,WorldPaysendanauthorisation responsetothemerchant,pleaserefertoSecondOrderReplyMessage(arrow9)
4.
5. 6.
7.
8.
9.
XML Messages and HTML Redirect

ThefollowingXMLmessagesandHTMLpageareinvolvedintheauthenticationprocess: theinitialordermessage(arrow2indiagram) replyfortheinitialordermessage(arrow3indiagram) redirecttheshoppertotheissuer(arrow4indiagram) thesecondordermessagewiththeauthenticationresponse(arrow6indiagram) replyforthesecondordermessage(arrow8indiagram)
Creating an Initial Order Message (arrow 2)

ThefollowingsectiondetailstheadditionalXMLrequiredtoprocessarequestand explainstheinformationreturnedinthesubsequentresponse. Thefirstordermessageisalmostthesameastheregularordermessages.Onlyafew additionalelementsareaddedandsomeelementsaremademandatoryforusewith3D Secure. Thefollowingordermessageexampleshowsonlythemandatoryelements.
<paymentService merchantCode="MYMERCHANT" version="1.4"> <submit> <order orderCode="merchantGeneratedOrderCode" installationId="12345"> <description>Description</description> <amount currencyCode= exponent="2" value="5000"/> <orderContent>Default Order Content</orderContent> <paymentDetails> <VISA-SSL> <cardNumber>4111111111111111</cardNumber> <expiryDate> <date month="02" year="2008"/> </expiryDate> <cardHolderName>3D</cardHolderName> </VISA-SSL> <session shopperIPAddress="123.123.123.123" id="112233"/> </paymentDetails> <shopper> <browser> <acceptHeader>text/html</acceptHeader> <userAgentHeader>Mozilla/5.0 ...</userAgentHeader> </browser> </shopper> </order> </submit> </paymentService>
Thenewelementsarebrowser, acceptHeader and userAgentHeader.These elementsareusedtoredirecttheshoppertothecorrectissuersiteforauthentication. TheacceptHeaderelementshouldcontaintheexactcontentoftheHTTPacceptheader assenttothemerchantfromtheshoppersuseragent. TheuserAgentHeaderelementshouldcontaintheexactcontentoftheHTTPuseragent headerassenttothemerchantfromtheshoppersuseragent.
Initial Order Reply Message (arrow 3)

ThismessageextendstheorderStatuselementwithanewsubelement;requestInfo. Thiselementisacontainerforpossiblerequestsforinformationonthesubmittedorder. Arequestfor3DSecureauthenticationisdefinedwithelementname request3DSecure.Anexampleofthecompletemessageisshownbelow.
<paymentService merchantCode="MYMERCHANT" version="1.4"> <reply> <orderStatus orderCode='merchantGeneratedOrderCode'> <requestInfo> <request3DSecure> <paRequest>somedata</paRequest> <issuerURL>http://example.issuer.url/3dsec.html</issuerURL> </request3DSecure> </requestInfo> <echoData>somedata</echoData> </orderStatus> </reply> </paymentService>
TheelementpaRequestcontainsdatathatwasreceivedfromthe3DSecurityDirectory. Thisdatamustbesuppliedasisintheredirectmessagetotheshoppersissuersite. TheissuerURLelementcontainstheactualURLtowhichtheshoppermustbe redirected.ThisisshoppersIssuersitewheretheshoppershouldauthenticatethemselves withthe3DSecuremechanism. AnextraelementechoDataisadded,whichisusedbyoursoftwaretoprocessthe subsequentmessagesbelongingtothesametransactionmoreefficiently.Thiselement mustbesuppliedinallsubsequentmessagesasis.
Redirect the Shopper to Issuer (arrow 4)

Whenthemerchantreceivesthefirstreplywiththerequestfor3DSecureauthentication, themerchantmustredirecttheshoppertotheissuerssite.Thismustbedonebyposting anHTMLformtotheIssuerURL.TheformmustcontaintheattributesPaReqand TermUrl.OptionallyitcancontainanattributeMD. TheIssuerssiteURL,towhichtheformmustbeposted,isgivenintheissuerUrl elementofthereplymessage. ThevalueforthePaReqattributemustbethedatasuppliedinthepaRequestelement ofthereplymessage. ThevaluefortheTermUrlattributeisaURLpointingtothemerchantssite.Itspecifies theservicetowhichtheshopperisredirectedfromtheissuerssite.Themerchantis responsibleforsupplingacorrectvalue. TheMDattributecancontainanydataandwillbesuppliedasisinthefinalpostwhen theshopperisredirectedfromtheIssuerssitetothemerchantssite(thevalueofthe TermUrlattribute).Thisattributecanbeusedbythemerchanttohandlethesessionstate betweentheoriginalshoppingsessionandthefinalpostaftertheshopperhasbeen authenticated. ThisHTMLexamplepageredirectstheshoppertotheIssuerssite:
<html> <head> <title>3-D Secure helper page</title> </head> <body OnLoad="OnLoadEvent();"> This page should forward you to your own card issuer for identification. If your browser does not start loading the page, press the button you see. <br/> After you successfully identify yourself you will be sent back to this site where the payment process will continue as if nothing had happened.<br/> implemented... <form name="theForm" method="POST" action="value of the issuerUrl element" > <input type="hidden" name="PaReq" value="value of the paRequest element" /> <input type="hidden" name="TermUrl" value="url of merchant site" /> <input type="hidden" name="MD" value="merchant supplied data" /> <input type="submit" name="Identify yourself" /> </form> <script language="Javascript"> <!-function OnLoadEvent() { // Make the form post as soon as it has been loaded. document.theForm.submit(); } // --> </script> </body> </html>
WhentheshopperhasenabledJavascriptinthebrowser,theshopperwillautomatically beforwardedtotheIssuerssite.IfJavascripthasbeendisabled,theshoppermustpress theSubmitbuttoninordertocontinue.
Second Order Message (arrow 6)

Thesecondordermessageisalmostthesameastheinitialordermessage.Onlytwo elementsareadded,theinfo3DSecureelement(andsubelements)andtheechoData element.Asshownintheexamplebelow.
<paymentService merchantCode="MYMERCHANT" version="1.4"> <submit> <order orderCode="merchantGeneratedOrderCode" installationId="12345"> <description>Description</description> <amount currencyCode="GBP" exponent="2" value="5000"/> <orderContent>Default Order Content</orderContent> <paymentDetails> <VISA-SSL> <cardNumber>4111111111111111</cardNumber> <expiryDate> <date month="02" year="2006"/> </expiryDate> <cardHolderName>3D</cardHolderName> </VISA-SSL> <session shopperIPAddress="123.123.123.123" id="112233"/> <info3DSecure> <paResponse>somedata</paResponse> </info3DSecure> </paymentDetails> <shopper> <browser> <acceptHeader>text/html</acceptHeader> <userAgentHeader>Mozilla/5.0 ...</userAgentHeader> </browser>
</shopper> <echoData>somedata</echoData> </order> </submit> </paymentService>
Theinfo3DSecureelementcontainsthepayerauthenticationresponsedatareceivedby theshopper/merchantfromtheissuer. IntheechoDataelement,themerchantmustsupplythesamedataasitreceivedinthe firstreplymessage. Notethatweuseafarmofwebserverstoservetherequestsand WorldPayneedtoensurethatthefirstandsecondordersare successfullymatchedup.Inordertofacilitatethis,youneedto extractthesessioncookiethatispassedbackintheheaderofthe XMLdocument(theresponsefromthePaymentService)andreturn itintheheaderofthesecondXMLorder.
Failed Authentication (arrow 7)

Ifashopperfailstoauthenticatethemselves,thenyouwillreceiveoneoftworeplies dependingonwhethertheRiskManagementModuleisactivatedornot.
Refused
IftheRiskManagementModuleisimplementedforyourAdministration,youwillreceive anormalREFUSEDreply.
<payment> <paymentMethod>MAESTRO-SSL</paymentMethod> <amount value="2750" currencyCode="GBP" exponent="2" debitCreditIndicator="credit"/> <lastEvent>REFUSED</lastEvent> <ISO8583ReturnCode code="76" description="CARD BLOCKED"/> </payment>
3D-Secure Referral Message

IftheRiskManagementModuleisnotimplementedforyourAdministration,youwill receivethe3DSecurereferralmessageagain(refertoInitialOrderReplyMessage(3)).
<paymentService merchantCode="MYMERCHANT" version="1.4"> <reply> <orderStatus orderCode='merchantGeneratedOrderCode'> <requestInfo> <request3DSecure> <paRequest>ThePaReq</paRequest> <issuerURL>http://example.issuer.url/3dsec.html</issuerURL> </request3DSecure> </requestInfo> <echoData>somedata</echoData> </orderStatus> </reply> </paymentService>
Second Reply Message (arrow 9)

Authorised
Iftheshopperauthenticatessuccessfully,youwillreceivethenormalreplyforauthorised payments.Noadditionalelementsareadded.
<paymentService merchantCode="MYMERCHANT" version="1.4"> <reply> <orderStatus orderCode="merchantGeneratedOrderCode"> <payment> <paymentMethod>VISA-SSL</paymentMethod> <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="10000"/> <lastEvent>AUTHORISED</lastEvent> <balance accountType="IN_PROCESS"> <amount currencyCode="EUR" debitCreditIndicator="credit" exponent="2" value="10000"/> </balance> <balance accountType="AUTHORISED"> <amount currencyCode="EUR" debitCreditIndicator="debit" exponent="2" value="10000"/> </balance> <cardNumber>4111********1111</cardNumber> </payment> </orderStatus> </reply> </paymentService>
Test Environment
Inorderformerchantstotesttheir3DSecureimplementation,weprovideatestpayment service.ThisservicecanbeusedtosubmitdummyXMLorders.Notethatyoumustbe enabledfor3DSecurebeforeyoucanusethetestpaymentservice.Wealsoprovidea dummyissuersitesothatpartoftheprocesscanalsobetested. ThevalueofthecardHolderNameelementintheXMLordermessagecanbeusedto manipulatethetest,asfollows: ifthecardHolderNameis3Dthenthetestenvironmentwillactasifthecredit cardisparticipatingin3DSecure(thatis,the3DSecurityDirectorywould respondwithenrolled) ifthecardHolderNameisNO3Dthenthetestenvironmentwillactasifthe creditcardisnotparticipatingin3DSecure(thatis,theDirectorywouldrespond withnotenrolled) withanyothervalueforcardHolderName,thetestenvironmentwillactasifitis anormalecommercetransaction(thatis,nolookupwiththeDirectory).
YoucanusethevalueofthepaResponseelementtomanipulatetheoutcomeofthe payerauthentication.Therearethesepossibilities: avalueofIDENTIFIEDmeanstheshoppersidentityissuccessfullyverified avalueofNOT_IDENTIFIEDmeanstheshoppersidentificationcouldnotbe verified
avalueofUNKNOWN_IDENTITYmeansthattheauthenticationfailed andanyothervaluemeanstheverificationprocessitselffailed.
Usingthedummyissuersite,thesethreeoptionscanbeselectedwithadropdownlist. NotethatintheProductionenvironment,thelengthofthepaResponse elementcanbeupto4.7KB.However,intheTestenvironmentyou shoulduseconsiderablyshorterlengths,suchasthoseshownabove, otherwiseaparseerrorwillbegenerated.
Appendices
Appendices
Introduction
Theappendicesavailableforthisguidearelistedbelow. o o o o o o o PaymentMethodCodes ISOCurrencyCodes AcquirerResponseCodes ISOCountryCodes CVC/CVVChecksandResponses TestingTransactions XMLErrorCodes
Payment Method Codes

Thechildelementsbelowareusedtodefinethecardtypethatisusedbytheshopper. payment method paymentType
Amex
AMEXSSL
Diners Card
DINERSSSL
ELV
ELVSSL
JCBCard
JCBSSL
MasterCard
ECMCSSL
SoloCard
SOLO_GBSSL
Maestro
MAESTRO SSL
Appendices
VisaCard
VISASSL
VisaDelta
VISASSL
Visa Electron
VISASSL
Visa Purchasing
VISASSL
Appendices
ISO Currency Codes

CurrenciesacceptedbytheWorldPayPaymentServicearelistedbelow. PleasenotethatthevaluesintheorderssenttoWorldPayNEVERhaveanydecimal delimiters.Merchantsshoulduseexponentinstead.Exponentisthenumberofdecimals availableinthecurrency.Alsonotethatcurrencycodeisalwaysincapitals. InthefollowingexampletheamountpayablebytheshopperisEuro19,82:
<amount value="1982" currencyCode="EUR" exponent="2"/>
ThefullISO4217listcanbefoundat:http://www.id3.org/iso4217.html
ISO 4217 Currency Codes

code ARS Name Nuevo Argentine Peso Australian Dollar Brazilian Real Canadian Dollar Exponent 2
AUD
BRL
CAD
CHF CLP
SwissFranc 2 Chilean Peso Yuan Renminbi 2
CNY
COP
Colombian 2 Peso Czech Koruna Danish Krone Euro 2
CZK
DKK
EUR
Appendices
GBP
Pound Sterling
HKD
HongKong 2 Dollar Hungarian 2 Forint Indonesian 0 Rupiah Iceland Krona Japanese Yen Kenyan Shilling South Korean Won Mexican Peso Malaysian Ringgit 2
HUF
IDR
ISK
JPY
KES
KRW
MXP
MYR
NOK
Norwegian 2 Krone New Zealand Dollar Philippine Peso 2
NZD
PHP
PLN
NewPolish 2 Zloty Portugese Escudo Swedish Krone 2
PTE
SEK
Appendices
SGD
Singapore Dollar Slovak Koruna ThaiBaht New Taiwan Dollar USDollars
SKK
THB TWD
2 2
USD VND
Vietnamese 2 NewDong South African Rand 2
ZAR
Appendices
Acquirer Response Codes

WorldPayusestheISO8583ResponseCodesintheorderStatusEventmessagestoindicate thestatusofthepayment:AUTHORISED,REFUSED,etc. ThePaymentServicemapstheseresponsestoasimplifiedlist.Belowyouwillfindall possibleresponsecodes,theirnumericvalueandthemappingtoastatus.
ISO 8583 Response Codes

code message value 0AUTHORISED 2REFERRED 4HOLDCARD 5REFUSED 8APPROVEAFTER IDENTIFICATION 13INVALIDAMOUNT 15INVALIDCARDISSUER 17ANNULATIONBYCLIENT 28ACCESSDENIED 29IMPOSSIBLEREFERENCE NUMBER 33CARDEXPIRED 34FRAUDSUSPICION 38SECURITYCODEEXPIRED 41LOSTCARD 43STOLENCARD,PICKUP status AUTHORISED REFUSED REFUSED REFUSED REFUSED
REFUSED REFUSED REFUSED REFUSED REFUSED
REFUSED REFUSED REFUSED REFUSED REFUSED
Appendices
51LIMITEXCEEDED 55INVALIDSECURITYCODE 56UNKNOWNCARD 57ILLEGALTRANSACTION 62RESTRICTEDCARD 63SECURITYRULES VIOLATED 75SECURITYCODEINVALID 76CARDBLOCKED 85REJECTEDBYCARD ISSUER 91CREDITCARDISSUER TEMPORARILYNOT REACHABLE 97SECURITYBREACH 3INVALIDACCEPTOR 12INVALIDTRANSACTION 14INVALIDACCOUNT 19REPEATOFLAST TRANSACTION 20ACQUIRERERROR 21REVERSALNOT PROCESSED,MISSING AUTHORISATION 24UPDATEOFFILE
REFUSED REFUSED REFUSED REFUSED REFUSED REFUSED
REFUSED REFUSED REFUSED
REFUSED
REFUSED ERROR ERROR ERROR ERROR
ERROR ERROR
ERROR
Appendices
IMPOSSIBLE 25REFERENCENUMBER CANNOTBEFOUND 26DUPLICATEREFERENCE NUMBER 27ERRORINREFERENCE NUMBERFIELD 30FORMATERROR 31UNKNOWNACQUIRER ACCOUNTCODE 40REQUESTEDFUNCTION NOTSUPPORTED 58TRANSACTIONNOT PERMITTED 64AMOUNTHIGHERTHAN PREVIOUSTRANSACTION AMOUNT 68TRANSACTIONTIMED OUT 80AMOUNTNOLONGER AVAILABLE, AUTHORISATIONEXPIRED 92CREDITCARDTYPENOT PROCESSEDBYACQUIRER 94DUPLICATEREQUEST ERROR ERROR
ERROR
ERROR
ERROR ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
ERROR
Appendices
ISO Country Codes

ThecountryCodeelementisusedinXMLorders/communications,itisanuppercase twoletterISO3166standardcountrycode,asshowninthefollowingexample:
... <address> <countryCode>GB</countryCode> </address>
ISOsourcereference: http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166code-lists/list-en1.html
ISO 3166 Two-Letter Country Codes

Country name <countryCode> or country parameter value
AFGHANISTAN
AF
LAND ISLANDS ALBANIA
AX
AL
ALGERIA
DZ
AMERICAN SAMOA ANDORRA
AS
AD
ANGOLA
AO
ANGUILLA
AI
ANTARCTICA
AQ
ANTIGUAAND BARBUDA
AG
Appendices
ARGENTINA
AR
ARMENIA
AM
ARUBA
AW
AUSTRALIA
AU
AUSTRIA
AT
AZERBAIJAN
AZ
BAHAMAS
BS
BAHRAIN
BH
BANGLADESH
BD
BARBADOS
BB
BELARUS
BY
BELGIUM
BE
BELIZE
BZ
BENIN
BJ
BERMUDA
BM
BHUTAN
BT
BOLIVIA
BO
BOSNIAAND HERZEGOVINA BOTSWANA
BA
BW
Appendices
BOUVETISLAND
BV
BRAZIL
BR
BRITISHINDIAN OCEAN TERRITORY BRUNEI DARUSSALAM BULGARIA
IO
BN
BG
BURKINAFASO
BF
BURUNDI
BI
CAMBODIA
KH
CAMEROON
CM
CANADA
CA
CAPEVERDE
CV
CAYMAN ISLANDS CENTRAL AFRICAN REPUBLIC CHAD
KY
CF
TD
CHILE
CL
CHINA
CN
CHRISTMAS ISLAND
CX
Appendices
COCOS (KEELING) ISLANDS COLOMBIA
CC
CO
COMOROS
KM
CONGO
CG
CONGO,THE DEMOCRATIC REPUBLICOF THE COOKISLANDS
CD
CK
COSTARICA
CR
CTEDIVOIRE
CI
CROATIA
HR
CUBA
CU
CYPRUS
CY
CZECH REPUBLIC DENMARK
CZ
DK
DJIBOUTI
DJ
DOMINICA
DM
DOMINICAN REPUBLIC ECUADOR
DO
EC
Appendices
EGYPT
EG
ELSALVADOR
SV
EQUATORIAL GUINEA ERITREA
GQ
ER
ESTONIA
EE
ETHIOPIA
ET
FALKLAND ISLANDS (MALVINAS) FAROEISLANDS
FK
FO
FIJI
FJ
FINLAND
FI
FRANCE
FR
FRENCH GUIANA FRENCH POLYNESIA FRENCH SOUTHERN TERRITORIES GABON
GF
PF
TF
GA
GAMBIA
GM
GEORGIA
GE
Appendices
GERMANY
DE
GHANA
GH
GIBRALTAR
GI
GREECE
GR
GREENLAND
GL
GRENADA
GD
GUADELOUPE
GP
GUAM
GU
GUATEMALA
GT
GUERNSEY
GG
GUINEA
GN
GUINEABISSAU
GW
GUYANA
GY
HAITI
HT
HEARDISLAND AND MCDONALD ISLANDS HOLYSEE (VATICANCITY STATE) HONDURAS
HM
VA
HN
Appendices
HONGKONG
HK
HUNGARY
HU
ICELAND
IS
INDIA
IN
INDONESIA
ID
IRAN,ISLAMIC REPUBLICOF IRAQ
IR
IQ
IRELAND
IE
ISRAEL
IL
ITALY
IT
JAMAICA
JM
JAPAN
JP
JERSEY
JE
JORDAN
JO
KAZAKHSTAN
KZ
KENYA
KE
KIRIBATI
KI
KOREA, DEMOCRATIC PEOPLES REPUBLICOF
KP
Appendices
KOREA, REPUBLICOF KUWAIT
KR
KW
KYRGYZSTAN
KG
LAOPEOPLES DEMOCRATIC REPUBLIC LATVIA
LA
LV
LEBANON
LB
LESOTHO
LS
LIBERIA
LR
LIBYANARAB JAMAHIRIYA LIECHTENSTEIN
LY
LI
LITHUANIA
LT
LUXEMBOURG
LU
MACAO
MO
MACEDONIA, THEFORMER YUGOSLAV REPUBLICOF MADAGASCAR
MK
MG
MALAWI
MW
MALAYSIA
MY
Appendices
MALDIVES
MV
MALI
ML
MALTA
MT
MARSHALL ISLANDS MARTINIQUE
MH
MQ
MAURITANIA
MR
MAURITIUS
MU
MAYOTTE
YT
MEXICO
MX
MICRONESIA, FEDERATED STATESOF MOLDOVA, REPUBLICOF MONACO
FM
MD
MC
MONGOLIA
MN
MONTSERRAT
MS
MOROCCO
MA
MOZAMBIQUE
MZ
MYANMAR
MM
NAMIBIA
NA
Appendices
NAURU
NR
NEPAL
NP
NETHERLANDS
NL
NETHERLANDS ANTILLES NEW CALEDONIA NEWZEALAND
AN
NC
NZ
NICARAGUA
NI
NIGER
NE
NIGERIA
NG
NIUE
NU
NORFOLK ISLAND NORTHERN MARIANA ISLANDS NORWAY
NF
MP
NO
OMAN
OM
PAKISTAN
PK
PALAU
PW
PALESTINIAN TERRITORY, OCCUPIED
PS
Appendices
PANAMA
PA
PAPUANEW GUINEA PARAGUAY
PG
PY
PERU
PE
PHILIPPINES
PH
PITCAIRN
PN
POLAND
PL
PORTUGAL
PT
PUERTORICO
PR
QATAR
QA
RUNION
RE
ROMANIA
RO
RUSSIAN FEDERATION RWANDA
RU
RW
SAINT BARTHELEMY SAINTHELENA
BL
SH
SAINTKITTS ANDNEVIS SAINTLUCIA
KN
LC
Appendices
SAINTPIERRE ANDMIQUELON SAINTVINCENT ANDTHE GRENADINES SAMOA
PM
VC
WS
SANMARINO
SM
SAOTOMEAND PRINCIPE SAUDIARABIA
ST
SA
SENEGAL
SN
SERBIA
CS
SEYCHELLES
SC
SIERRALEONE
SL
SINGAPORE
SG
SLOVAKIA
SK
SLOVENIA
SI
SOLOMON ISLANDS SOMALIA
SB
SO
SOUTHAFRICA
ZA
SOUTH GEORGIAAND THESOUTH SANDWICH
GS
Appendices
ISLANDS SPAIN ES
SRILANKA
LK
SUDAN
SD
SURINAME
SR
SVALBARDAND JANMAYEN SWAZILAND
SJ
SZ
SWEDEN
SE
SWITZERLAND
CH
SYRIANARAB REPUBLIC TAIWAN, PROVINCEOF CHINA TAJIKISTAN
SY
TW
TJ
TANZANIA, UNITED REPUBLICOF THAILAND
TZ
TH
TIMORLESTE
TL
TOGO
TG
TOKELAU
TK
Appendices
TONGA
TO
TRINIDADAND TOBAGO TUNISIA
TT
TN
TURKEY
TR
TURKMENISTAN
TM
TURKSAND CAICOS ISLANDS TUVALU
TC
TV
UGANDA
UG
UKRAINE
UA
UNITEDARAB EMIRATES UNITED KINGDOM UNITEDSTATES
AE
GB
US
UNITEDSTATES MINOR OUTLYING ISLANDS URUGUAY
UM
UY
UZBEKISTAN
UZ
VANUATU
VU
Appendices
VaticanCityState refertoHOLY SEE VENEZUELA
VA
VE
VIETNAM
VN
VIRGIN ISLANDS, BRITISH VIRGIN ISLANDS,U.S. WALLISAND FUTUNA WESTERN SAHARA YEMEN
VG
VI
WF
EH
YE
ZAMBIA
ZM
ZIMBABWE
ZW
Appendices
CVC/CVV Checks and Responses

YoucancarryoutaSecurityCodeVerification(CVC/CVV)checkonanindividualdirect order.CVC/CVVisa3or4digitvalueprintedonthecard(forexample,onasignature strip),butnotencodedonthemagneticstripe,andenablesthesecuritycodeenteredby theshoppertobecomparedagainstthecardissuersrecordsduringthepaymentprocess. OnlyorderscontainingavalidCVC/CVVcodefragmentwillbechecked,asdisplayedin theexamplebelow.AnorderwithouttheCVCcodefragmentwillnotbechecked.
<cardHolderName>J. Shopper</cardHolderName> <cvc>123</cvc> <cardAddress> ...
Testing
ThefollowingCVC/CVVscenarioscanbetestedusingthecodeslistedbelow. CVC/CVV code Leftblank simulated situation NOTSUPPLIED BYSHOPPER NOTSENTTO ACQUIRER NORESPONSE FROM ACQUIRER NOTCHECKED BYACQUIRER FAILED APPROVED numeric response 1
111
222
333
444 555
5 6
Appendices
Testing Transactions
Anumberofdifferentcasescanbetestedbyenteringthefollowingvaluesasthe card/accountholdername(<cardHolderName>)intheorder: REFUSEDwillsimulatearefusedpayment REFERREDwillsimulatearefusalwiththerefusalreasonreferred FRAUDwillsimulatearefusalwiththerefusalreasonfraudsuspicion ERRORwillsimulateapaymentthatendsinerror.
Allothercard/accountholdernameswillsimulateanauthorisedpayment. Fortestpurposeswehaveprovidedasetoftestcreditanddebitcardnumbers,theseare listedbelowintheTestCardNumberssection. CapturesandrefundscanbesimulatedthroughtheMerchantAdministrationInterface. UsetheCaptureorRefundbuttoninthePaymentandOrderDetails page.Alternatively,youcansendanXMLcaptureorrefundordermodificationtothe Testenvironment.
Test Card Numbers

ThefollowingcardnumberscanbeusedwhenyoumaketesttransactionsinTest environmentsonlydonotusetheminlive,Productionenvironments: card type Mastercard VisaDelta UK VisaDelta NonUK Visa Visa American Express Diners JCB Visa Electron (UKonly) card number 5100080000000000 4406080400000000 number length 16 16 issue no length 0 0
4462030000000000
16
4911830000000 4917610000000000 370000200000000
13 16 15
0 0 0
36700102000000 3528000700000000 4917300800000000
14 16 16
0 0 0
Appendices
Solo Solo Discover Card Laser Maestro Visa Purchasing
6334580500000000 633473060000000000 6011000400000000
16 18 16
0 1 0
630495060000000000 6759649826438453 4484070000000000
18 16 16
0 0 0
NotethatVisaPurchasingtransactionsaretreatedasVisacredit cardtransactions.
German ELV
TotestGermanELVpaymentsintheTestenvironmentacorrectlyformattedaccount number(Kontonummer)andvalidbankcode(Bankleitzahl)shouldbeused,forexample: Accountnumber:12345678 Bankcode:10000000 Bankname:Bundesbank Bankresidence:Berlin card type ELV ELV ELV PleasenotethatELVmustbeactivatedintheProductionenvironmentformerchantswho wouldliketotestELVtransactions. bank code 20030000 43050001 30070024 account number 92441196 122108525 5929120
Appendices
XML Error Codes

ThelistofXMLerrorcodesisasfollows: 1. 2. 3. 4. 5. 6. 7. Internalerror,ageneralerror Parseerror,invalidXML Invalidnumberoftransactionsinbatch Securityerror Invalidrequest Invalidcontent,occurswhenXMLisvalidbutcontentofXMLisnot Paymentdetailsintheorderelementareincorrect
ForfulldetailsofourDTD,referto:http://dtd.worldpay.com/paymentService_v1.dtd
Examples
Thefollowingaresomeexamplesfortheseerrorcodes.
Error Code 2
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.3" merchantCode="MYCO"> <reply> <error code="2"><![CDATA[Invalid bankAccount details : Invalid payment details : Account and bankcode combination is incorrect]]></error> </reply> </paymentService>
Error Code 4
<?xml version="1.0"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService merchantCode="MYCO" version="1.3"> <reply> <error code="4"><![CDATA[IP check failed. Access denied.]]></error> </reply> </paymentService>
Error Code 5
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.3" merchantCode="MYCO"> <reply> <orderStatus orderCode="12234"> <error code="5"><![CDATA[Cannot book payment to CANCELLED if paymentstatus is not AUTHORISED but : REFUSED]]></error> </orderStatus>
Appendices
</reply> </paymentService>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN""http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.3" merchantCode="MYCO"> <reply> <error code="5"><![CDATA[Duplicate Order]]></error> </reply> </paymentService>
<?xml version="1.0"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN""http://dtd.worldpay.com/paymentService_v1.dtd"><paymentService merchantCode="MYCO" version="1.4"> <reply> <orderStatus orderCode="11223"> <error code="5"><![CDATA[Requested capture amount (EUR 125,50) exceeds the authorised balance for this payment (EUR 115,50)]]></error> </orderStatus> </reply> </paymentService>
Error Code 7
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"><paymentService version="1.3" merchantCode="MYCO"> <reply> <orderStatus orderCode="1112"> <error code="7"><![CDATA[Invalid payment details : Expiry date = 012002]]></error> </orderStatus> </reply> </paymentService>
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE paymentService PUBLIC "-//WorldPay//DTD WorldPay PaymentService v1//EN" "http://dtd.worldpay.com/paymentService_v1.dtd"> <paymentService version="1.4" merchantCode="MYCO"> <reply> <orderStatus orderCode="11223"> <error code="7"><![CDATA[Gateway error]]></error> </orderStatus> </reply> </paymentService>

DXML

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

DXML

Uploaded by

Copyright:

Available Formats

Submitting Transactions in the Direct Model

About this Guide

About This Guide

What is XML Direct?

Payment Card Industry Data Security Standard (PCI DSS)

3-D Secure Authentication

Before You Start

Before You Start

modifyandqueryorderdata:administertransactionsremotely,thatis,fromoutside (andinadditionto)WorldPaysMerchantAdministrationInterface(MAI).You haveachoiceofhowyouworkremotelyusingoneofthefollowing:

Before You Start

AnychangestosettingsmustbemadeintheProduction environmentintheMerchantAdministrationInterface.Thesettings canthenbecopiedovertotheTestenvironment.

Connect Using Login Name and XML Password

Before You Start

Error Messages, Invalid XML

Use Valid Syntax

Reference the DTD

Use Declared Elements Only

Before You Start

Structure of an XML Direct Order

Structure of an XML Direct Order

XML and Document Type Declaration

Merchant and Service-specific Information

Structure of an XML Direct Order

<paymentService version="1.4" merchantCode="WPACC11112222"> <submit> ... </submit> </paymentService>

Order Description and Amount

aninstallationidattribute.ThisshouldbeyourXMLInvisibleinstallationidthatyou havereceivedfromWorldPay. Anorderwithapreviouslyusedordercodecannotbeprocessed correctlyandyouarelikelytoreceiveerrormessagesandencounter problemswithreporting.

Structure of an XML Direct Order

<orderContent> <![CDATA[content here]]> </orderContent>

Payment Details and Session Information

Structure of an XML Direct Order

NotethatthecvcelementcontainstheCardVerificationCode.For detailspleaserefertotheappendixCVC/CVVChecksAndResponses. Alsonotethatthenumericparts(ifthereareany)ofthestreetelement areusedintheAVScheck.Thenonnumericpartsareignored.

FortheSolo(SOLO_GBSSL)paymentmethodeithertheissuenumberorthestartdate mustbeincludedinthepaymentDetails,dependingontheissuerpolicy.Pleasenote thattheissuenumbercanbeuptothreedigits,includingpossiblezerosinfront.This exampleshowspaymentDetails forSOLO_GBSSL:

Structure of an XML Direct Order

XML Direct Order Example

Structure of an XML Direct Order

TheCDATAsectionintheorderContentelementcontainsacompleteinvoiceinHTML. Theimagebelowshowswhatthisordercontentlookslikewhenviewedwithaweb browser.

Structure of an XML Direct Order

Figure 1: Example HTML order content as viewed with a browser.

Response from the Payment Service

Response from the Payment Service

Reply to an XML Direct Order

Response from the Payment Service

Posting an XML Order

Posting an XML Order

Setting-up the Connection

Submitting a 3-D Secure Order

Submitting a 3-D Secure Order

The Process Flow

Submitting a 3-D Secure Order

Submitting a 3-D Secure Order

XML Messages and HTML Redirect

Creating an Initial Order Message (arrow 2)

Submitting a 3-D Secure Order

Initial Order Reply Message (arrow 3)

Redirect the Shopper to Issuer (arrow 4)

Submitting a 3-D Secure Order

WhentheshopperhasenabledJavascriptinthebrowser,theshopperwillautomatically beforwardedtotheIssuerssite.IfJavascripthasbeendisabled,theshoppermustpress theSubmitbuttoninordertocontinue.

Second Order Message (arrow 6)

Submitting a 3-D Secure Order

</shopper> <echoData>somedata</echoData> </order> </submit> </paymentService>

Failed Authentication (arrow 7)

3D-Secure Referral Message

Submitting a 3-D Secure Order