Sitecre E-Cmmerce Fundamental Editin 1.1 Payment Methd Reference Guide Rev: 2011-05-19 Sitecre E-Cmmerce Fundamental Editin 1.1 Payment Methd Reference Guide The payment methds supprted by the Sitecre E -Cmmerce Fundamental Editin Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. The cntents f this dcument are the prperty f Sitecre. Cpyright 2001-2011 Sitecre. All rights reserved.
Sitecre E-Cmmerce Fundamental Editin 1.1 Table f Cntents Intrductin... 3 Integratin... 5 Hsted Payment Frms... 5 Sitecre E-Cmmerce Supprted Cntracts fr Payment Prviders Integratin... 6 Payment Prviders API... 7 Supprted Payment Prviders... 9 Payment Methd Cnfiguratin... 9 Installing a SEFE Payment Prvider... 12 Ticket Reservatin... 13 Implementing a New Payment Prvider... 15 Payment Prvider Changes... 19 Changes t API... 19 New Interfaces and Base Classes... 19 Obslete Cntracts... 20 Changes t the Unity.cnfig File... 21 Changes t Cnfiguratin Files... 21 Changes t CMS Cntent... 21 Changes t Functinality Affecting System Behavir... 21 New Features... 22 Glssary... 23 Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 2 f 23
Payment Methd Reference Guide Intrductin Online payment methds allw payments and mney transfers t be made ver the Internet. Payment prtals are an electrnic alternative t traditinal paper methds f payment such as checks and mney rders which have been invlved in many cases f litigatin cncerning fraud. The Sitecre E-Cmmerce slutin can be integrated with payment prviders. They ffer merchants nline services that accept electrnic payments by a variety f payment methds including credit cards, bank-based payments, such as direct debit, bank transfer, and real-time bank transfer based n nline banking. In the Example Pages package, the Payment page is the secnd page in the checkut prcess. When yu click Next n the Custmer Details page, the Payment page is displayed. The Payment page is where yu decide hw t pay fr the prducts yu are buying. After yu click the Cnfirm Payment buttn, yu are redirected t the web page f the payment prvider yu selected. On the Payment page yu can submit yur credit card data after which the payment is either apprved r cancelled. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 3 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 The payment methds that are displayed n this page are stred in the Webshp Business Settings flder. Fr mre infrmatin abut cnfiguring the Webshp Business Settings flder, see the E-Cmmerce Installatin and Cnfiguratin Guide. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 4 f 23
Payment Methd Reference Guide Integratin The Sitecre E-Cmmerce payment prvider mdel makes use f invice payment frms that are hsted by payments. Hsted Payment Frms Payment prviders ffer a hsted payment prcessing slutin that handles all the steps in prcessing a transactin, including: Cllectin f custmer payment infrmatin thrugh a secure, hsted frm. Generatin f a receipt fr the custmer. Secure transmissin t the payment prcessing netwrks. Mvement f prceeds t the merchant s bank accunt. Secure strage f cardhlder infrmatin. The security f a payment transactin is assured thrugh the use f a unique digital signature r fingerprint that is sent with each transactin. This fingerprint is used by payment prviders t authenticate bth the merchant and the transactin. Merchants are nt required t cllect, transmit r stre sensitive cardhlder infrmatin t prcess transactins. Additinally, the hsted payment frms ffered by the payment prviders d nt require merchants t purchase and install a Secure Sckets Layer (SSL) digital certificate. This remves the cmplexity f securely handling and string cardhlder infrmatin, and makes it easier t cmply with the Payment Card Industry (PCI) Data Security Standard. In a typical webshp scenari, as used in the example pages package, the wrkflw f payment gateway s hsted payment frms in Sitecre E-Cmmerce is: 1. Custmer prceeds t the checkut f their shpping cart. 2. On the Payment page f the checkut, the custmer selects a payment prvider frm the list f payment prviders cnfigured fr the webshp (fr example, Authrize.NET, Amazn). 3. When the custmer cmpletes the checkut prcess, their rder data are transferred, using a secure prtcl, t the selected payment prvider by being redirected t the payment gateway s hsted payment frm pages. 4. On the payment gateway the custmer enters their credentials, credit card number, and submits the frm fr prcessing. This is dne externally frm the web-shp. Sitecre E- Cmmerce payment prvider mdel supprts several types f payments transactins: a. Authrize and capture. b. Authrize nly and capture r cancel at a later pint. 5. The payment gateway transfers the custmer back t the Webshp Return page f the checkut; If there is an errr, the example pages implementatin displays a standard errr message enabling the custmer t try again r t select anther payment methd. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 5 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 If the custmer cancels the payment, the example pages implementatin shws a cancel errr message that lets the custmer t try it again. If the transactin is cmpleted successfully, the rder is created and the rder cnfirmatin is displayed. Checkut Payment Page The user selects the payment methd and cnfirms the amunt by Cnfirm payment Payment transfer Errr Cancel Payment Gateway Hsted Frm User enters the credit card infrmatin and the payment is authrized (r authrized and captured). Transfer back Checkut Return Page Transactin is validated and prcessed. Create Order Order Cnfirmatin Displays the rder cnfirmatin. Different data transfer methds fr payment gateway integratins are supprted: 1. GET methd: HTTP GET parameters transfer the data and initiate the payment. 2. Web service call: The payment prvider prvides a web reference fr activating remte methds and uses web service calls t transfer data 3. POST methd: The payment prvider prvides a URL that accepts frm fields with payment data and then transfers them with the HTTP POST methd. Sitecre E-Cmmerce Supprted Cntracts fr Payment Prviders Integratin By default Sitecre E-Cmmerce includes several payment prviders that nly require a minimal amunt f installatin and cnfiguratin. The payment prviders that are implemented in Sitecre E-Cmmerce have the fllwing features: If yu installed the SEFE example pages package, nline payment is integrated int the checkut prcess in the Payment page, and in the Order Cnfirmatin page. This integratin als includes errr handling. The mdule is tested with the fllwing payment prviders: PayPal Amazn Payments Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 6 f 23
Payment Methd Reference Guide Authrize.NET PayEx DIBS BBS QuickPay.dk Epay.dk If a payment prvider is installed, yu can implement a payment methd by defining the custmer s username, passwrd and the related settings. Supprts the use f tw r mre payment prviders at the same time. Can use bth test and prductin accunts by cnfiguring the URL f the payment gateway in the cnfiguratin files r the payment items. Payment Prviders API The class hierarchy and API f the payment prviders have been changed frm the previus release. The main innvatins are: 1. The IPaymentPrvider<T>, IOnlinePaymentPrvider<T>, IOfflinePaymentPrvider<T>, IReservableOnlinePaymentPrvider<T, TRT> interfaces and PaymentPrviderBase<T>, OnlinePaymentPrviderBase<T> classes have been marked as bslete. The fllwing classes and interfaces are at the tp f the hierarchy: All the specific payment prviders like EPayPaymentPrvider, QuickPayPaymentPrvider are inherited frm the OnlinePaymentPrvider and implement the IReservable interface. 2. OnlinePaymentPrvider defines hw nline payments are prcessed. It supprts bth ne-stage transactins, fr example a sale, and tw-stage transactins authrizatin and the subsequent capturing. The Invke (PaymentSystem paymentsystem, PaymentArgs paymentargs) methd generates and transfers data t the payment prvider fr authrizatin r sale transactin. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 7 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 The PrcessCallBack (PaymentSystem paymentsystem, PaymentArgs paymentargs) methd prcesses the call frm the payment gateway t validate payment fr the transactin and if needed t create a reservatin ticket. 3. IReservable prcesses nline payments with separate authrizatin and capturing actins (pstpned) ; The Capture (PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket, decimal amunt) methd generates and transfers data t the payment prvider t capture the transactin and reserve the mney. The CancelReservatin(PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket) methd cancels the reservatin f the ticket. Nte The default rder states Capture and Cancel cntain business lgic s that when the state is changed, frm the rder state buttns within the Cntent Editr, the rder is either captured in full r cancelled altgether. Partial capturing is supprted by the API but nt implemented in the current state lgic and UI. The SEFE cre package als includes the fllwing additinal classes fr the strage and transmissin f payment related infrmatin: ReservatinTicket cntains infrmatin abut the reserved payment. AuthrizatinCde is a secure cde. Each prvider uses different lgic t create and prcess the payment. TransactinNumber is the number f the authrizatin transactin. InviceNumber is the number f the rder (invice). Amunt is the amunt f mney that is reserved. PaymentArgs is a unified list f the data that is required by the payment prviders. PaymentUrls: SuccessPageUrl is the URL f the lcal page that is called if the payment transactin is successful. FailurePageUrl is the URL f the lcal page that is called if the payment transactin fails. CancelPageUrl is the URL t the lcal page that is called if the payment transactin is cancelled by the custmer. ReturnPageUrl is the URL f the default lcal return page. Descriptin is a shrt explanatin f the purchase. This infrmatin is supplied by the webshp. Shpping cart cntains all the infrmatin abut the purchase, such as prices, VAT, gds and the like. This infrmatin is supplied by the webshp. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 8 f 23
Payment Methd Reference Guide Supprted Payment Prviders The fllwing payment prviders are supprted in Sitecre E-Cmmerce: Vendr PayPal Amazn: Flexible Payments Service. Authrize. NET: Server Integratin Methd, Advanced Integratin Methd. Data Transfer Type POST, Web Service GET WebService POST, WebService Links https://cms.paypal.cm/us/cgi-bin/?cmd=_rendercntent&cntent_id=develper/library_dcumentatin http://aws.amazn.cm/fps/ https://payments.amazn.cm/sdui/sdui/business?sn=d evfps/fps http://aws.amazn.cm/fps/faqs/#a3 http://develper.authrize.net/guides/aim/ http://develper.authrize.net/guides/sim/ BBS Web Service http://www.bbs.dk/ https://epayment-test.bbs.n/terminal/default.aspx https://epayment.bbs.n/terminal/default.aspx DIBS epay PayEx POST, Web Service POST, Web Service Web Service, GET http://tech.dibs.dk/dibs-api/dibs-api/ http://www.epay.dk/main/ http://pim.payex.cm/ (lgin: dwnlad, passwrd: laddwn) QuickPay POST http://dc.quickpay.dk/index.html Payment Methd Cnfiguratin T cnfigure a payment prvider and ensure that it appears n the Checkut Payment page f the Sample pages), yu must create a new Payment Methd item in the Webshp Business Settings in Sitecre. Nte Yu can install the SEFE cre package withut the example pages and still be able t use the payment prviders and the API. Hwever, yu must perfrm the necessary cnfiguratin t ensure that yu can access the payment prviders frm the API. The Payment Methds item is lcated in Ecmmerce/Business Catalg/Payment Methds. The fllwing fields need t be filled in fr each payment methd: Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 9 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 Field Name Title Shrt Descriptin Icn Name Cde Username Passwrd PaymentPrviderUrl PaymentPrviderSecndaryUrl Settings Descriptin The name displayed n the Payment page near the ptin buttn. The text used t describe each payment methd in the ptin-buttn list. The icn used t illustrate the payment prvider. An ptinal field used by external systems when imprting the item. Used t give an understandable descriptin t the Cde field. The unique identifier f the payment prvider methd. This is used thrughut the system and is reflected n the rder. This must be unique fr all the payment methd items in yur business catalg. The name that identifies the merchant ID accunt fr the nline prvider. This is btained frm the prvider. The passwrd/ tken-id /security-key supplied by the payment prvider. This is ften used t encrypt data befre sending it t the payment prvider. The URL used t send data t the prvider. This URL is generally different in the test and the prductin envirnments. An ptinal field that is used if the payment integratin needs t use different URLs fr varius parts f the integratin. This can be used if the authenticatin payment frm is lcated n ne server and web service calls are pinting t anther. A field that is used t enable the shp wner t change the settings that are used t cnfigure the behavir f the client. This data is either sent t the payment prvider at the beginning f the payment transactin r can serve as directives fr ur engine. The values are entered as XML. The frmat f these settings are: <settings id= settingname >sme value</settings> Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 10 f 23
Payment Methd Reference Guide The fllwing picture illustrates a payment methd in Sitecre and an example f its use. Nrmally, yu d nt have t create these items. They are supplied with the Sitecre installatin packages. Nte The default cnfiguratin withut the lgin credentials shuld be available under /sitecre/system/mdules/ecmmerce/payment Optins after yu install ne f the supplied prviders. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 11 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 Installing a SEFE Payment Prvider Dwnlad the apprpriate package and install it using the Develpment Tls, Installatin Wizard. During the installatin yu are asked t add registratin infrmatin t the App_Cnfig/Include/Unity.cnfig file. Fr example, if yu are installing EPay, the fllwing changes are required: 1. Register the payment prvider alias: <alias alias="epaypaymentprvider" type="sitecre.ecmmerce.payments.epay.epaypaymentprvider, Sitecre.Ecmmerce.Payments.EPay" /> 2. Register the payment prvider in the cntainer sectin f the Unity.cnfig file: <register type="paymentprvider" mapt="epaypaymentprvider" name="epay" /> After that yur current payment prvider is presented as the master://sitecre/system/mdules/ecmmerce/payment Optins/<Prvider> item. Cpy this item t the Payment Optins flder in the cntent tree, where yur webshp is lcated. The payment prviders must be cnfigured fr each webshp. This allws different webshps t ffer different payment ptins t the custmer. PayPal Register in the PayPal sandbx, and then create a test accunt in the sandbx n the fllwing page: https://develper.paypal.cm/ After yu receive the username and passwrd, enter this infrmatin in the PayPal frm fields. Yu can als manage yur test accunts using the sandbx. T manage a test accunt, chse the accunt yu want and click Enter test accunt. Yu can als use the PayPal API t btain the credentials that yu need t perfrm a transactin. Enter the fllwing data in the Settings parameter: <setting id="apiusername">parten_1299487089_biz_api1.mail.ru</setting> <setting id="apipasswrd">sct4s4w5q4spxb3h</setting> <setting id="apisignature">azickvqdo37mzkhbknxvi9plpm5rayjy72ryeecw2pbksklw4jwvyqeg</setting> <setting id="envirnment">sandbx</setting> When yu have finished testing, register a live accunt. Amazn T cnfigure this payment prvider, create a new Flexible Payments Service (FPS) accunt. Fr mre infrmatin abut hw t cnfigure the payment prvider by creating a new FPS accunt, see http://aws.amazn.c m/fps/ After yu are registered, yu receive the lgin credentials t use the service. In the Amazn item, enter the apprpriate values in the Username and Passwrd fields. Authrize.Net Create a test accunt n the fllwing page: https://develper.authrize.net/testaccunt Fill in the Username (merchant ID) and Passwrd fields. T manage yur accunt and the transactins, use the fllwing URL: https://test.authrize.net/ BBS Create a new test accunt n the fllwing page. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 12 f 23
Payment Methd Reference Guide https://epayment-test.bbs.n/ The BBS payment prvider cntains a cnfiguratin file. By default, we cnfigure ur payment prvider t use the test BBS. Yu can switch t prductin by setting the fllwing cnfiguratin URL: DIBS <applicatinsettings> <Sitecre.Ecmmerce.Payments.Bbs.Prperties.Settings> <setting name="sitecre_ecmmerce_payments_bbs" serializeas="string"> <value>https://epayment.bbs.n/netaxept.svc</value> </setting> </Sitecre.Ecmmerce.Payments.Bbs.Prperties.Settings> </applicatinsettings> Create a new test accunt. Yu receive yur username, passwrd and tw secret keys t verify yur requests. In the Setting field, enter key1 and key2 settings. T manage yur accunt, use the fllwing URL: https://payment.architrade.cm/lgin/lgin.actin?pwc=1 (lgin as admin) EPay Cntact the payment prvider t btain the username r merchant ID and passwrd t use the service. T manage yur accunt, use the fllwing URL: https://ssl.ditnlinebetalingssystem.dk/admin/ PayEx Create a new test accunt. Enter the username r merchant ID and passwrd that yu receive frm the payment prvider. T manage yur accunt, use the fllwing URL: http://secure.payex.cm/admin/ When yu finished testing, yu can make the payment prvider use the live service endpints within the cnfiguratin file: QuickPay <applicatinsettings> <Sitecre.Ecmmerce.Payments.PayEx.Prperties.Settings> <setting name="sitecre_ecmmerce_payments_payex_payextest_pxorder" serializeas="string"> <value>https://external.payex.cm/pxrder/pxrder.asmx</value> </setting> </Sitecre.Ecmmerce.Payments.PayEx.Prperties.Settings> </applicatinsettings> Create a new test accunt. Enter the username r merchant ID and passwrd that yu receive frm the payment prvider. T manage yur accunt, use the fllwing URL: https://manager.quickpay.net/ Ticket Reservatin Sme new individual packages with payment prviders are supplied with the Sitecre E-Cmmerce slutin. The new individual packages can wrk with r withut ticket reservatin. The IReservable interface has been implemented fr all these prviders, and they are cnfigured t wrk in reservable mde by default. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 13 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 Reservable means that when the custmer cmpletes a payment and is redirected back t the Return Page, nly authrizatin is perfrmed. The mney is nt drawn frm the custmer s accunt befre an explicit capture request t the payment prvider is prcessed. The initial respnse frm the payment prvider cntains the unique ticket infrmatin indicating that the rder amunt has been reserved. The reservatin ticket is stred alng with the Order, and must be used t capture the mney later. T capture the mney, additinal actins must be perfrmed. Yu can capture the mney by: Using the prvider administratin interface. Using the SEFE API. Managing the rder. Basic rder management is implemented in SEFE 1.1. When yu capture r cancel an rder in any f the rder states the business lgic calls the payment prvider and either uses the reservatin ticket t capture the mney r cancels the reservatin ticket. In the current SEFE versin, yu can cnfigure the payment prvider t wrk in reservable mde using the prvider settings fr each prvider: Amazn A) <setting id="transactintype">authorization</setting> - reservable mde. B) <setting id="transactintype">sale</setting> - ne-stage transactin mde. Authrize.Net BBS DIBS EPay A) <setting id="x_type">auth_only</setting> - reservable mde. B) <setting id="transactintype">auth_capture</setting> - ne-stage transactin mde. A) <setting id="peratin">auth</setting> - reservable mde. B) <setting id="peratin">sale</setting> - ne-stage transactin mde. A) <setting id="preauth">false</setting> <setting id="capturenw">yes</setting> - reservable mde. B) <setting id="preauth">true</setting> - ne-stage transactin mde. A) <setting id="instantcapture">0</setting> - reservable mde. B) <setting id="instantcapture">1</setting> - ne-stage transactin mde. PayEx A) <setting id="purchaseoperatin">authorization</setting> - reservable mde. B) <setting id="purchaseoperatin">sale</setting> - ne-stage transactin mde. QuickPay A) <setting id="autcapture">0</setting> - reservable mde. B) <setting id="autcapture">1</setting> - ne-stage transactin mde. PayPal A) <setting id="paymentactin">authorization</setting> - reservable mde. B) <setting id="paymentactin">sale</setting> - ne-stage transactin mde. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 14 f 23
Payment Methd Reference Guide Implementing a New Payment Prvider In a grwing e-cmmerce market and with emergence f new nline payment services, Sitecre develpers may need t implement new payment prviders. SEFE allws develpers t implement a prvider that adheres t the cntracts in a simple way. Use the fllwing apprach t implement a custm SEFE payment prvider: 1. Create a new.net class library. 2. Add references t the Micrsft.Practices.Unity, Sitecre.Ecmmerce.DmainMdel and the Sitecre.Ecmmerce.Kernel assemblies. 3. Create a new class and make it inherit frm Sitecre.Ecmmerce.Payments.OnlinePaymentPrvider. 4. Make the class implement the Sitecre.Ecmmerce.DmainMdel.Payments.IReservable interface: namespace <Any_Namespace> using Sitecre.Ecmmerce.DmainMdel.Payments; using Sitecre.Ecmmerce.Payments /// <summary> /// PayPal nline payment prvider /// </summary> public class <SmePrvider>PaymentPrvider : OnlinePaymentPrvider, IReservable Override the Invke(PaymentSystem, PaymentArgs) and the PrcessCallback(PaymentSystem, PaymentArgs) methds. Use the Invke methd t prepare the data that must be sent t the nline payment prvider and redirect t the service page. Sme payment services accept the POST requests and thers prvide web methds t perfrm payment transactins. In the fllwing, we use ur PayPal prvider as an example t shw yu hw t implement a custm payment prvider. The PayPal implementatin uses the POST methd t cmmunicate with the service: public verride vid Invke(PaymentSystem paymentsystem, PaymentArgs paymentargs) // Fill the variables with the apprpriate data. // Yu can find the necessary parameters within the prvider // nline dcumentatin. NameValueCllectin requestdata = new NameValueCllectin "cmd", Cmmand, "paymentactin", paymentactin, "business", merchant, "item_name", descriptin, "item_number", rdernumber, "amunt", amunt, "currency_cde", currency, "return", returnurl, Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 15 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 "cancel_return", cancelurl, "ntify_url", returnurl, ; this.pstdata(paymentsystem.paymenturl, requestdata); 5. The PrcessCallBack() methd must be called after redirectin frm the prviders hsted frm. Check the incming parameters in the request r use web methds t perfrm additinal interactin. Depending n the respnse, set the apprpriate PaymentStatus fr the Sitecre payment prvider and handle it in the necessary way: r r Create the rder and display the receipt. Redirect t the PaymentCancel page. Redirect t the PaymentErrr page. Here is the example frm the PayPal client: public verride vid PrcessCallback(PaymentSystem paymentsystem, PaymentArgs paymentargs) this.paymentstatus = PaymentStatus.Failure; HttpRequest request = HttpCntext.Current.Request; string paymentstatus = request.frm["payment_status"].tupper(); string transactinnumber = request.frm["txn_id"]; string rderid = request.frm["item_number"]; string currency = request.frm["mc_currency"]; string amunt = request.frm["mc_grss"]; if (paymentstatus!= "FAILED" && paymentstatus!= "DENIED") this.paymentstatus = PaymentStatus.Succeeded; // Save the data after successful transactin, in HTTP Sessin by default default */ if (/*Cnditin t check that yur prvider wrk in reservable mde*/) ReservatinTicket reservatinticket = new ReservatinTicket InviceNumber = rderid, Amunt = TypeUtil.TryParse(amunt, decimal.zer), AuthrizatinCde = PaymentCnstants.EmptyAuthrizatinCde, TransactinNumber = transactinnumber ; /* Save the reservatin ticket after successful transactin, in HTTP Sessin by else this.paymentstatus = PaymentStatus.Canceled; if (this.paymentstatus!= PaymentStatus.Succeeded) /* Save the infrmatin that the transactin was cancelled r failed, in HTTP Sessin by default */ 6. T make yur payment prvider wrk in reservable mde, yu shuld als implement the fllwing methds defined by the IReservable interface: Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 16 f 23
Payment Methd Reference Guide Capture(PaymentSystem, PaymentArgs, ReservatinTicket, decimal amunt), Cancel(PaymentSystem, PaymentArgs, ReservatinTicket). The first methd interacts with the payment service and captures the amunt frm the reserved ticket. The secnd methd cancels the reservatin. Nte The Capture methd accepts a parameter named Amunt, which enables partial capture. A part f the reservatin ticket stred in SEFE is the riginal reserved amunt. A full capture will withdraw the full authrized/reserved amunt frm the custmer s accunt. Smetimes nly a part f an rder can be shipped initially r the rder has been mdified t cntain less prducts. In these cases a partial capture withdraws nly the specified amunt and nt the full amunt. It s nt pssible t withdraw mre mney than has been riginally authrized/reserved. If the amunt in the rder has changed and exceeds the riginal amunt a new reservatin must be perfrmed. Here is an example that uses the PayPal implementatin: /// <summary> /// Captures the payment /// </summary> /// <param name="paymentsystem">the payment system.</param> /// <param name="paymentargs">the payment args.</param> /// <param name="reservatinticket">the reservatin ticket.</param> /// <param name="amunt">the amunt.</param> public vid Capture(PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket, decimal amunt) var cnfiguratin = new PaymentSettingsReader(paymentSystem); var credentials = new CustmSecurityHeaderType Credentials = new UserIdPasswrdType Username = cnfiguratin.getsetting("apiusername"), Passwrd = cnfiguratin.getsetting("apipasswrd"), Signature = cnfiguratin.getsetting("apisignature"), ; using (var client = new PayPalAPIAASapBinding()) client.requestercredentials = credentials; DCaptureReq request = new DCaptureReq DCaptureRequest = new DCaptureRequestType AuthrizatinID = reservatinticket.transactinnumber, Amunt = new BasicAmuntType currencyid = CurrencyCdeType.USD, Value = amunt.tstring(), Versin = cnfiguratin.getsetting("requestversin") ; var respnse = client.dcapture(request); string captureresult = respnse.ack.tstring(); ITransactinData transactindataprvider = Cntext.Entity.Reslve<ITransactinData>(); transactindataprvider.savepersistentvalue(reservatinticket.invicenumber, captureresult == "Success"? PaymentCnstants.CaptureSuccess : respnse.errrs.aggregate("uncaptured:", (current, errr) => string.frmat("01;", current, errr.shrtmessage))); /// <summary> /// Cancels the payment reservatin /// </summary> /// <param name="paymentsystem">the payment system.</param> /// <param name="paymentargs">the payment args.</param> /// <param name="reservatinticket">the reservatin ticket.</param> Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 17 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 public vid CancelReservatin(PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket) var cnfiguratin = new PaymentSettingsReader(paymentSystem); var credentials = new CustmSecurityHeaderType Credentials = new UserIdPasswrdType Username = cnfiguratin.getsetting("apiusername"), Passwrd = cnfiguratin.getsetting("apipasswrd"), Signature = cnfiguratin.getsetting("apisignature"), ; using (var client = new PayPalAPIAASapBinding()) client.requestercredentials = credentials; DVidReq request = new DVidReq DVidRequest = new DVidRequestType AuthrizatinID = reservatinticket.transactinnumber, Versin = cnfiguratin.getsetting("requestversin") ; var respnse = client.dvid(request); string cancelresult = respnse.ack.tstring(); ITransactinData transactindataprvider = Cntext.Entity.Reslve<ITransactinData>(); transactindataprvider.savepersistentvalue(reservatinticket.invicenumber, cancelresult == "Success"? PaymentCnstants.CancelSuccess : respnse.errrs.aggregate("uncanceled:", (current, errr) => string.frmat("01;", current, errr.shrtmessage))); 7. Cmpile yur assembly and place it in the /bin flder f yur web site. 8. Register yur prvider in the <rt>/app_cnfig/unity.cnfig file: Set the payment prvider: <alias alias="<provider_name>" type="<your_namespace>.<provider_class_name>, <ASSEMBLY_NAME" />; Set the payment prvider in the <cntainer /> sectin: <register type="paymentprvider" mapt="<provider_name>" name="<custom_short_name>" /> 9. Create a new payment prvider item in the Payment Optins item f the Business Catalg frm the master://sitecre/templates/ecmmerce/business Catalg/Payment template. Fill in the necessary fields. The value f the Cde field shuld be equal t the <CUSTOM_SHORT_NAME> 10. Register the accunt n the service side and btain the credentials. Enter the URL, Merchant ID, and Passwrd in the field f the same need. 11. Publish the item. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 18 f 23
Payment Methd Reference Guide Payment Prvider Changes In this chapter, we describe what has changed in versin 1.1 as cmpared t 1.0.2 in terms f the payment prviders. Changes t API New Interfaces and Base Classes Sitecre E-Cmmerce Fundamental Editin 1.1 intrduces new types t the hierarchy f the payment prviders. Payment Prvider Class The main rt class, PaymentPrvider, which is an abstract class, was added. public abstract class PaymentPrvider public virtual PaymentStatus PaymentStatus get; set; public abstract vid Invke(PaymentSystem paymentsystem, PaymentArgs paymentargs); public abstract vid PrcessCallback(PaymentSystem paymentsystem, PaymentArgs paymentargs); The OnlinePaymentPrvider abstract class is directly inherited frm PaymentPrvider and implements the Invke()and the PstData()methds. The PstData() methd submits request parameters t the payment service URI: public abstract class OnlinePaymentPrvider : PaymentPrvider // Initializes the payment. public verride vid Invke(DmainMdel.Payments.PaymentSystem paymentsystem, PaymentArgs paymentargs) // Psts the data. prtected virtual vid PstData(string url, NameValueCllectin parameters) // Cnstants t use within the whle set f the payment prviders. prtected static class PaymentCnstants New Service Clients Sme new implementatins f the existing SEFE payment prviders were released in this versin: BbsPaymentPrvider EPayPaymentPrvider Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 19 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 PayExPaymentPrvider PayPalPaymentPrvider QuickPayPaymentPrvider All f these classes are inherited frm OnlinePaymentPrvider. IReservable Interface In the DmainMdel f the Sitecre E-Cmmerce Fundamental Editin, a new IReservable interface has been intrduced. The new IReservable interface is a cntract that allws ur payment prviders t interact with the payment services t capture previusly authrized amunts f mney and t cancel reserved tickets. public interface IReservable vid Capture(PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket, decimal amunt); vid CancelReservatin(PaymentSystem paymentsystem, PaymentArgs paymentargs, ReservatinTicket reservatinticket); Nw all payment prviders implement this interface: public class <SmePrvider>PaymentPrvider : OnlinePaymentPrvider, IReservable The crrespnding class diagram lks like this: Obslete Cntracts In versin 1.1, the fllwing payment cntracts and classes were marked as bslete: Interfaces: IPaymentPrvider<T> IOfflinePaymentPrvider<T> IOnlinePaymentPrvider<T> IReservableOnlinePaymentPrvider<T, TRT> Classes: Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 20 f 23
Payment Methd Reference Guide PaymentPrviderBase<T> OnlinePaymentPrviderBase<T> Changes t the Unity.cnfig File The new payment prvider implementatins can perate in tw mdes: With ticket reservatin r Withut ticket reservatin. Yu can cnfigure this in the Settings field f the apprpriate items. Registering the prviders in the Unity.cnfig file is simple. 1. Register the payment prvider alias. <alias alias="epaypaymentprvider" type="sitecre.ecmmerce.payments.dibs.epaypaymentprvider, Sitecre.Ecmmerce.Payments.EPay" /> 2. Register the mapping in the cntainer sectin. <register type="paymentprvider" mapt="epaypaymentprvider" name="epay" /> Imprtant Yu must map the implementatin t the PaymentPrvider base class. Changes t Cnfiguratin Files Sme payment prviders use web methds t grant access t their functinality. They als have different endpints fr testing purpses and fr wrking in prductin mde. All the prviders are cnfigured s as t interact with the URL fr test requests by default. Yu can change this behavir in the supplied Sitecre.Ecmmerce.Payments.<Prvider>.cnfig files. Here is an example fr the BBS service: <applicatinsettings> <Sitecre.Ecmmerce.Payments.Bbs.Prperties.Settings> <setting name="sitecre_ecmmerce_payments_bbs" serializeas="string"> <value>https://epayment.bbs.n/netaxept.svc</value> </setting> </Sitecre.Ecmmerce.Payments.Bbs.Prperties.Settings> </applicatinsettings> Changes t CMS Cntent This versin f SEFE cntains nly ne change that is related t the payment prvider: The IsOnlinePayment field was excluded frm the master://sitecre/templates/ecmmerce/business Catalg/Payment template. Changes t Functinality Affecting System Behavir SEFE 1.1 cntains all the cntracts required fr backward cmpatibility. This ensures that during the update nthing is deleted frm yur SEFE slutin. Upgrading yur SEFE versin t a newer ne, makes yur webshp mre reliable and secure. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 21 f 23
Sitecre E-Cmmerce Fundamental Editin 1.1 New Features The fllwing features have been intrduced: All the payment prviders supprt the reservatin f mney n the credit card and ticket bking. At the mment, yu can manage ticket cancellatin and payment capturing in the Order Catalg. Yu can als use the API fr this purpse. Fr mre infrmatin abut ticket cancellatin and payment capturing, see the Sitecre Payment Methds Reference Guide. Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 22 f 23
Payment Methd Reference Guide Glssary Payment gateway Payment gateway is a user interface f a payment service t which a custmer is redirected frm the webshp during a payment. After the payment is cmpleted, the custmer is redirected back t the webshp. Payment prvider Payment prvider is a client implementatin in yur webshp that makes it pssible t invlve a particular payment service during a payment. Payment prvider is a class that interacts with the crrespnding payment service (fr example, PayPal) using the crrespnding payment system settings. Payment service Payment service is an external internet service that makes it pssible t make nline payments. A payment service is a third party rganizatin. If yu want t use a particular payment service, such as Amazn, yu must create and cnfigure a payment prvider fr this payment service. Payment system Payment system is a set f cnfiguratin settings fr a payment prvider. A payment system typically includes the fllwing settings: URL Webshp Name Merchant ID Passwrd Sitecre is a registered trademark. All ther brand and prduct names are the prperty f their respective hlders. Page 23 f 23