onlinepayments-sdk-ruby 11.0.0 → 11.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (31) hide show
  1. checksums.yaml +4 -4
  2. data/AGENTS.md +23 -0
  3. data/README.md +22 -0
  4. data/lib/onlinepayments/sdk/communication/metadata_provider.rb +1 -1
  5. data/lib/onlinepayments/sdk/factory.rb +6 -0
  6. data/lib/onlinepayments/sdk/merchant/merchant_client.rb +4 -0
  7. data/onlinepayments-sdk-ruby.gemspec +2 -2
  8. data/skills/worldline-direct/SKILL.md +85 -0
  9. data/skills/worldline-direct/examples/after_payment_operations_example.rb +75 -0
  10. data/skills/worldline-direct/examples/app_types.rb +170 -0
  11. data/skills/worldline-direct/examples/client_integration_example.rb +76 -0
  12. data/skills/worldline-direct/examples/client_setup.rb +60 -0
  13. data/skills/worldline-direct/examples/create_payment_response_handler.rb +32 -0
  14. data/skills/worldline-direct/examples/customer_device.rb +32 -0
  15. data/skills/worldline-direct/examples/error_handling_example.rb +99 -0
  16. data/skills/worldline-direct/examples/hosted_checkout_example.rb +181 -0
  17. data/skills/worldline-direct/examples/hosted_fields_example.rb +82 -0
  18. data/skills/worldline-direct/examples/hosted_tokenization_example.rb +79 -0
  19. data/skills/worldline-direct/examples/payment_attempt.rb +30 -0
  20. data/skills/worldline-direct/examples/payment_links_example.rb +52 -0
  21. data/skills/worldline-direct/examples/payment_status_example.rb +62 -0
  22. data/skills/worldline-direct/examples/recurring_payments_example.rb +127 -0
  23. data/skills/worldline-direct/examples/server_to_server_example.rb +81 -0
  24. data/skills/worldline-direct/examples/webhook_event_processor.rb +40 -0
  25. data/skills/worldline-direct/examples/webhooks_endpoint.rb +73 -0
  26. data/skills/worldline-direct/examples/webhooks_setup.rb +41 -0
  27. data/skills/worldline-direct/references/errors.md +113 -0
  28. data/skills/worldline-direct/references/flows.md +966 -0
  29. data/skills/worldline-direct/references/ruby.md +208 -0
  30. data/skills/worldline-direct/references/webhooks.md +167 -0
  31. metadata +25 -1
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: c4266190b4ed568bed352853a13fb14b6bc37ad673be2017495ab13a7d2dbf16
4
- data.tar.gz: 6dc688e03ec15ac93e97f982438f3e19ab0b7f40136611f3226845b527ba4511
3
+ metadata.gz: 421b66130f7d15ee91b211d68a7997280aaa1822676e3101703eb0eb05a95d0b
4
+ data.tar.gz: 9fbd7a9a28ba4be33a072303c0b6965f1da0fe64cf84d7622508561d587e1d44
5
5
  SHA512:
