README.markdown in datatrans-5.1.0 vs README.markdown in datatrans-5.2.0
- old
+ new
@@ -29,10 +29,14 @@
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](#json-transactions) 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).
```ruby
@transaction = datatrans.web_transaction(
@@ -96,16 +100,28 @@
JSON Transactions
=================
More information about Datatrans JSON API can be found [here](https://api-reference.datatrans.ch/). Our gem uses endpoints from `/v1/transactions` section.
-We 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 devises).
+We 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).
-Authorize
+Saving Payment Information
+--------------------------
+
+According to the [docs](https://docs.datatrans.ch/docs/customer-initiated-payments#saving-payment-information), 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](https://docs.datatrans.ch/docs/redirect-lightbox#saving-payment-information).
+- **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
---------
-Authorize JSON transaction:
+Initialize a JSON transaction:
```ruby
transaction = datatrans.json_transaction(
refno: 'ABCDEF',
amount: 1000, # in cents!
@@ -114,13 +130,13 @@
success_url: <your_application_return_url>,
cancel_url: <your_application_return_url>,
error_url: <your_application_return_url>
)
-# call to init endpoint to initialize a transaction
+# call to initialize endpoint to initialize a transaction
# returns true or false depending if response was successful or not
-init = transaction.authorize
+init = transaction.init
# successful authorization call returns in response a transaction id
if init
transaction_id = transaction.response.params["transactionId"]
end
@@ -137,11 +153,11 @@
redirect_to path
# or if you redirect after AJAX request:
render js: "window.location='#{path}'"
```
-You 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.
+You 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.
Transaction status
------------------
You can check the trasaction [status](https://api-reference.datatrans.ch/#tag/v1transactions/operation/status), see its history and retrieve the card information.
@@ -194,14 +210,61 @@
transaction.response.error_code
transaction.response.error_message
end
```
+Merchant Initiated Payments
+---------
+It's possible to authorize transactions without user interaction, via [merchant initiated payments](https://docs.datatrans.ch/docs/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:
+
+```ruby
+transaction = datatrans.json_transaction(
+ refno: 'ABCDEF',
+ amount: 0, # omit amount for dedicated registrations
+ currency: "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 id
+if init
+ transaction_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`:
+
+```ruby
+dedicated_registration = datatrans.json_transaction(transaction_id: transaction_id)
+dedicated_registration.status # this will contain the card information
+
+card_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
================
-XML API is [deprecated](https://mailchi.mp/datatrans/basic-authdynamic-sign_reminder) by Datatrans. After June 3rd, 2024 all merchants will have to use JSON API.
+> [!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](#json-transactions) instead.
If you have already a credit card alias or an authorized transaction you can
use the convenient XML methods to process payments.
Authorize