Secure Payment Form V2 Internet Merchant
Contents
1. L2 w Ex er Eiut Internet Merchant Payment Solution Secure Payment Form V2 C Der Bit Cyberbit A S Development Resource Guide Secure Payment Form V2 internet Merchant Payment Solution Copyright 2009 Cyberbit A S All rights reserved AC ES CvberBit Internet Merchant Payment Solution Secure Payment Form V2 Change Register 23 01 2008 01 09 2009 Updated parameter list 12 10 2009 Contact Details support cyberbit eu General Product Support Phone 45 7027 0585 support cyberbit eu Phone 45 7027 0585 Technical Support Questions Copyright 2009 Cyberbit A S All rights reserved CEE CvberBit Internet Merchant Payment Solution Secure Payment Form V2 Table of Contents Copyright 2009 Cyberbit A S All rights reserved 1 Introduction Cyberbit s Secure Payment Form SPF is an easily integrated solution which permits secure and trusted transactions over the Internet The following document describes how to integrate the payment solution into a merchant s website The document will guide a developer through the integration process required to use Cyberbit s Secure Payment Form To make the integration even easier this guide also provides code examples for the various development requirements Secure connectivity is obtained over the Internet by establishing an SSL encrypted connection between the merchant s website and the Cyberbit Payment Gateway To integrate a merch2. lt html gt lt head gt lt title gt Test Payment lt title gt lt head gt body form method POST action https test com spfv2 spfv2 php gt value 1 name transtype gt value sdf6a6yr3 3d 33 name secret gt value https www cyberbit eu bjarne test accept php input type hidden input type hidden input type hidden name accepturl gt input input input lt INPUE input name hash gt lt input input input input input input lt INPUE input lt input lt input lt input name header gt lt input lt input lt LNOUE lt input lt input type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type submit value CyberTest name merchantid gt value test3 name InternalorderId value 978 name currencycode gt value 100 name amountcleared gt value 28006f49d5ffc3a60adbe4898594e7493ee34b055 value cardholder email com name owneremail gt value some street name owneraddress gt value 123 name owneraddressnumber gt value London name ownercity gt value OO name ownerstate gt value GB name ownercountry value Larry name ownerfirstname gt value Smith name ow
3. is sent Before a transaction 1s sent to the payment gateway a hash has to be generated to make sure that the data has not been altered When this hash has been generated it is sent in the post along with the other required information The following fields are used to create the hash value Merchantld Transtype InternalOrderId Currency Amount Subscriptionld HashKey Example Merchantld CyberTest Transtype InternalOrderld test Currency 978 Amount 100 SubscriptionId HashCode 123 String CyberTestltest1978100123 Hash shal CyberTest1test1978100123 Hash bdfcd17a913e26b1966539d76c748b6c8ca08af9 Validating data sent to the accept page It is also possible to validate the data sent to the accept page and example is provided below Statuscode Statustext OrderId Time HashKey Statuscode 000 Statustext Success From Processer Order Id test Time 20080125153955 HashCode 123 String 000Success From Processertest120080125153955123 Hash shal 000Success From Processertest120080125153955123 Hash ac7a7f45031801226260377406c19e5bc8f90f3c5 Validating data sent to the callback URL It is very important that the data sent to the callback URL is validated to ensure that the transaction result is coming from the Payment Gateway and have not been altered If the hash is NOT validated anybody knowing the callback URL and what the data sent to it looks like could forge a false transaction r
4. the chapter Implementing the Methods 3 The cardholder is presented with the SPF located on a Cyberbit web server 4 The cardholder fills the SPF with the needed credit card information and sends payment information to Cyberbit s Payment Gateway 5 Payment status is sent to the merchant s web server to ensure that the transaction order is registered at the merchant s website For further details please see the chapter Callback from the Payment Gateway 6 A payment status is sent back to the cardholder this status page displays if the transaction was a SUCCESS 7 Cardholder is directed back to merchant s website to get his hers receipt 2 Sending Transactions This chapter will describe the procedures and parameters to send the different types of transactions to the SPF All transactions will be made through a HTTPS POST as described below Format Values Key A Alphabetical a z A Z N Numeric 0 9 AN Alpha Numeric a z A Z 0 9 URL Uniform Resource Locator Presence Values Key R Required O Optional C Conditional Parameter Name Format Presence Description Secret R Transaction secret provided by Cyberbit A S Merchantld R Merchant ID provided by Cyberbit A S CurrencyCode Currency code according to ISO 4217 Terminal Terminal O If Terminal is set the Cyberbit Payment Gateway will automatically generate an order id for the order being processed This means instead of us
5. transtype gt lt input type hidden value sdf6a6yr3 3d 33 name secret gt lt input type hidden value https www cyberbit eu bjarne test accept php name accepturl gt input input input input lt 1NPUE name hash gt input 1nput input lt input lt input lt input input lt LNOUE lt input anput input name header gt input input input lt INPUE type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden type hidden value CyberTest name merchantid gt value test3 name InternalorderId value 9 8 name currencycode gt value 100 name amountcleared gt value 28006f49d5ffc3a60adbe4898594e7493ee34b055 value cardholder email com name owneremail gt value some street name owneraddress gt value 123 name owneraddressnumber gt value London name ownercity gt value 00 name ownerstate gt value GB name ownercountry gt value Larry name ownerfirstname gt value Smith name ownerlastname gt value 123456 name ownerzip value 442154856354 name ownerphone gt value Item Number Item Description Amount Price value 1 Blue car 1 1 000 00 name orderline1l gt value 2 R
6. when creating a new subscription To know more about recurring transaction read the manual Cyberbit User Manual Recurrin The parameters above are the only data required to make a transactions The parameters below are all optional and will be shown on the SPF The table below shows the fields that should be sent in the POST message to display order information to the customer An example of this is shown in the part 2 1 of this chapter Examples can also be found in the examples html you have received together with this manual Parameter Name Format Presence Description The first order line to be shown There can be as many order lines as desired by incrementing the number by one for every order line Orderline 1 This field allows you to show to total amount to the customer 2 1 Implementing the Methods An authorize or an authorize capture request is made by sending a HTTPS POST to the Cyberbit Payment Gateway The Cyberbit Payment Gateway is accessible through the following URL Test Environment URL will be given to you upon account creation Live Environment URL will be given to you upon account creation Below is a code example of how to make the HTTPS POST and start the SPF First prepare the POST Below is an example on how a POST could look like The example can also be found in the example html form method POST action https test xxxxx xx xxxx php gt lt input type hidden value 1 name
7. ant s website with Cyberbit using the SPF a developer must be able to provide client side security for receiving information This 1s done by connecting to Cyberbit using the HTTPS protocol so as to pass this information using SSL This document provides information on how to implement the following e commerce transaction types Authorization Only Authorization and Capture 1 1 Reguirements Before the merchant will be able to start testing a few things have to be in place The merchant must have received a test account with the following information Merchantld Unigue ID assigned to merchants Password used to login to the payment gateway backend Secret Code Unigue code sent with every transaction Hashing Code Secret hashing code used to validate transaction data This code must only be known by the merchant and Cyberbit A S System Overview 1 Start Payment FR 7 Receipt Page N Card Holder Merchants Website A 2 Payment Request 5 Payment Status ent Gateway Cyberbit Paym The diagram above shows the payment process when using Cyberbit s SPF 1 When the cardholder have selected the goods he she wants to buy and have filled a form on merchant s website stating his hers name address shipping info etc the cardholder presses a link button to start the payment 2 Merchant s website opens a payment window linked to Cyberbit s SPF For further details see
8. e see PHP Code Example For a complete Copy Paste example of the entire payment process written in PHP see PHP Code Example 3 Transaction Status Codes Status Codes Status Text gi 2 3 10 000 Status Code Text O Missing or wrong MerchantId I Ul 006 Access Error Restricted by Ip Address TransType are not supported by this Clearing Gateway p09 Error From Processor Error From Processor 019 Cannot find at Authorize Capture to process 043 CreditCards from country is Blocked This acguirer does not support recurring transactions Billing interval must be 5 or higher check merchant guide for more info 046 Transtype Authorize or Sale after Authorize is not allowed here Use Transtype 3 or 8 47 Instead IP and Credit Card is not from same countr 4 State Codes US Canadian State Codes State OO Outside US or Canada District of Columbia Delaware Delaware KY po ND North Dakota OR rego PRO Puerto Rico ON Ontario Saskatchewan 5 PHP Code Example This chapter will show examples m PHP of the entire payment process The payment page Below is an example of the form that starts the payment When the Make Payment button is pressed the SPF will start and the cardholder can start the payment Further examples can be found in examples html
9. ed bike 2 250 00 name orderline2 gt value Shipping 150 00 name shipping gt value Total 1 650 00 name total gt input type submit value Make Payment gt lt form gt The example above will create a payment form with the above details Notice the header orderlineX shipping and total fields These fields will generate a table containing the order information which will be shown on the SPF if enabled The example above will create an order information table like the one below Order Information Itern Number item Description Price 1 Blue car 2 Red bike 2 250 00 Shipping 150 00 Total 1 650 00 2 2 Callback from Payment Gateway After every transaction the merchant will receive a POST message with status of the transaction This POST will be sent to the callback URL defined by the merchant The merchant s callback page will receive four callback parameters Parameter Name Description Fingerprint The SHA1 hash of the transaction see Validating Transaction Data for further details Xml Will return all data sent by the merchant s website to Cyberbit s Payment Gateway in XML format Besides data from the merchant s website this XML will also hold the transaction data from the Payment Gateway To see an example of a returned XML message see the chapter XML Example The purpose of the callback message is to inform the merchant s website of the transaction status The callbac
10. esult and maybe fooling the system to think that a valid transaction has been made Only the XML containing the transaction data and the fingerprint is sent to the callback URL To validate 1f the data 1s valid first generate a hash our of the XML and your unique hashing key Shal XML HashKey And hold the resulting SHA1 hashing value up against the fingerprint If those two values matches then the data is valid Below is an example if the SHA1 creation written in PHP fingerprint shal Sxml Shashkey Note that the unique key is in the end of the XML message When the SHA1 hashing has been made compare this value to the value received in the fingerprint parameter of the callback message IMPORTANT The unique key is only known by Cyberbit A S and the merchant make sure the key 1s never shown on the merchant s website 2 4 Finishing the Payment Process When a successful transaction has been made the cardholder will be directed back to the merchant s website Because of the cross domain policies in the mozilla browser the merchant s accept page will be shown in the payment window Because of this it is recommended that the merchant s accept page takes the parameters from the POST given to the accept page send the data to a receipt page on the merchant s website and closes the payment window In this way the cardholder will be directed back to the merchant s website showing a receipt page For a PHP example of a possible accept pag
11. hodCall gt lt SiteURL gt test xxxxx xx lt SiteURL gt lt IpAddress gt xxx xxx xxx xxx lt IpAddress gt lt ProcessDate gt 2007 03 29 16 16 34 lt ProcessDate gt ProcessUsedTime 1 3863520622253 ProcessUsedTime lt MerchantId gt xxxxxxxx lt MerchantId gt lt ProcessStatus gt 0 lt ProcessStatus gt lt ProcessStatusText gt Transaction OK lt ProcessStatusText gt lt AcquireCode gt 0 lt AcquireCode gt lt AcquireText gt Transaction OK lt AcquireText gt lt OrderiD gt testl234 lt Order1ID gt lt AuthResponse gt 422666 lt AuthResponse gt lt ProcessOrderID gt C381600117517779515367 422666 lt ProcessOrderID gt lt Response gt lt ECGPro gt
12. ing an order id generated by the merchant the Payment Gateway will generate an order id and return this id to the callback URL and the accept URL If the Terminal parameter is set the Orderld parameter will be ignored and can be left out If you need this functionality set this value to Terminal OwnerAddress AN 50 C Cardholder s address OwnerCit Cardholder s cit OwnerState A 2 C Cardholder s state for a list of valid states see State Codes OwnerLastName A 20 R Cardholder s last name OwnerPhone AN 20 C Cardholder s phone number OwnerMonthOfBirth N 2 C Cardholder s month of birth MM ShippingFirstName A 20 O First name of the person who receives the goods ShippingAddress AN 50 O The shipping address O SWE ShippingCity AN 50 The shipping city ShippingState A 2 O Shipping state for a list of valid states see State Codes ShippingEmail AN 100 O The E Mail of the person who receives the goods CreditCardType A 10 O This is the type of credit card selected by the cardholder Valid Options Option Description Visa Visa Visaelec Visa Electron Mastercard MasterCard Maestro Maestro Amex American Express Dinersclub Diners Club Discover Discover cb JC Solo Solo Bleue Bleue Visadan Visa Dankort Edankort eDankort V L Giropa GiroPa C w es SubscriptionID Subscription ID used with recurring transactions The subscription ID is assigned
13. k message is sent promptly after a transaction have been made in this way the merchant s website will be able to acknowledge a transaction even though the cardholder might close the SPF immediately after a transaction have been made and therefore not getting a receipt from the merchant s receipt page Important It is important that the merchant acknowledges the transaction on the callback URL instead of on the accept URL The reason to this 1s that the cardholder might close the SPF immediately after a transaction have been made and therefore never reach the accept page If this 1s the case and the merchant only acknowledges a successful transaction on the accept page the money will be drawn from the cardholder s bank account but the merchant will never register the transaction and therefore will never send the goods If the transaction 1s acknowledged on the callback page the merchant will always be able to acknowledge a transaction even though the SPF is closed by the cardholder All errors that may happen in a transaction will also be returned to the callback URL In this way the merchant is able to log the error message returned by the Payment Gateway 2 3 Validating Transaction Data When the account information is received you will receive a unique hashing key along with your other account information This key 1s used in the data validation process to make sure the data has not been altered in any way Hashing before the transaction
14. n the payment window The example below will take the data returned by the Payment Gateway and direct the cardholder and the data to a receipt page on the merchant s website php ohashaingKey xxxxxxx echo hlsAOCOepte nls Stmp array foreach GET as key gt Svalue 5tmp strtoupper key value oSsrr ocmp STATUSCODE s ostr a Stump STATUSTEXI s str tmp ORDERID ostr orcmp TIME 9 GETI MyHasHh shalt 5tr hashingqREY e echo lt pre gt print r 5 GET echo prec x XML Parser As mentioned earlier the transaction result 1s sent to the callback URL but before the data can be used the XML has to be parsed Below 1s an example on how to parse the transaction XML using PHP oxml trim POST xml op xml parser cr ate xml parse into struct p xml vals index xml parser free 5p for Si 0 i lt count s5vals SITE 4 if vals i type complete print valsis tag vals iozi valus 6 XML Example The example below is how an XML message could look The information in the top the Response tag is information specific from the Payment Gateway and the information in the lower part the lt ReturnInfo gt is information received from the merchant s website eRCOCEPPO Response StatusCode 000 StatusCode lt StatusText gt Success From Processor lt StatusText gt lt MethodCall gt POST lt Met
15. nerlastname gt value 123456 name ownerzip gt value 442154856354 name ownerphone gt value Item Number Item Description Amount Price value 1 Blue car 1 000 00 name orderlinel value 2 Red bike 2 250 00 namese orderline2 value Shipping 150 00 name shipping gt value Total 1 650 00 name total gt value Make Payment gt lt body gt lt html gt Page linked to the Callback URL The code below is for test purpose only to see what data is returned It writes all callback data to a file In a Live situation this page should be where the order is acknowledged and reserved for the cardholder OBS Be sure the chante hashingKey xxxxxxx with the hashing code provided by Cyberbit A S lt This PHP example writes all callback data to a file called callback txt ShashingKey xxxxxxx fingerprint trim S POST fingerprint xml trim _POST xml I Check LE finogerprsnt matches if shal xml hashingKey Sfingerprint SString lt FINGERPRINT StTingerprint s ANN Sstring statuscode else SSEKLNg Fingerprint did not maten handle fope n callba k txE w fwrite Shandle Sstring fclose handle gt Accept page This is the accept page the cardholder will be returned to when a payment is done Because if the cross domain policies in mozilla as described earlier this page will be shown i
Download Pdf Manuals
Related Search