{"id":18978020,"url":"https://github.com/simplificator/datatrans","last_synced_at":"2025-09-23T21:19:56.334Z","repository":{"id":1570654,"uuid":"2005081","full_name":"simplificator/datatrans","owner":"simplificator","description":"A simple implementation of the Datatrans API (see datatrans.ch)","archived":false,"fork":false,"pushed_at":"2024-10-24T09:04:26.000Z","size":159,"stargazers_count":23,"open_issues_count":5,"forks_count":15,"subscribers_count":14,"default_branch":"master","last_synced_at":"2024-10-25T00:35:44.736Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simplificator.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2011-07-06T07:01:30.000Z","updated_at":"2024-09-06T12:15:31.000Z","dependencies_parsed_at":"2023-07-05T19:02:03.390Z","dependency_job_id":"65ef2bc9-84bd-4112-826a-a9665228cdb3","html_url":"https://github.com/simplificator/datatrans","commit_stats":{"total_commits":104,"total_committers":12,"mean_commits":8.666666666666666,"dds":0.8173076923076923,"last_synced_commit":"98ebe1c153d82b04287bca848afa02a8caa47922"},"previous_names":[],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplificator%2Fdatatrans","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplificator%2Fdatatrans/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplificator%2Fdatatrans/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simplificator%2Fdatatrans/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simplificator","download_url":"https://codeload.github.com/simplificator/datatrans/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247369952,"owners_count":20927928,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-08T15:31:52.101Z","updated_at":"2025-09-23T21:19:51.261Z","avatar_url":"https://github.com/simplificator.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"Datatrans\n=========\n\nRuby adapter for the Datatrans payment gateway (http://www.datatrans.ch).\n\nConfiguration\n-------------\n\nBuild your Datatrans Configuration like so:\n\n```ruby\n    datatrans = Datatrans::Config.new(\n      :merchant_id =\u003e '1234567',\n      :sign_key =\u003e 'ab739fd5b7c2a1...',\n      :password =\u003e 'server to server request password',\n      :environment =\u003e :production,\n      :proxy =\u003e {\n        :http_proxyaddr =\u003e \"proxy.com\",\n        :http_proxyport =\u003e 80,\n        :http_proxyuser =\u003e \"hans\",\n        :http_proxpass =\u003e \"xxx\",\n      }\n    )\n```\n\nIf you don't want to use signed requests (disabled in datatrans web console), you can set `config.sign_key` to `false`.\nThe configuration is then used as parameter to all the constructors and helpers, see examples below.\n\nPossible values for the environment: `:production`, `:development`\n\nWeb Authorization\n=================\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e 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](#json-transactions) instead.\n\nIf you want to process a credit card the first time a web authorization is\nnecessary. Add the following code to a controller action that shows the form.\nYou need to pass at least `amount`, `currency` and `refno` (order number).\n```ruby\n    @transaction = datatrans.web_transaction(\n      :amount =\u003e 1000, # in cents!\n      :currency =\u003e 'CHF',\n      :refno =\u003e 'ABCDEF',\n      :uppCustomerEmail =\u003e 'customer@email.com',\n      # feel free to add more upp infos here ...\n    )\n```\n\nIn your View your show the credit card form with a convenient helper:\n\n```ruby\n    = form_tag Datatrans.web_authorize_url do\n\n      = text_field_tag :paymentmethod, 'ECA'\n      = text_field_tag :cardno\n      = text_field_tag :expm\n      = text_field_tag :expy\n      = text_field_tag :cvv\n\n      = hidden_field_tag :successUrl, \u003cyour_application_return_url\u003e\n      = hidden_field_tag :cancelUrl, \u003cyour_application_return_url\u003e\n      = hidden_field_tag :errorUrl, \u003cyour_application_return_url\u003e\n\n      = datatrans_notification_request_hidden_fields(datatrans, @transaction)\n\n      = submit_tag \"send\"\n```\n\nIn this example we use just ECA (Mastercard) as paymentmethod. Feel free to\nprovide an appropriate select field to offer more payment methods. Don't forget\nto add `successUrl`, `cancelUrl` and `errorUrl`. We recommend to set them all\nto the same value.\n\nAfter you submit the request to Datatrans they redirect back to your application.\nNow you can process the transaction like this:\n```ruby\n    begin\n      transaction = datatrans.web_transaction(params)\n\n      if transaction.authorize\n        # transaction was successful, access the following attributes\n        # transaction.transaction_id\n        # transaction.creditcard_alias\n        # transaction.masked_cc\n        # transaction.authorization_code\n        # ...\n\n      else\n        # transaction was not successful, accces the error details\n        # transaction.error_code, transaction.error_message, transaction.error_detail\n\n      end\n    rescue Datatrans::InvalidSignatureError =\u003e exception\n      # the signature was wrong, the request may have been compromised...\n    end\n```\n\nJSON Transactions\n=================\n\nMore information about Datatrans JSON API can be found [here](https://api-reference.datatrans.ch/). Our gem uses endpoints from `/v1/transactions` section. \n\nWe implemented support for [Redirect mode](https://docs.datatrans.ch/docs/redirect-lightbox) (since Lightbox mode may not work correctly on mobile, whereas Redirect works well on all devices).\n\nSaving Payment Information\n--------------------------\n\nAccording to the [docs](https://docs.datatrans.ch/docs/customer-initiated-payments#saving-payment-information), there are three possible flows:\n\n- **Customer Initiated Payments**: _Your customer pays and nothing is registered._\n  - 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).\n- **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._\n  - 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](https://docs.datatrans.ch/docs/redirect-lightbox#saving-payment-information).\n- **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._\n  - 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.\n\nInitialize\n---------\n\nInitialize a JSON transaction:\n\n```ruby\ntransaction = datatrans.json_transaction(\n  refno: 'ABCDEF',\n  amount: 1000, # in cents!\n  currency: \"CHF\",\n  payment_methods: [\"ECA\", \"VIS\"],\n  success_url: \u003cyour_application_return_url\u003e,\n  cancel_url: \u003cyour_application_return_url\u003e,\n  error_url: \u003cyour_application_return_url\u003e\n)\n\n# call to initialize endpoint to initialize a transaction\n# returns true or false depending if response was successful or not\ninit = transaction.init\n\n# successful authorization call returns in response a transaction id\nif init\n  transaction_id = transaction.response.params[\"transactionId\"]\nend\n```\n\nStart a transaction\n-------------------\n\nOnce 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}}`.\n\n```ruby\n path = datatrans.json_transaction(transaction_id: transaction_id).transaction_path\n\n redirect_to path\n # or if you redirect after AJAX request:\n render js: \"window.location='#{path}'\"\n```\n\nYou do not have to [settle a transaction](https://api-reference.datatrans.ch/#tag/v1transactions/operation/settle) 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.\n\nTransaction status\n------------------\n\nYou can check the trasaction [status](https://api-reference.datatrans.ch/#tag/v1transactions/operation/status), see its history and retrieve the card information.\n\n```ruby\n  transaction = datatrans.json_transaction(transaction_id: transaction_id)\n\n  # status method returns true or false depending if response was successfull\n  if transaction.status\n    data = transaction.response.params\n    # this will return following hash (may vary dependong on your payment method):\n    {\n      \"transactionId\"=\u003e\"230223022302230223\",\n      \"merchantId\"=\u003e\"1100000000\",\n      \"type\"=\u003e\"payment\",\n      \"status\"=\u003e\"settled\",\n      \"currency\"=\u003e\"CHF\",\n      \"refno\"=\u003e\"123456abc\",\n      \"paymentMethod\"=\u003e\"VIS\",\n      \"detail\"=\u003e\n        {\"authorize\"=\u003e{\"amount\"=\u003e1000, \"acquirerAuthorizationCode\"=\u003e\"100000\"}, \"settle\"=\u003e{\"amount\"=\u003e1000}},\n      \"language\"=\u003e\"en\",\n      \"card\"=\u003e\n        {\"masked\"=\u003e\"400000xxxxxx0018\",\n        \"expiryMonth\"=\u003e\"06\",\n        \"expiryYear\"=\u003e\"25\",\n        \"info\"=\u003e\n          {\"brand\"=\u003e\"VISA\",\n          \"type\"=\u003e\"debit\",\n          \"usage\"=\u003e\"consumer\",\n          \"country\"=\u003e\"SE\",\n          \"issuer\"=\u003e\"SVENSKA HANDELSBANKEN AB\"},\n        \"3D\"=\u003e{\"authenticationResponse\"=\u003e\"Y\"}},\n      \"history\"=\u003e\n        [{\"action\"=\u003e\"init\",\n          \"amount\"=\u003e1000,\n          \"source\"=\u003e\"api\",\n          \"date\"=\u003e\"2023-06-06T08:37:23Z\",\n          \"success\"=\u003etrue,\n          \"ip\"=\u003e\"8.8.8.8\"},\n        {\"action\"=\u003e\"authorize\",\n          \"autoSettle\"=\u003etrue,\n          \"amount\"=\u003e1000,\n          \"source\"=\u003e\"redirect\",\n          \"date\"=\u003e\"2023-06-06T08:37:42Z\",\n          \"success\"=\u003etrue,\n          \"ip\"=\u003e\"8.8.8.8\"}]\n    }\n  else\n    transaction.response.error_code\n    transaction.response.error_message\n  end\n```\n\nMerchant Initiated Payments\n---------\n\nIt's possible to authorize transactions without user interaction, via [merchant initiated payments](https://docs.datatrans.ch/docs/merchant-initiated-payments).\n\nTo 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:\n\n```ruby\ntransaction = datatrans.json_transaction(\n  refno: 'ABCDEF',\n  amount: 0, # omit amount for dedicated registrations\n  currency: \"CHF\",\n  payment_methods: [\"ECA\", \"VIS\"],\n  success_url: \u003cyour_application_return_url\u003e,\n  cancel_url: \u003cyour_application_return_url\u003e,\n  error_url: \u003cyour_application_return_url\u003e\n)\n\ninit = transaction.init\n\n# successful authorization call returns in response a transaction id\nif init\n  transaction_id = transaction.response.params[\"transactionId\"]\nend\n```\n\nThen, at a later point in time, and without needing any user interaction, you can create a payment via `merchant_authorize`:\n\n```ruby\ndedicated_registration = datatrans.json_transaction(transaction_id: transaction_id)\ndedicated_registration.status # this will contain the card information\n\ncard_alias = dedicated_registration.response.params[\"card\"][\"alias\"]\ncard_expiry_month = dedicated_registration.response.params[\"card\"][\"expiryMonth\"]\ncard_expiry_year = dedicated_registration.response.params[\"card\"][\"expiryYear\"]\n\ntransaction = datatrans.json_transaction(\n  refno: \"ABCDEF\",\n  amount: 1000,\n  currency: \"CHF\",\n  card: {alias: card_alias, expiryMonth: card_expiry_month, expiryYear: card_expiry_year}\n)\n\ntransaction.merchant_authorize # this will charge the card without user interaction\n```\n\nXML Transactions\n================\n\n\u003e [!IMPORTANT]\n\u003e\n\u003e 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](#json-transactions) instead.\n\nIf you have already a credit card alias or an authorized transaction you can\nuse the convenient XML methods to process payments.\n\nAuthorize\n---------\n\n```ruby\n    transaction = datatrans.xml_transaction(\n      :refno =\u003e 'ABCDEF',\n      :amount =\u003e 1000, # in cents!\n      :currency =\u003e 'CHF',\n      :aliasCC =\u003e '8383843729284848348',\n      :expm =\u003e 12,\n      :expy =\u003e 15,\n    )\n\n    if transaction.authorize\n      # ok, the transaction is authorized...\n      # access same values as in the web authorization (e.g. transaction.transaction_id)\n    else\n      # transaction.error_code, transaction.error_message, transaction.error_detail\n    end\n```\n\n\nCapture\n-------\n\nTo capture an authorized transaction you use the following code:\n\n```ruby\n    transaction = datatrans.xml_transaction(\n      :refno =\u003e 'ABCDEF',\n      :amount =\u003e 1000, # in cents!\n      :currency =\u003e 'CHF',\n      :transaction_id =\u003e 19834324987349723948729834,\n    )\n\n    if transaction.capture\n      # ok, the money is yours...\n    else\n      # transaction.error_code, transaction.error_message, transaction.error_detail\n    end\n```\n\nVoid\n----\n\nTo make an authorized transaction invalid use void.\n\n```ruby\n    transaction = datatrans.xml_transaction(\n      :refno =\u003e 'ABCDEF',\n      :amount =\u003e 1000, # in cents!\n      :currency =\u003e 'CHF',\n      :transaction_id =\u003e 19834324987349723948729834,\n    )\n\n    if transaction.void\n      # ok, the transaction is not longer valid...\n    else\n      # transaction.error_code, transaction.error_message, transaction.error_detail\n    end\n```\n\nTodo\n====\n\n* allow signing of xml transactions\n* allow signing with different keys\n* add credit method to reverse already captured transactions\n* add purchase method to authorize and capture in one step\n* add url helpers for success, cancel and error urls\n* extend configuration possibilities\n* dry code more\n\n\nContribute\n==========\n\n* Fork the project.\n* Make your feature addition or bug fix.\n* Add specs for it. This is important so we don't break it in a\n  future version unintentionally.\n* Commit, do not mess with rakefile, version, or history.\n  (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)\n* Send us a pull request. Bonus points for topic branches.\n\n\nCredits\n=======\n\nDatatrans is maintained by Simplificator GmbH (http://simplificator.com).\n\nThe initial development was sponsered by Evita AG and Limmex AG.\n\nLicense\n=======\n\nDatatrans is released under the MIT license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplificator%2Fdatatrans","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimplificator%2Fdatatrans","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimplificator%2Fdatatrans/lists"}