Datatrans

Ruby adapter for the Datatrans payment gateway (http://www.datatrans.ch).

Configuration

Build your Datatrans Configuration like so:

datatrans=Datatrans::Config.new(:merchant_id=>'1234567',:sign_key=>'ab739fd5b7c2a1...',:password=>'server to server request password',:environment=>:production,:proxy=>{:http_proxyaddr=>"proxy.com",:http_proxyport=>80,:http_proxyuser=>"hans",:http_proxpass=>"xxx",})

If you don't want to use signed requests (disabled in datatrans web console), you can set config.sign_key to false. The configuration is then used as parameter to all the constructors and helpers, see examples below.

Possible values for the environment: :production, :development

Web Authorization

Important

Datatrans no longer supports the Payment Page API. The support in this gem will be removed in the next major release. Please use the JSON API instead.

If you want to process a credit card the first time a web authorization is necessary. Add the following code to a controller action that shows the form. You need to pass at least amount, currency and refno (order number).

@transaction=datatrans.web_transaction(:amount=>1000,# in cents!:currency=>'CHF',:refno=>'ABCDEF',:uppCustomerEmail=>'customer@email.com',# feel free to add more upp infos here ...)

In your View your show the credit card form with a convenient helper:

=form_tagDatatrans.web_authorize_urldo=text_field_tag:paymentmethod,'ECA'=text_field_tag:cardno=text_field_tag:expm=text_field_tag:expy=text_field_tag:cvv=hidden_field_tag:successUrl, <your_application_return_url>
=hidden_field_tag:cancelUrl, <your_application_return_url>
=hidden_field_tag:errorUrl, <your_application_return_url>=datatrans_notification_request_hidden_fields(datatrans,@transaction)=submit_tag"send"

In this example we use just ECA (Mastercard) as paymentmethod. Feel free to provide an appropriate select field to offer more payment methods. Don't forget to add successUrl, cancelUrl and errorUrl. We recommend to set them all to the same value.

After you submit the request to Datatrans they redirect back to your application. Now you can process the transaction like this:

begintransaction=datatrans.web_transaction(params)iftransaction.authorize# transaction was successful, access the following attributes# transaction.transaction_id# transaction.creditcard_alias# transaction.masked_cc# transaction.authorization_code# ...else# transaction was not successful, accces the error details# transaction.error_code, transaction.error_message, transaction.error_detailendrescueDatatrans::InvalidSignatureError=>exception# the signature was wrong, the request may have been compromised...end

JSON Transactions

More information about Datatrans JSON API can be found here. Our gem uses endpoints from /v1/transactions section.

We implemented support for Redirect mode (since Lightbox mode may not work correctly on mobile, whereas Redirect works well on all devices).

Saving Payment Information

According to the docs, there are three possible flows:

• Customer Initiated Payments: Your customer pays and nothing is registered.
  • This is the most basic setup and does not save any payment information: First, call transaction.init, and then redirect the user to the transaction_path (see the sections Initialize and Start a transaction below).
• Customer Initiated Payment and creating an alias for subsequent Merchant Initiated Payments: Your customer pays and the card or payment method information is registered. You receive an alias which you save for later merchant initiated payments or one-click checkouts.
  • In order to save payment information after your customer has finalized their payment, without them having to re-enter their payment information and go through the 3D-Secure flow, pass option: {"createAlias": true}. More information can be found here.
• Merchant Initiated Payments: Your customer registers their card or payment method information without any payment. Their account is not charged. This is what we call a dedicated registration.
  • This setup allows you to save a customers payment information without any charge in the beginning. This is useful in the context of setting up a subscription model (e.g., usage-based billing at the end of a billing period). See the section Merchant Initiated Payments below.

Initialize

Initialize a JSON transaction:

transaction=datatrans.json_transaction(refno: 'ABCDEF',amount: 1000,# in cents!currency: "CHF",payment_methods: ["ECA","VIS"],success_url: <your_application_return_url>,cancel_url: <your_application_return_url>,error_url: <your_application_return_url>
)# call to initialize endpoint to initialize a transaction# returns true or false depending if response was successful or notinit=transaction.init# successful authorization call returns in response a transaction idifinittransaction_id=transaction.response.params["transactionId"]end

Start a transaction

Once you have a transaction id, you can start a transaction. Users of your application will be redirected to the datatrans payment pages: https://pay.sandbox.datatrans.com/v1/start/{{transactionId}}.

path=datatrans.json_transaction(transaction_id: transaction_id).transaction_pathredirect_topath# or if you redirect after AJAX request:renderjs: "window.location='#{path}'"

You do not have to settle a transaction by yourself: we set "autoSettle": true by default when authorizing a transaction, which means the transaction will be settled automatically. This can be overridden by setting auto_settle: false when authorizing a transaction.

Transaction status

You can check the trasaction status, see its history and retrieve the card information.

transaction=datatrans.json_transaction(transaction_id: transaction_id)# status method returns true or false depending if response was successfulliftransaction.statusdata=transaction.response.params# this will return following hash (may vary dependong on your payment method):{"transactionId"=>"230223022302230223","merchantId"=>"1100000000","type"=>"payment","status"=>"settled","currency"=>"CHF","refno"=>"123456abc","paymentMethod"=>"VIS","detail"=>{"authorize"=>{"amount"=>1000,"acquirerAuthorizationCode"=>"100000"},"settle"=>{"amount"=>1000}},"language"=>"en","card"=>{"masked"=>"400000xxxxxx0018","expiryMonth"=>"06","expiryYear"=>"25","info"=>{"brand"=>"VISA","type"=>"debit","usage"=>"consumer","country"=>"SE","issuer"=>"SVENSKA HANDELSBANKEN AB"},"3D"=>{"authenticationResponse"=>"Y"}},"history"=>[{"action"=>"init","amount"=>1000,"source"=>"api","date"=>"2023-06-06T08:37:23Z","success"=>true,"ip"=>"8.8.8.8"},{"action"=>"authorize","autoSettle"=>true,"amount"=>1000,"source"=>"redirect","date"=>"2023-06-06T08:37:42Z","success"=>true,"ip"=>"8.8.8.8"}]}elsetransaction.response.error_codetransaction.response.error_messageend

Merchant Initiated Payments

It's possible to authorize transactions without user interaction, via merchant initiated payments.

To perform a so-called "dedicated registration" (so we can later charge the card via its alias), you should follow the same steps as described above, but not provide an amount:

transaction=datatrans.json_transaction(refno: 'ABCDEF',amount: 0,# omit amount for dedicated registrationscurrency: "CHF",payment_methods: ["ECA","VIS"],success_url: <your_application_return_url>,cancel_url: <your_application_return_url>,error_url: <your_application_return_url>
)init=transaction.init# successful authorization call returns in response a transaction idifinittransaction_id=transaction.response.params["transactionId"]end

Then, at a later point in time, and without needing any user interaction, you can create a payment via merchant_authorize:

dedicated_registration=datatrans.json_transaction(transaction_id: transaction_id)dedicated_registration.status# this will contain the card informationcard_alias=dedicated_registration.response.params["card"]["alias"]card_expiry_month=dedicated_registration.response.params["card"]["expiryMonth"]card_expiry_year=dedicated_registration.response.params["card"]["expiryYear"]transaction=datatrans.json_transaction(refno: "ABCDEF",amount: 1000,currency: "CHF",card: {alias: card_alias,expiryMonth: card_expiry_month,expiryYear: card_expiry_year})transaction.merchant_authorize# this will charge the card without user interaction

XML Transactions

Important

Datatrans will stop supporting the XML API on June 3rd, 2024. The support in this gem will be removed in the next major release. Please use the JSON API instead.

If you have already a credit card alias or an authorized transaction you can use the convenient XML methods to process payments.

Authorize

transaction=datatrans.xml_transaction(:refno=>'ABCDEF',:amount=>1000,# in cents!:currency=>'CHF',:aliasCC=>'8383843729284848348',:expm=>12,:expy=>15,)iftransaction.authorize# ok, the transaction is authorized...# access same values as in the web authorization (e.g. transaction.transaction_id)else# transaction.error_code, transaction.error_message, transaction.error_detailend

Capture

To capture an authorized transaction you use the following code:

transaction=datatrans.xml_transaction(:refno=>'ABCDEF',:amount=>1000,# in cents!:currency=>'CHF',:transaction_id=>19834324987349723948729834,)iftransaction.capture# ok, the money is yours...else# transaction.error_code, transaction.error_message, transaction.error_detailend

Void

To make an authorized transaction invalid use void.

transaction=datatrans.xml_transaction(:refno=>'ABCDEF',:amount=>1000,# in cents!:currency=>'CHF',:transaction_id=>19834324987349723948729834,)iftransaction.void# ok, the transaction is not longer valid...else# transaction.error_code, transaction.error_message, transaction.error_detailend

Todo

• allow signing of xml transactions
• allow signing with different keys
• add credit method to reverse already captured transactions
• add purchase method to authorize and capture in one step
• add url helpers for success, cancel and error urls
• extend configuration possibilities
• dry code more

Contribute

• Fork the project.
• Make your feature addition or bug fix.
• Add specs for it. This is important so we 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 we can ignore when we pull)
• Send us a pull request. Bonus points for topic branches.

Credits

Datatrans is maintained by Simplificator GmbH (http://simplificator.com).

The initial development was sponsered by Evita AG and Limmex AG.

License

Datatrans is released under the MIT license.