Merge pull request #166 from Adyen/feature/terminal-api

Aleffio · web-flow · commit 9763eb966527 · 2023-08-25T09:02:18.000+02:00
Feature/terminal api
diff --git a/README.md b/README.md
@@ -21,6 +21,7 @@ This library supports the following:
 | [Recurring API](https://docs.adyen.com/api-explorer/Recurring/68/overview) | v68 | Endpoints for managing saved payment details. | [Recurring](lib/adyen/services/recurring.rb) |
 | [Stored Value API](https://docs.adyen.com/payment-methods/gift-cards/stored-value-api) | v46 | Manage both online and point-of-sale gift cards and other stored-value cards. | [StoredValue](lib/adyen/services/storedValue.rb) |
 | [Transfers API](https://docs.adyen.com/api-explorer/transfers/3/overview) | v3 | The Transfers API provides endpoints that can be used to get information about all your transactions, move funds within your balance platform or send funds from your balance platform to a transfer instrument. | [Transfers](lib/adyen/services/transfers.rb) |
+| [Cloud-based Terminal API](https://docs.adyen.com/point-of-sale/design-your-integration/terminal-api/terminal-api-reference/) | - | Our point-of-sale integration. | [TerminalCloudAPI](lib/adyen/services/terminalCloudAPI.rb) |
 
 For more information, refer to our [documentation](https://docs.adyen.com/) or the [API Explorer](https://docs.adyen.com/api-explorer/).
 
@@ -99,6 +100,121 @@ To run the tests use :
 bundle install --with development 
 ~~~~
 
+## Using the Cloud Terminal API Integration
+In order to submit In-Person requests with [Terminal API over Cloud](https://docs.adyen.com/point-of-sale/design-your-integration/choose-your-architecture/cloud/) you need to initialize the client in the same way as explained above for Ecommerce transactions:
+``` ruby
+# Step 1: Require the parts of the module you want to use
+require 'adyen-ruby-api-library'
+
+# Step 2: Initialize the client object
+adyen = Adyen::Client.new(api_key: 'YOUR_API_KEY', env: :test)
+
+# Step 3: Create the request
+serviceID = "123456789"
+saleID = "POS-SystemID12345"
+POIID = "Your Device Name(eg V400m-123456789)"
+
+# Use a unique transaction for every transaction you perform
+transactionID = "TransactionID"
+
+request = 
+{
+  "SaleToPOIRequest": {
+    "MessageHeader": {
+      "MessageClass": "Service",
+      "MessageCategory": "Payment",
+      "MessageType": "Request",
+      "ServiceID": serviceID,
+      "SaleID": saleID,
+      "POIID": POIID,
+      "ProtocolVersion": "3.0"
+    },
+    "PaymentRequest": {
+      "SaleData": {
+        "SaleTransactionID": {
+          "TransactionID": transactionID,
+          "TimeStamp": "2023-08-23T09:48:55"
+        },
+        "SaleToAcquirerData": "eyJhcHBsaWNhdGlvbkluZm8iOnsiYWR5ZW5MaWJyYXJ5Ijp7Im5hbWUiOiJhZ....",
+        "TokenRequestedType": "Transaction"
+      },
+      "PaymentTransaction": {
+        "AmountsReq": {
+          "Currency": "EUR",
+          "RequestedAmount": 10
+        }
+      }
+    }
+  }
+}
+
+# Step 4: Make the request
+response = adyen.terminal_cloud_api.sync(request)
+```
+
+### Optional: perform an abort request
+
+To perform an [abort request](https://docs.adyen.com/point-of-sale/basic-tapi-integration/cancel-a-transaction/) you can use the following example:
+``` ruby
+abortRequest = 
+{
+  "MessageHeader": {
+    "MessageClass": "Service",
+    "MessageCategory": "Abort",
+    "MessageType": "Request",
+    "ServiceID": serviceID,
+    "SaleID": saleID,
+    "POIID": POIID,
+    "ProtocolVersion": "3.0"
+  },
+  "AbortRequest": {
+    "AbortReason": "MerchantAbort",
+    "MessageReference": {
+      "MessageCategory": "Payment",
+      "SaleID": saleID,
+      # Service ID of the payment you're aborting
+      "ServiceID": serviceID,
+      "POIID": POIID
+    }
+  }
+}
+
+response = adyen.terminal_cloud_api.sync(abortRequest)
+```
+
+### Optional: perform a status request
+
+To perform a [status request](https://docs.adyen.com/point-of-sale/basic-tapi-integration/verify-transaction-status/) you can use the following example:
+``` ruby
+statusRequest =
+{
+  "MessageHeader": {
+    "MessageClass": "Service",
+    "MessageCategory": "TransactionStatus",
+    "MessageType": "Request",
+    "ServiceID": serviceID,
+    "SaleID": saleID,
+    "POIID": POIID,
+    "ProtocolVersion": "3.0"
+  },
+  "TransactionStatusRequest": {
+    "ReceiptReprintFlag": true,
+    "DocumentQualifier": [
+      "CashierReceipt",
+      "CustomerReceipt"
+    ],
+    "MessageReference": {
+      "SaleID": saleID,
+      # serviceID of the transaction you want the status update for
+      "ServiceID": serviceID,
+      "MessageCategory": "Payment"
+    }
+  }
+}
+
+response = adyen.terminal_cloud_api.sync(statusRequest)
+```
+
 ## Feedback
 We value your input! Help us enhance our API Libraries and improve the integration experience by providing your feedback. Please take a moment to fill out [our feedback form](https://forms.gle/A4EERrR6CWgKWe5r9) to share your thoughts, suggestions or ideas.
 
diff --git a/lib/adyen-ruby-api-library.rb b/lib/adyen-ruby-api-library.rb
@@ -19,3 +19,4 @@
 require_relative 'adyen/services/management'
 require_relative 'adyen/services/storedValue'
 require_relative 'adyen/services/balanceControlService'
+require_relative 'adyen/services/terminalCloudAPI'
diff --git a/lib/adyen/client.rb b/lib/adyen/client.rb
@@ -75,6 +75,9 @@ def service_url_base(service)
         when 'Management'
           url = "https://management-#{@env}.adyen.com"
           supports_live_url_prefix = false
+        when 'TerminalCloudAPI'
+          url = "https://terminal-api-#{@env}.adyen.com"
+          supports_live_url_prefix = false
         else
           raise ArgumentError, 'Invalid service specified'
         end
@@ -98,6 +101,8 @@ def service_url_base(service)
     def service_url(service, action, version)
       if service == "Checkout" && @env == :live
         return "#{service_url_base(service)}/checkout/v#{version}/#{action}"
+      elsif version == nil
+        return "#{service_url_base(service)}/#{action}"
       else
         return "#{service_url_base(service)}/v#{version}/#{action}"
       end
@@ -221,6 +226,9 @@ def call_adyen_api(service, action, request_data, headers, version, _with_applic
       # delete has no response.body (unless it throws an error)
       if response.body.nil? || response.body === ''
         AdyenResult.new('{}', response.headers, response.status)
+      # terminal API async call returns always 'ok'
+      elsif response.body === 'ok'
+        AdyenResult.new('{}', response.headers, response.status)
       else
         AdyenResult.new(response.body, response.headers, response.status)
       end
@@ -286,6 +294,10 @@ def stored_value
     def balance_control_service
       @balance_control_service ||= Adyen::BalanceControlService.new(self)
     end
+
+    def terminal_cloud_api
+      @terminal_cloud_api ||= Adyen::TerminalCloudAPI.new(self)
+    end
   end
 end
 # rubocop:enable all
diff --git a/lib/adyen/services/terminalCloudAPI.rb b/lib/adyen/services/terminalCloudAPI.rb
@@ -0,0 +1,38 @@
+require_relative './service'
+module Adyen
+  class TerminalCloudAPI < Service
+    attr_accessor :service
+
+    def initialize(client)
+      super(client, nil ,'TerminalCloudAPI')
+    end
+
+    def connected_terminals(request, headers: {})
+      endpoint = '/connectedTerminals'.gsub(/{.+?}/, '%s')
+      endpoint = endpoint.gsub(%r{^/}, '')
+      endpoint = format(endpoint)
+      
+      action = { method: 'post', url: endpoint }
+      @client.call_adyen_api(@service, action, request, headers, @version)
+    end
+
+    def sync(request, headers: {})
+      endpoint = '/sync'.gsub(/{.+?}/, '%s')
+      endpoint = endpoint.gsub(%r{^/}, '')
+      endpoint = format(endpoint)
+      
+      action = { method: 'post', url: endpoint }
+      @client.call_adyen_api(@service, action, request, headers, @version)
+    end
+
+    def async(request, headers: {})
+      endpoint = '/async'.gsub(/{.+?}/, '%s')
+      endpoint = endpoint.gsub(%r{^/}, '')
+      endpoint = format(endpoint)
+
+      action = { method: 'post', url: endpoint }
+      @client.call_adyen_api(@service, action, request, headers, @version)
+    end
+
+  end
+end
diff --git a/spec/client_spec.rb b/spec/client_spec.rb
@@ -236,4 +236,23 @@
     expect(client.service_url('PosTerminalManagement', 'assignTerminals', '1'))
       .to eq('https://postfmapi-test.adyen.com/postfmapi/terminal/v1/assignTerminals')
   end
+
+  it 'checks the creation of TerminalCloudAPI sync url' do
+    client = Adyen::Client.new(api_key: 'api_key', env: :test)
+    expect(client.service_url('TerminalCloudAPI', 'sync', nil))
+      .to eq('https://terminal-api-test.adyen.com/sync')
+  end
+
+  it 'checks the creation of TerminalCloudAPI async url' do
+    client = Adyen::Client.new(api_key: 'api_key', env: :test)
+    expect(client.service_url('TerminalCloudAPI', 'async', nil))
+      .to eq('https://terminal-api-test.adyen.com/async')
+  end
+
+  it 'checks the creation of TerminalCloudAPI connectedTerminals url' do
+    client = Adyen::Client.new(api_key: 'api_key', env: :test)
+    expect(client.service_url('TerminalCloudAPI', 'connectedTerminals', nil))
+      .to eq('https://terminal-api-test.adyen.com/connectedTerminals')
+      
+  end
 end
diff --git a/spec/mocks/requests/TerminalCloudAPI/connected_terminals.json b/spec/mocks/requests/TerminalCloudAPI/connected_terminals.json
@@ -0,0 +1,3 @@
+{
+    "merchantAccount": "YourMerchantAccount"
+}
diff --git a/spec/mocks/requests/TerminalCloudAPI/sync_payment.json b/spec/mocks/requests/TerminalCloudAPI/sync_payment.json
@@ -0,0 +1,29 @@
+{
+    "SaleToPOIRequest": {
+        "MessageHeader": {
+            "MessageClass": "Service",
+            "MessageCategory": "Payment",
+            "MessageType": "Request",
+            "ServiceID": "1233094855",
+            "SaleID": "POSSystemID12345",
+            "POIID": "V400m-1234123412",
+            "ProtocolVersion": "3.0"
+        },
+        "PaymentRequest": {
+            "SaleData": {
+                "SaleTransactionID": {
+                    "TransactionID": "123456764",
+                    "TimeStamp": "2023-08-23T09:48:55"
+                },
+                "SaleToAcquirerData": "eyJhcHBsaWNhdGlvbkluZm8iOnsiYWR5ZW5MaWJyYXJ5Ijp7Im5hbWUiOiJhZ....",
+                "TokenRequestedType": "Transaction"
+            },
+            "PaymentTransaction": {
+                "AmountsReq": {
+                    "Currency": "EUR",
+                    "RequestedAmount": 10
+                }
+            }
+        }
+    }
+}
diff --git a/spec/mocks/responses/TerminalCloudAPI/connected_terminals.json b/spec/mocks/responses/TerminalCloudAPI/connected_terminals.json
@@ -0,0 +1,5 @@
+{
+    "uniqueTerminalIds": [
+        "V400m-1234123412"
+    ]
+}
diff --git a/spec/mocks/responses/TerminalCloudAPI/sync_payment.json b/spec/mocks/responses/TerminalCloudAPI/sync_payment.json
@@ -0,0 +1,18 @@
+{
+    "SaleToPOIResponse":{
+      "MessageHeader":{},
+      "PaymentResponse":{
+        "POIData":{
+          "POITransactionID":{
+            "TransactionID": "oLkO0012498220087000.KHQC5N7G84BLNK43"
+          }
+        },
+        "Response":{
+          "Result":"Success",
+          "AdditionalResponse":"...shopperEmail=shoppersemail%40address.com..."
+        }
+      },
+      "PaymentReceipt":{}
+    }
+  }
+  
diff --git a/spec/terminal_cloud_api_spec.rb b/spec/terminal_cloud_api_spec.rb
@@ -0,0 +1,91 @@
+require 'spec_helper'
+require 'json'
+
+RSpec.describe Adyen::TerminalCloudAPI, service: 'TerminalCloudAPI' do
+  before(:all) do
+    @shared_values = {
+      client: create_client(:api_key),
+      service: 'TerminalCloudAPI'
+    }
+  end
+  
+  it 'makes a connectedTerminals POST call' do
+    request_body = JSON.parse(json_from_file('mocks/requests/TerminalCloudAPI/connected_terminals.json'))
+
+    response_body = json_from_file('mocks/responses/TerminalCloudAPI/connected_terminals.json')
+
+    url = @shared_values[:client].service_url(@shared_values[:service], 'connectedTerminals', nil)
+    WebMock.stub_request(:post, url)
+           .with(
+             headers: {
+               'x-api-key' => @shared_values[:client].api_key
+             }
+           )
+           .to_return(
+             body: response_body
+           )
+
+    result = @shared_values[:client].terminal_cloud_api.connected_terminals(request_body)
+    response_hash = result.response
+
+    expect(result.status)
+      .to eq(200)
+    expect(response_hash)
+      .to eq(JSON.parse(response_body))
+    expect(response_hash)
+      .to be_a Adyen::HashWithAccessors
+    expect(response_hash)
+      .to be_a_kind_of Hash
+  end
+
+  it 'makes a sync payment POST call' do
+    request_body = JSON.parse(json_from_file('mocks/requests/TerminalCloudAPI/sync_payment.json'))
+
+    response_body = json_from_file('mocks/responses/TerminalCloudAPI/sync_payment.json')
+
+    url = @shared_values[:client].service_url(@shared_values[:service], 'sync', nil)
+    WebMock.stub_request(:post, url)
+           .with(
+             headers: {
+               'x-api-key' => @shared_values[:client].api_key
+             }
+           )
+           .to_return(
+             body: response_body
+           )
+
+    result = @shared_values[:client].terminal_cloud_api.sync(request_body)
+    response_hash = result.response
+
+    expect(result.status)
+      .to eq(200)
+    expect(response_hash)
+      .to eq(JSON.parse(response_body))
+    expect(response_hash)
+      .to be_a Adyen::HashWithAccessors
+    expect(response_hash)
+      .to be_a_kind_of Hash
+  end
+
+  it 'makes an async payment POST call' do
+    request_body = JSON.parse(json_from_file('mocks/requests/TerminalCloudAPI/sync_payment.json'))
+
+    url = @shared_values[:client].service_url(@shared_values[:service], 'async', nil)
+    WebMock.stub_request(:post, url)
+           .with(
+             headers: {
+               'x-api-key' => @shared_values[:client].api_key
+             }
+           )
+           .to_return(
+             body: 'ok'
+           )
+
+    result = @shared_values[:client].terminal_cloud_api.async(request_body)
+    response_hash = result.response
+
+    expect(result.status)
+      .to eq(200)
+  end
+end
+# rubocop:enable Metrics/BlockLength

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "merchantAccount": "YourMerchantAccount"`
	`3`	`+}`
-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +{
 +    "uniqueTerminalIds": [
 +        "V400m-1234123412"
 +    ]
 +}