6
- metadata.gz: 296e0dff1fc016e2b917a0e90b4394ae32a185f026702613a0558eba460e2436685e3cd5f1215e0c24a3b9fa17683f4d055b2ccf29029d61fe5a63c043442e31
7
- data.tar.gz: 4aa1f5deedb96aaf114462c8791a442ce9b823c8bc478b1322885d2aeee90a2d5753d72b466b6ec31ec384d70944edeabdb76f3b0720e92946e2ebc0992a0cbd
6
+ metadata.gz: c8c3d7a3c41d5d184711b07b7a9db3c5f3bcf6a20db6485ab622333ce862ab43b490455c6be02e2bc63ad0f7e2a19b86989a07263112d0a6e2b9bf4b4b3f29e6
7
+ data.tar.gz: fd7b0e1e2fa0e1faa989d46b8b85cee85a018aa577fcb43d91a3b04b3270ae50510f2004befd08930f1210d3ed0025e3b40735f3ea7c321fe9e3458e05b875b0
data/AGENTS.md ADDED
@@ -0,0 +1,23 @@
1
+ # AGENTS.md
2
+
3
+ ## Using this SDK in your project
4
+
5
+ If you are writing code that integrates Worldline Direct with this SDK, read the agent skill
6
+ for this SDK version first and use the code it shows. Do not write SDK calls from memory.
7
+
8
+ - In this gem: `skills/worldline-direct/SKILL.md`
9
+ (gem folder: `bundle info onlinepayments-sdk-ruby --path`)
10
+ - Online: https://raw.githubusercontent.com/wl-online-payments-direct/sdk-ruby/11.1.0/skills/worldline-direct/SKILL.md
11
+
12
+ The skill matches SDK version 11.1.0. If your installed version is different, use the skill
13
+ from your installed gem.
14
+
15
+ ## Working on this SDK
16
+
17
+ - SDK source: `lib/onlinepayments/sdk/`; unit tests: `spec/lib/`; integration tests: `spec/integration/`.
18
+ - Install the test dependencies with `gem install rake rspec webmock sinatra`.
19
+ - Run the unit tests with `rake unit`, the integration tests with `rake integration`, and both with `rake spec`.
20
+ - The integration tests need the environment variables `onlinePayments_api_v1hmac_apiKeyId`,
21
+ `onlinePayments_api_v1hmac_secretApiKey` and `onlinePayments_api_merchantId`.
22
+ - Generate the documentation with `rake yard` (output in `doc/`).
23
+ - See `README.md` for details.
data/README.md CHANGED
@@ -61,6 +61,28 @@ To install the SDK using `gem`, execute the following command:
61
61
  ```
62
62
  3. Feel free to delete the unzipped archive, the zip file, and the gem file at this point; they are no longer required.
63
63
 
64
+ ## Working with AI agents
65
+
66
+ The SDK comes with an agent skill for AI coding agents such as Claude Code, Codex, GitHub Copilot and Cursor. It tells the agent how to choose an integration method, which steps each flow needs, which rules every integration must follow, and gives code examples that are type-checked against this SDK version.
67
+
68
+ The skill for this version is available:
69
+
70
+ * online, as plain Markdown for agents: https://raw.githubusercontent.com/wl-online-payments-direct/sdk-ruby/11.1.0/skills/worldline-direct/SKILL.md
71
+ * online, on GitHub: https://github.com/wl-online-payments-direct/sdk-ruby/blob/11.1.0/skills/worldline-direct/SKILL.md
72
+ * in the installed gem: `skills/worldline-direct/` in the gem folder, e.g. `vendor/bundle/ruby/<ruby version>/gems/onlinepayments-sdk-ruby-<version>/skills/worldline-direct/` when Bundler installs into `vendor/bundle`. `bundle info onlinepayments-sdk-ruby --path` prints the gem folder; without Bundler, `gem contents onlinepayments-sdk-ruby | grep SKILL.md` prints the path of the skill.
73
+ * in this repository: `skills/worldline-direct/`
74
+
75
+ To make your agent use it, add this to the `AGENTS.md` or `CLAUDE.md` file of your project:
76
+
77
+ ```
78
+ For the Worldline Direct integration (onlinepayments-sdk-ruby), read and follow the agent skill
79
+ skills/worldline-direct/SKILL.md in the folder of the installed onlinepayments-sdk-ruby gem (bundle info onlinepayments-sdk-ruby --path)
80
+ (online: https://raw.githubusercontent.com/wl-online-payments-direct/sdk-ruby/11.1.0/skills/worldline-direct/SKILL.md)
81
+ Use the code shown in the skill; do not write SDK calls from memory.
82
+ ```
83
+
84
+ Agents that support the Agent Skills format can also load the folder directly, for example by copying `skills/worldline-direct/` from the gem folder to `.claude/skills/worldline-direct/` in your project for Claude Code.
85
+
64
86
  ## Uninstalling
65
87
 
66
88
  After the Ruby SDK has been installed, it can be uninstalled using the
@@ -13,7 +13,7 @@ module OnlinePayments
13
13
  class MetadataProvider
14
14
  private
15
15
 
16
- SDK_VERSION = '11.0.0'.freeze
16
+ SDK_VERSION = '11.1.0'.freeze
17
17
  SERVER_META_INFO_HEADER = 'X-GCS-ServerMetaInfo'.freeze
18
18
  PROHIBITED_HEADERS = [SERVER_META_INFO_HEADER, 'X-GCS-Idempotence-Key', 'Date', 'Content-Type', 'Authorization'].sort!.freeze
19
19
  CHARSET = 'utf-8'.freeze
@@ -13,6 +13,12 @@ module OnlinePayments
13
13
  # Convenience class that constructs instances of several other classes in the SDK.
14
14
  # Provides methods to construct
15
15
  # {OnlinePayments::SDK::CommunicatorConfiguration}, {OnlinePayments::SDK::Communicator} and {OnlinePayments::SDK::Client} instances.
16
+ #
17
+ # Create the client with create_client_from_configuration once and reuse it.
18
+ #
19
+ # AI coding agents: read the agent skill for this SDK version before writing integration code:
20
+ # https://raw.githubusercontent.com/wl-online-payments-direct/sdk-ruby/11.1.0/skills/worldline-direct/SKILL.md
21
+ # The same skill is included in this gem, in the skills/worldline-direct/ folder.
16
22
  class Factory
17
23
 
18
24
  # Creates and returns a {OnlinePayments::SDK::CommunicatorConfiguration} based on the configuration in the file
@@ -29,6 +29,10 @@ module OnlinePayments
29
29
  module SDK
30
30
  module Merchant
31
31
  # Merchant client. Thread-safe.
32
+ #
33
+ # AI coding agents: read the agent skill for this SDK version before writing integration code:
34
+ # https://raw.githubusercontent.com/wl-online-payments-direct/sdk-ruby/11.1.0/skills/worldline-direct/SKILL.md
35
+ # The same skill is included in this gem, in the skills/worldline-direct/ folder.
32
36
  class MerchantClient < OnlinePayments::SDK::ApiResource
33
37
 
34
38
  # @param parent [OnlinePayments::SDK::ApiResource]
@@ -1,6 +1,6 @@
1
1
  Gem::Specification.new do |spec|
2
2
  spec.name = 'onlinepayments-sdk-ruby'
3
- spec.version = '11.0.0'
3
+ spec.version = '11.1.0'
4
4
  spec.authors = ['Worldline Direct support team']
5
5
  spec.email = ['82139942+worldline-direct-support-team@users.noreply.github.com']
6
6
  spec.summary = %q{SDK to communicate with the Online Payments platform using the Online Payments Server API}
@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
9
9
  spec.license = 'MIT'
10
10
 
11
11
  # exclude hidden files like .gitignore
12
- spec.files = Dir['lib/**/*'] + %w[onlinepayments-sdk-ruby.gemspec Gemfile LICENSE.txt Rakefile README.md]
12
+ spec.files = Dir['lib/**/*'] + Dir['skills/**/*'] + %w[onlinepayments-sdk-ruby.gemspec Gemfile LICENSE.txt Rakefile README.md AGENTS.md]
13
13
  spec.executables = spec.files.grep(%r{^bin\/}) { |f| File.basename(f) }
14
14
  spec.test_files = spec.files.grep(%r{^(test|spec|features)\/})
15
15
  spec.require_paths = ['lib']
@@ -0,0 +1,85 @@
1
+ ---
2
+ name: worldline-direct
3
+ description: Write and review integrations with the Worldline Direct payment platform that use the Ruby server SDK (onlinepayments-sdk-ruby). Use when code creates or changes payments, Hosted Checkout, Hosted Tokenization or Hosted Fields sessions, client SDK sessions, payment links, captures, refunds, cancellations, recurring or card-on-file payments, reads payment status, receives webhooks, or handles SDK errors.
4
+ ---
5
+
6
+ # Worldline Direct integration with the Ruby SDK
7
+
8
+ Follow this skill whenever you write or change code that calls the Worldline Direct platform through
9
+ `onlinepayments-sdk-ruby`.
10
+
11
+ ## How to work
12
+
13
+ 1. Choose the integration method with the table below. If the user has not chosen one, propose Hosted Checkout.
14
+ 2. Open `references/flows.md` and follow the steps for that method. Use the code shown there; it is copied from
15
+ examples that are compiled against this SDK. Do not write SDK calls from memory.
16
+ 3. Read `references/ruby.md` for installation, client setup and the SDK call for each API operation.
17
+ 4. Every integration also needs webhook handling (`references/webhooks.md`) and error handling
18
+ (`references/errors.md`).
19
+ 5. For fields and operations not shown in the references, check the installed SDK classes and the API reference:
20
+ https://docs.direct.worldline-solutions.com/en/api-reference. Property names in the SDK match the API reference.
21
+
22
+ The `examples/` folder has the complete source files the snippets come from, including the `using`/`import` lines.
23
+
24
+ ## Choose an integration method
25
+
26
+ | Method | Use when | Card data on your server |
27
+ |---|---|---|
28
+ | Hosted Checkout | Redirect to a payment page hosted by the platform, all payment methods. Simplest and the default. | No |
29
+ | Hosted Tokenization | Card form in an iframe on your own checkout page. | No |
30
+ | Hosted Fields | Separate card fields that you style, on your own checkout page. | No |
31
+ | Client integration | Mobile app or own form; a Client SDK encrypts the card data on the device. | Encrypted only |
32
+ | Server-to-server | You send card data or a token from your server. Card data requires PCI DSS SAQ D. | Yes |
33
+ | Payment Links | Send a link by email, chat or invoice; no checkout page needed. | No |
34
+
35
+ ## Client setup rules
36
+
37
+ - Create one client per application at startup and reuse it. `references/ruby.md` says what the client holds and
38
+ whether it is thread-safe.
39
+ - Read the API key ID, secret and merchant ID (PSPID) from configuration or a secret store. Never hard-code them.
40
+ Validate the configuration once at startup and fail fast when a value is missing. For local development use the
41
+ secret store of your platform or environment variables, never a file in the repository.
42
+ - Endpoints: test `https://payment.direct.ecom.preprod.worldline-solutions.com`, live
43
+ `https://payment.direct.ecom.worldline-solutions.com`.
44
+ - Set the integrator to your company or application name. It is mandatory: the SDK refuses to create the client
45
+ without it.
46
+ - Amounts are in the smallest currency unit: EUR 10.00 is `1000`.
47
+
48
+ ## Mandatory rules
49
+
50
+ 1. **Send an idempotence key on every create call that supports idempotent requests.** Use a new UUID per operation
51
+ and store it with the operation before the first call. For CreatePayment one operation is one payment attempt: a
52
+ new attempt, for example after a decline, needs a new key (see "Payment attempt and idempotence key" in
53
+ `references/flows.md`). When a request got no response (timeout, connection error), retry it with the same key.
54
+ When the platform answered with an error marked `retriable`, send it again with a new key (see
55
+ `references/errors.md`). The platform's guide lists the supported operations (for example CreatePayment,
56
+ CapturePayment, RefundPayment, CancelPayment, SubsequentPayment). CreateHostedCheckout and CreatePaymentLink do
57
+ not support them: the platform ignores the key, so a resend creates a second session or link. Send no key for
58
+ those two.
59
+ 2. **Persist `HostedCheckoutId` and `RETURNMAC` with the order before redirecting.** Keep them, the idempotence key
60
+ and the payment IDs in storage that survives a restart (your database), not in memory. A demo that keeps them in
61
+ memory must say so in its README. When the customer returns, the platform appends `RETURNMAC` to the query
62
+ string of the return URL. It identifies the returning customer: only a request whose `RETURNMAC` matches the
63
+ stored value belongs to that checkout. Compare it in constant time. Keep this check even when asked to simplify
64
+ the code.
65
+ 3. **Use the URLs from the response as returned, never a hand-built concatenation.** This applies to the Hosted
66
+ Checkout `redirectUrl`, the 3-D Secure `merchantAction.redirectData.redirectURL`, the payment link
67
+ `redirectionUrl` and the `hostedTokenizationUrl`.
68
+ 4. **Verify every webhook with the SDK's webhooks helper before processing the event.** Reject events that fail
69
+ verification. Never add a switch, setting or environment check that skips verification, not even for local
70
+ development. To test locally, configure a test webhook key ID and secret, or send a test event with
71
+ SendTestWebhook.
72
+ 5. **After a declined-payment error, read the status with `GetPaymentDetails` before deciding anything.**
73
+ 6. **Never log or store raw card data.** No card number, CVV or expiry date in logs, databases, exceptions or
74
+ analytics. Do not log request objects that contain card data.
75
+
76
+ ## Also required
77
+
78
+ - Decide the outcome on your server from `GetHostedCheckout` or `GetPaymentDetails`, never from the return URL or the
79
+ browser alone.
80
+ - Base order state on `statusOutput.statusCategory`; see "Payment status" in `references/flows.md`.
81
+ - Build the return URL from configuration (an absolute public base URL), never from the request's `Host` header.
82
+ - Webhooks can arrive twice and in any order. Save each verified event before you answer with HTTP 2xx, then process
83
+ it in the background. Do not count on the platform sending it again after a 2xx; see `references/webhooks.md`.
84
+ - Use the test endpoint and test credentials until the user explicitly asks for live.
85
+ - Documentation: https://docs.direct.worldline-solutions.com
@@ -0,0 +1,75 @@
1
+ require 'onlinepayments/sdk'
2
+
3
+ # Each method takes an idempotence key. Create it once per operation (e.g. when someone clicks "Refund") and store it.
4
+ # Pass the same key again if the request got no answer; see ErrorHandlingExample.
5
+ class AfterPaymentOperationsExample
6
+ # @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
7
+ def initialize(merchant)
8
+ @merchant = merchant
9
+ end
10
+
11
+ # [START capture-payment]
12
+ # Captures an authorized payment (status PENDING_CAPTURE). Without an amount, the full amount is captured.
13
+ # @param payment_id [String]
14
+ # @param amount_in_cents [Integer]
15
+ # @param is_final [Boolean] true: this capture is final, no further capture is accepted.
16
+ # @param idempotence_key [String]
17
+ # @return [OnlinePayments::SDK::Domain::CaptureResponse]
18
+ def capture(payment_id, amount_in_cents, is_final, idempotence_key)
19
+ details = merchant.payments.get_payment_details(payment_id)
20
+ raise "Payment #{payment_id} cannot be captured in status #{details.status}" if details.status != 'PENDING_CAPTURE'
21
+
22
+ request = OnlinePayments::SDK::Domain::CapturePaymentRequest.new
23
+ request.amount = amount_in_cents
24
+ request.is_final = is_final
25
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
26
+ merchant.payments.capture_payment(payment_id, request, context)
27
+ end
28
+ # [END capture-payment]
29
+
30
+ # [START refund-payment]
31
+ # Refunds a captured payment, fully or partly.
32
+ # @param payment_id [String]
33
+ # @param amount_in_cents [Integer]
34
+ # @param currency_code [String]
35
+ # @param idempotence_key [String]
36
+ # @return [OnlinePayments::SDK::Domain::RefundResponse]
37
+ def refund(payment_id, amount_in_cents, currency_code, idempotence_key)
38
+ details = merchant.payments.get_payment_details(payment_id)
39
+ unless details.status_output&.is_refundable == true
40
+ raise "Payment #{payment_id} is not refundable in status #{details.status}"
41
+ end
42
+
43
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
44
+ amount_of_money.amount = amount_in_cents
45
+ amount_of_money.currency_code = currency_code
46
+ request = OnlinePayments::SDK::Domain::RefundRequest.new
47
+ request.amount_of_money = amount_of_money
48
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
49
+ # REFUND_REQUESTED: the platform is processing the refund and waiting for the result. The status then becomes
50
+ # REFUNDED or REJECTED; treat the refund as done only when it is REFUNDED.
51
+ merchant.payments.refund_payment(payment_id, request, context)
52
+ end
53
+ # [END refund-payment]
54
+
55
+ # [START cancel-payment]
56
+ # Cancels (voids) an authorization that is not captured yet. No amount cancels the full amount.
57
+ # @param payment_id [String]
58
+ # @param idempotence_key [String]
59
+ # @return [OnlinePayments::SDK::Domain::CancelPaymentResponse]
60
+ def cancel(payment_id, idempotence_key)
61
+ details = merchant.payments.get_payment_details(payment_id)
62
+ unless details.status_output&.is_cancellable == true
63
+ raise "Payment #{payment_id} is not cancellable in status #{details.status}"
64
+ end
65
+
66
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
67
+ merchant.payments.cancel_payment(payment_id, OnlinePayments::SDK::Domain::CancelPaymentRequest.new, context)
68
+ end
69
+ # [END cancel-payment]
70
+
71
+ private
72
+
73
+ # @return [OnlinePayments::SDK::Merchant::MerchantClient]
74
+ attr_reader :merchant
75
+ end
@@ -0,0 +1,170 @@
1
+ # Stand-ins for your application's own types and persistence. The examples use them where your code must store or read
2
+ # data; replace them with your own code.
3
+
4
+ # The payment state of an order in your application.
5
+ module OrderPaymentState
6
+ PENDING = :pending
7
+ AUTHORIZED = :authorized
8
+ PAID = :paid
9
+ FAILED = :failed
10
+ CANCELLED = :cancelled
11
+ REFUNDED = :refunded
12
+ REVERSED = :reversed
13
+ end
14
+
15
+ # What the web layer must do after a create payment call: redirect the customer to redirect_url, or show the state.
16
+ class PaymentStep
17
+ # @param redirect_url [String, nil]
18
+ # @param state [Symbol, nil] one of the OrderPaymentState values
19
+ def initialize(redirect_url: nil, state: nil)
20
+ @redirect_url = redirect_url
21
+ @state = state
22
+ end
23
+
24
+ # @return [String, nil]
25
+ attr_reader :redirect_url
26
+
27
+ # @return [Symbol, nil]
28
+ attr_reader :state
29
+ end
30
+
31
+ class StoredHostedCheckout
32
+ # @param hosted_checkout_id [String]
33
+ # @param returnmac [String]
34
+ def initialize(hosted_checkout_id, returnmac)
35
+ @hosted_checkout_id = hosted_checkout_id
36
+ @returnmac = returnmac
37
+ end
38
+
39
+ # @return [String]
40
+ attr_reader :hosted_checkout_id
41
+
42
+ # @return [String]
43
+ attr_reader :returnmac
44
+ end
45
+
46
+ # Stand-in for your database code.
47
+ class OrderStore
48
+ # @param order_id [String]
49
+ # @param hosted_checkout_id [String]
50
+ # @param returnmac [String]
51
+ # @return [void]
52
+ def save_hosted_checkout(order_id, hosted_checkout_id, returnmac)
53
+ raise NotImplementedError
54
+ end
55
+
56
+ # @param order_id [String]
57
+ # @return [StoredHostedCheckout]
58
+ def get_hosted_checkout(order_id)
59
+ raise NotImplementedError
60
+ end
61
+
62
+ # The idempotence key of the create call for this order. Store it before the call.
63
+ # @param order_id [String]
64
+ # @param idempotence_key [String]
65
+ # @return [void]
66
+ def save_idempotence_key(order_id, idempotence_key)
67
+ raise NotImplementedError
68
+ end
69
+
70
+ # @param order_id [String]
71
+ # @return [String, nil]
72
+ def get_idempotence_key(order_id)
73
+ raise NotImplementedError
74
+ end
75
+
76
+ # @param order_id [String]
77
+ # @param payment_id [String]
78
+ # @return [void]
79
+ def save_payment_id(order_id, payment_id)
80
+ raise NotImplementedError
81
+ end
82
+
83
+ # @param order_id [String]
84
+ # @return [String, nil] nil while no payment ID is stored yet
85
+ def get_payment_id(order_id)
86
+ raise NotImplementedError
87
+ end
88
+
89
+ # @param order_id [String]
90
+ # @param state [Symbol] one of the OrderPaymentState values
91
+ # @return [void]
92
+ def save_state(order_id, state)
93
+ raise NotImplementedError
94
+ end
95
+
96
+ # @param customer_id [String]
97
+ # @param initial_payment_id [String]
98
+ # @return [void]
99
+ def save_recurring_payment_id(customer_id, initial_payment_id)
100
+ raise NotImplementedError
101
+ end
102
+
103
+ # @param customer_id [String]
104
+ # @return [String]
105
+ def get_recurring_payment_id(customer_id)
106
+ raise NotImplementedError
107
+ end
108
+ end
109
+
110
+ # Browser values collected with JavaScript on the checkout page.
111
+ class BrowserInfo
112
+ # @param color_depth [Integer]
113
+ # @param java_enabled [Boolean]
114
+ # @param screen_height [Integer]
115
+ # @param screen_width [Integer]
116
+ # @param timezone_offset_utc_minutes [Integer]
117
+ # @param locale [String]
118
+ def initialize(color_depth:, java_enabled:, screen_height:, screen_width:, timezone_offset_utc_minutes:, locale:)
119
+ @color_depth = color_depth
120
+ @java_enabled = java_enabled
121
+ @screen_height = screen_height
122
+ @screen_width = screen_width
123
+ @timezone_offset_utc_minutes = timezone_offset_utc_minutes
124
+ @locale = locale
125
+ end
126
+
127
+ # @return [Integer]
128
+ attr_reader :color_depth
129
+
130
+ # @return [Boolean]
131
+ attr_reader :java_enabled
132
+
133
+ # @return [Integer]
134
+ attr_reader :screen_height
135
+
136
+ # @return [Integer]
137
+ attr_reader :screen_width
138
+
139
+ # @return [Integer]
140
+ attr_reader :timezone_offset_utc_minutes
141
+
142
+ # @return [String]
143
+ attr_reader :locale
144
+ end
145
+
146
+ # Card details as entered by the customer. Never log or store this object.
147
+ class CardInput
148
+ # @param number [String]
149
+ # @param holder_name [String]
150
+ # @param expiry_date [String] MMYY, e.g. 1230 for December 2030.
151
+ # @param cvv [String]
152
+ def initialize(number:, holder_name:, expiry_date:, cvv:)
153
+ @number = number
154
+ @holder_name = holder_name
155
+ @expiry_date = expiry_date
156
+ @cvv = cvv
157
+ end
158
+
159
+ # @return [String]
160
+ attr_reader :number
161
+
162
+ # @return [String]
163
+ attr_reader :holder_name
164
+
165
+ # @return [String]
166
+ attr_reader :expiry_date
167
+
168
+ # @return [String]
169
+ attr_reader :cvv
170
+ end
@@ -0,0 +1,76 @@
1
+ require 'onlinepayments/sdk'
2
+ require_relative 'app_types'
3
+ require_relative 'create_payment_response_handler'
4
+ require_relative 'payment_attempt'
5
+
6
+ class ClientIntegrationExample
7
+ # @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
8
+ # @param orders [OrderStore]
9
+ def initialize(merchant, orders)
10
+ @merchant = merchant
11
+ @orders = orders
12
+ end
13
+
14
+ # [START client-session-create]
15
+ # Creates the session that a Client SDK (JavaScript, iOS, Android, Flutter...) needs to encrypt card data.
16
+ # @return [OnlinePayments::SDK::Domain::SessionResponse]
17
+ def create_client_session
18
+ session = merchant.sessions.create_session(OnlinePayments::SDK::Domain::SessionRequest.new)
19
+ # Send client_session_id, customer_id, client_api_url and asset_url to the app. Never send your API key.
20
+ session
21
+ end
22
+ # [END client-session-create]
23
+
24
+ # [START client-encrypted-payment]
25
+ # The Client SDK returns an encrypted string; the app posts it to your server.
26
+ # @param order_id [String]
27
+ # @param encrypted_customer_input [String]
28
+ # @param amount_in_cents [Integer]
29
+ # @param currency_code [String]
30
+ # @param device [OnlinePayments::SDK::Domain::CustomerDevice]
31
+ # @param return_url [String]
32
+ # @return [PaymentStep]
33
+ def pay(order_id, encrypted_customer_input, amount_in_cents, currency_code, device, return_url)
34
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
35
+ amount_of_money.amount = amount_in_cents
36
+ amount_of_money.currency_code = currency_code
37
+
38
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
39
+ references.merchant_reference = order_id
40
+
41
+ customer = OnlinePayments::SDK::Domain::Customer.new
42
+ customer.device = device
43
+
44
+ order = OnlinePayments::SDK::Domain::Order.new
45
+ order.amount_of_money = amount_of_money
46
+ order.references = references
47
+ order.customer = customer
48
+
49
+ redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
50
+ redirection_data.return_url = return_url
51
+ three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
52
+ three_d_secure.redirection_data = redirection_data
53
+
54
+ card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
55
+ card_input.authorization_mode = 'SALE'
56
+ card_input.three_d_secure = three_d_secure
57
+
58
+ request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
59
+ request.encrypted_customer_input = encrypted_customer_input
60
+ request.order = order
61
+ request.card_payment_method_specific_input = card_input
62
+
63
+ context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
64
+ response = merchant.payments.create_payment(request, context)
65
+ CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
66
+ end
67
+ # [END client-encrypted-payment]
68
+
69
+ private
70
+
71
+ # @return [OnlinePayments::SDK::Merchant::MerchantClient]
72
+ attr_reader :merchant
73
+
74
+ # @return [OrderStore]
75
+ attr_reader :orders
76
+ end
@@ -0,0 +1,60 @@
1
+ require 'uri'
2
+ require 'onlinepayments/sdk'
3
+
4
+ module ClientSetup
5
+ # [START client-setup]
6
+ # Create the client once when the application starts, reuse it for every request and close it on shutdown.
7
+ # Every value is validated here, so a wrong configuration stops the application at startup.
8
+ # @return [OnlinePayments::SDK::Client]
9
+ def self.create_client
10
+ configuration = OnlinePayments::SDK::CommunicatorConfiguration.new(
11
+ # Test or live host, e.g. payment.direct.ecom.preprod.worldline-solutions.com (without a path).
12
+ api_endpoint: "https://#{required_env('onlinePayments_api_endpoint_host')}",
13
+ api_key_id: required_env('onlinePayments_api_v1hmac_apiKeyId'),
14
+ secret_api_key: required_env('onlinePayments_api_v1hmac_secretApiKey'),
15
+ # Required: without it, creating the client raises RuntimeError "Unknown authorizationType".
16
+ authorization_type: OnlinePayments::SDK::Authentication::AuthorizationType::V1HMAC,
17
+ # Your company or application name; it identifies your requests in the platform logs.
18
+ # Required: without it, the SDK raises ArgumentError "integrator is required".
19
+ integrator: required_env('onlinePayments_api_integrator'),
20
+ # In seconds.
21
+ connect_timeout: 5,
22
+ socket_timeout: 300,
23
+ max_connections: 10
24
+ )
25
+ OnlinePayments::SDK::Factory.create_client_from_configuration(configuration)
26
+ end
27
+
28
+ # The merchant ID is your PSPID. All API calls start from the merchant client.
29
+ # @param client [OnlinePayments::SDK::Client]
30
+ # @return [OnlinePayments::SDK::Merchant::MerchantClient]
31
+ def self.create_merchant_client(client)
32
+ client.merchant(required_env('onlinePayments_api_merchantId'))
33
+ end
34
+
35
+ # The absolute public base URL of your shop, e.g. https://shop.example. The return URL of a checkout is built from
36
+ # it, never from the Host header of a request, which the sender controls.
37
+ # @return [String] without a trailing slash
38
+ def self.public_base_url
39
+ value = required_env('shop_publicBaseUrl')
40
+ uri = URI.parse(value)
41
+ unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty? && uri.query.nil? && uri.fragment.nil?
42
+ raise "shop_publicBaseUrl must be an absolute http(s) URL without query or fragment, e.g. https://shop.example"
43
+ end
44
+
45
+ value.strip.chomp('/')
46
+ end
47
+
48
+ # Read credentials from the environment or, better, a secret store of your platform, and never hard-code them.
49
+ # For local development keep them in your own environment or a local secret store, not in a file in the repository.
50
+ # A blank value counts as missing.
51
+ # @param name [String]
52
+ # @return [String]
53
+ def self.required_env(name)
54
+ value = ENV[name]
55
+ raise "Environment variable #{name} is not set" if value.nil? || value.strip.empty?
56
+
57
+ value
58
+ end
59
+ # [END client-setup]
60
+ end
@@ -0,0 +1,32 @@
1
+ require 'onlinepayments/sdk'
2
+ require_relative 'app_types'
3
+ require_relative 'payment_status_example'
4
+
5
+ module CreatePaymentResponseHandler
6
+ # [START payment-response-handle]
7
+ # Use for every create_payment response: server-to-server, Hosted Tokenization, Hosted Fields and client integration.
8
+ # @param response [OnlinePayments::SDK::Domain::CreatePaymentResponse]
9
+ # @param order_id [String]
10
+ # @param orders [OrderStore]
11
+ # @return [PaymentStep]
12
+ def self.handle_create_payment_response(response, order_id, orders)
13
+ payment = response.payment
14
+ payment_id = payment&.id
15
+ raise "The create payment response for order #{order_id} has no payment" if payment.nil? || payment_id.nil?
16
+
17
+ orders.save_payment_id(order_id, payment_id)
18
+
19
+ redirect_url = response.merchant_action&.redirect_data&.redirect_url
20
+ if response.merchant_action&.action_type == 'REDIRECT' && redirect_url && !redirect_url.empty?
21
+ # 3-D Secure challenge or a third-party page. Redirect to the URL exactly as returned.
22
+ # The customer comes back on your return URL; then read the status with get_payment_details.
23
+ return PaymentStep.new(redirect_url: redirect_url)
24
+ end
25
+
26
+ # No customer action needed: the result is already known.
27
+ state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
28
+ orders.save_state(order_id, state)
29
+ PaymentStep.new(state: state)
30
+ end
31
+ # [END payment-response-handle]
32
+ end
@@ -0,0 +1,32 @@
1
+ require 'onlinepayments/sdk'
2
+ require_relative 'app_types'
3
+
4
+ module CustomerDeviceBuilder
5
+ # [START customer-device]
6
+ # 3-D Secure needs details about the customer's browser. Collect the browser values with JavaScript on the checkout
7
+ # page and read the rest from the HTTP request (e.g. in Sinatra or Rails: request.env['HTTP_ACCEPT'],
8
+ # request.user_agent, request.ip).
9
+ # @param accept_header [String]
10
+ # @param user_agent [String]
11
+ # @param ip_address [String]
12
+ # @param browser [BrowserInfo]
13
+ # @return [OnlinePayments::SDK::Domain::CustomerDevice]
14
+ def self.build_customer_device(accept_header, user_agent, ip_address, browser)
15
+ browser_data = OnlinePayments::SDK::Domain::BrowserData.new
16
+ browser_data.color_depth = browser.color_depth
17
+ browser_data.java_enabled = browser.java_enabled
18
+ browser_data.java_script_enabled = true
19
+ browser_data.screen_height = browser.screen_height.to_s
20
+ browser_data.screen_width = browser.screen_width.to_s
21
+
22
+ device = OnlinePayments::SDK::Domain::CustomerDevice.new
23
+ device.accept_header = accept_header
24
+ device.user_agent = user_agent
25
+ device.ip_address = ip_address
26
+ device.locale = browser.locale
27
+ device.timezone_offset_utc_minutes = browser.timezone_offset_utc_minutes.to_s
28
+ device.browser_data = browser_data
29
+ device
30
+ end
31
+ # [END customer-device]
32
+ end