gem for securetrading xpay applet
Switch branches/tags
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



An abstaction layer on top Xpay from for futher details, in depth specifications and installation guides of the xpay java applet


* install the xpay java applet and configure it according to the installation guidelines from SecureTrading
* start the applet then install the gem:

$ gem install xpay

* configure by either creating a yaml file at config/xpay.yml or call Xpay.set_config with a hash
* (make sure to use Xpay.set_config(options_hash) instead of setting the options direct as that would
* prevent the new xml from being generated)
* the following options can be set:
   - merchant_name
   - version
   - alias
   - site_reference
   - port
   - callback_url


* An example of a 3D-Secure Transaction

    -first: create the class instance for CreditCard, Customer and Operatioon

       cc = => "Visa",
                                 :number => "4111111111111160",
                                 :security_code => "123",
                                  :valid_until => "11/11")

       cus = => "Fred Bloggs")

       ops = => "GBP", :amount => 1999)

       Create payment instance
       p ={:creditcard => cc, :customer => cus, :operation => ops)

       Make payment
       rt = p.make_payment

    -second: depending on the return value rt:

       rt==0 An error occured during processing
       Check p.response_block[:error_code] for further details

       rt==1 Settlement request approve, check p.response_block for all the details
       rt==2 Settlement request declined, check p.response_block for all the details

       rt==-1 A redirection to an 3D-Secure server is necessary.
       All necessary information is contained in p.three_secure
       It has the following keys:
           :md     a unique reference generated according to the 3D Secure specification
                   (currently up to 1024 bytes in base64 format).
                   it is passed as parameter in the callback from the 3D-Secure server
                   and you will need to store it to find the transaction on callback

           :pareq  The pareq contains purchase transaction details upon which ACS authentication decisions are based.
                   If you are making your own customised redirect page instead of using the <Html> provided then this
                   field MUST be included in that html, as a hidden field. The length of the PaReq is not explicitly
                   defined by the 3-D Secure specification. We recommend allowing at least 4096 bytes
                   for this field in any variables/storage systems.

           :termurl Your own callback url. If you are making your own customised redirect page
                    instead of using the <Html> provided then this field MUST be included in that html as a hidden field.

           :acsurl  This is the url of the ACS it should be used as the location of the redirect if you use your own form/redirect

           :html   This value contains the complete html code if you don't want to use your own form.
                   This can be achieved by sending your normal server headers to the client immediately followed by the contents of the <Html> tag.

           :request_xml This is a complete xml document as string that you need to pass to a new payment instance after the callback.
                        You need to store this field for the callback.

    -third: after the callback from the 3D Secure Server:

        make sure that protect_from_forgery is switched off for this controller method as it is not transmitted by the callback
        you will have to paramaters in the params hash
        params[:MD] and params[:PaRes]

        Use params[:md] to find your stored transaction:

        create a new class instance with the request_xml stored in the transaction and params[:PaRes] from the callback

         p ={:xml => request_xml, :pares => params[:PaRes])

        make the payment

         rt = p.make_payment

        The possible values of rt are as above.

* more examples to follow


See LICENSE for details.

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself in another branch so I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.