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.
- checksums.yaml +4 -4
- data/AGENTS.md +23 -0
- data/README.md +22 -0
- data/lib/onlinepayments/sdk/communication/metadata_provider.rb +1 -1
- data/lib/onlinepayments/sdk/factory.rb +6 -0
- data/lib/onlinepayments/sdk/merchant/merchant_client.rb +4 -0
- data/onlinepayments-sdk-ruby.gemspec +2 -2
- data/skills/worldline-direct/SKILL.md +85 -0
- data/skills/worldline-direct/examples/after_payment_operations_example.rb +75 -0
- data/skills/worldline-direct/examples/app_types.rb +170 -0
- data/skills/worldline-direct/examples/client_integration_example.rb +76 -0
- data/skills/worldline-direct/examples/client_setup.rb +60 -0
- data/skills/worldline-direct/examples/create_payment_response_handler.rb +32 -0
- data/skills/worldline-direct/examples/customer_device.rb +32 -0
- data/skills/worldline-direct/examples/error_handling_example.rb +99 -0
- data/skills/worldline-direct/examples/hosted_checkout_example.rb +181 -0
- data/skills/worldline-direct/examples/hosted_fields_example.rb +82 -0
- data/skills/worldline-direct/examples/hosted_tokenization_example.rb +79 -0
- data/skills/worldline-direct/examples/payment_attempt.rb +30 -0
- data/skills/worldline-direct/examples/payment_links_example.rb +52 -0
- data/skills/worldline-direct/examples/payment_status_example.rb +62 -0
- data/skills/worldline-direct/examples/recurring_payments_example.rb +127 -0
- data/skills/worldline-direct/examples/server_to_server_example.rb +81 -0
- data/skills/worldline-direct/examples/webhook_event_processor.rb +40 -0
- data/skills/worldline-direct/examples/webhooks_endpoint.rb +73 -0
- data/skills/worldline-direct/examples/webhooks_setup.rb +41 -0
- data/skills/worldline-direct/references/errors.md +113 -0
- data/skills/worldline-direct/references/flows.md +966 -0
- data/skills/worldline-direct/references/ruby.md +208 -0
- data/skills/worldline-direct/references/webhooks.md +167 -0
- metadata +25 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 421b66130f7d15ee91b211d68a7997280aaa1822676e3101703eb0eb05a95d0b
|
|
4
|
+
data.tar.gz: 9fbd7a9a28ba4be33a072303c0b6965f1da0fe64cf84d7622508561d587e1d44
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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.
|
|
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
|