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
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
require 'logger'
|
|
2
|
+
require 'onlinepayments/sdk'
|
|
3
|
+
require_relative 'app_types'
|
|
4
|
+
require_relative 'create_payment_response_handler'
|
|
5
|
+
require_relative 'payment_attempt'
|
|
6
|
+
require_relative 'payment_status_example'
|
|
7
|
+
|
|
8
|
+
class ErrorHandlingExample
|
|
9
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
10
|
+
# @param orders [OrderStore]
|
|
11
|
+
# @param logger [Logger]
|
|
12
|
+
def initialize(merchant, orders, logger)
|
|
13
|
+
@merchant = merchant
|
|
14
|
+
@orders = orders
|
|
15
|
+
@logger = logger
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# [START error-handling]
|
|
19
|
+
# idempotence_key is the stored key of the payment attempt (PaymentAttempt.key_for). Reuse it when a request
|
|
20
|
+
# got no answer; replace it, stored again, only when the platform answered with an error marked retriable.
|
|
21
|
+
# @param order_id [String]
|
|
22
|
+
# @param request [OnlinePayments::SDK::Domain::CreatePaymentRequest]
|
|
23
|
+
# @param idempotence_key [String]
|
|
24
|
+
# @return [PaymentStep]
|
|
25
|
+
def create_payment(order_id, request, idempotence_key)
|
|
26
|
+
context = OnlinePayments::SDK::CallContext.new(idempotence_key)
|
|
27
|
+
attempt = 1
|
|
28
|
+
begin
|
|
29
|
+
response = merchant.payments.create_payment(request, context)
|
|
30
|
+
rescue OnlinePayments::SDK::DeclinedPaymentException => e
|
|
31
|
+
# Declined: the payment exists. Read its status before deciding anything.
|
|
32
|
+
return handle_declined(order_id, e)
|
|
33
|
+
rescue OnlinePayments::SDK::IdempotenceException
|
|
34
|
+
# The first request with this key is still running. Wait, then send the same request again.
|
|
35
|
+
raise if attempt >= 3
|
|
36
|
+
|
|
37
|
+
sleep(2 * attempt)
|
|
38
|
+
attempt += 1
|
|
39
|
+
retry
|
|
40
|
+
rescue OnlinePayments::SDK::ValidationException => e
|
|
41
|
+
# 400: the request is invalid. Fix the request; retrying does not help.
|
|
42
|
+
# Log the error codes and the error ID, never the request (it can hold card data).
|
|
43
|
+
codes = e.errors.map { |error| "#{error.error_code} #{error.property_name}" }.join('; ')
|
|
44
|
+
logger.error("create_payment rejected, error_id #{e.error_id}: #{codes}")
|
|
45
|
+
raise
|
|
46
|
+
rescue OnlinePayments::SDK::ApiException => e
|
|
47
|
+
# A technical error marked retriable (e.g. PlatformException, 500, 502 or 503): the request was not
|
|
48
|
+
# processed. Send it again with a new key. Other errors are not retried: AuthorizationException
|
|
49
|
+
# (403) for a wrong API key, secret or merchant ID, ReferenceException (404, 409,
|
|
50
|
+
# 410) for an object not found, and server errors without a retriable error.
|
|
51
|
+
raise if attempt >= 3 || e.errors.none? { |error| error.retriable == true }
|
|
52
|
+
|
|
53
|
+
# The new key is stored before the call, like the first one.
|
|
54
|
+
context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.start(order_id, orders))
|
|
55
|
+
sleep(2 * attempt)
|
|
56
|
+
attempt += 1
|
|
57
|
+
retry
|
|
58
|
+
rescue OnlinePayments::SDK::Communication::CommunicationException
|
|
59
|
+
# No answer: timeout or connection error. The payment may or may not exist.
|
|
60
|
+
# Retry with the same key; the platform returns the original result instead of creating a second
|
|
61
|
+
# payment.
|
|
62
|
+
raise if attempt >= 3
|
|
63
|
+
|
|
64
|
+
sleep(2 * attempt)
|
|
65
|
+
attempt += 1
|
|
66
|
+
retry
|
|
67
|
+
end
|
|
68
|
+
CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
|
|
69
|
+
end
|
|
70
|
+
|
|
71
|
+
private
|
|
72
|
+
|
|
73
|
+
# @param order_id [String]
|
|
74
|
+
# @param e [OnlinePayments::SDK::DeclinedPaymentException]
|
|
75
|
+
# @return [PaymentStep]
|
|
76
|
+
def handle_declined(order_id, e)
|
|
77
|
+
payment_id = e.payment_result&.payment&.id
|
|
78
|
+
if payment_id.nil?
|
|
79
|
+
orders.save_state(order_id, OrderPaymentState::FAILED)
|
|
80
|
+
return PaymentStep.new(state: OrderPaymentState::FAILED)
|
|
81
|
+
end
|
|
82
|
+
|
|
83
|
+
orders.save_payment_id(order_id, payment_id)
|
|
84
|
+
details = merchant.payments.get_payment_details(payment_id)
|
|
85
|
+
state = PaymentStatusExample.to_order_state(details.status, details.status_output)
|
|
86
|
+
orders.save_state(order_id, state)
|
|
87
|
+
PaymentStep.new(state: state)
|
|
88
|
+
end
|
|
89
|
+
# [END error-handling]
|
|
90
|
+
|
|
91
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
92
|
+
attr_reader :merchant
|
|
93
|
+
|
|
94
|
+
# @return [OrderStore]
|
|
95
|
+
attr_reader :orders
|
|
96
|
+
|
|
97
|
+
# @return [Logger]
|
|
98
|
+
attr_reader :logger
|
|
99
|
+
end
|
|
@@ -0,0 +1,181 @@
|
|
|
1
|
+
require 'logger'
|
|
2
|
+
require 'openssl'
|
|
3
|
+
require 'uri'
|
|
4
|
+
require 'onlinepayments/sdk'
|
|
5
|
+
require_relative 'app_types'
|
|
6
|
+
require_relative 'payment_status_example'
|
|
7
|
+
|
|
8
|
+
class HostedCheckoutExample
|
|
9
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
10
|
+
# @param orders [OrderStore]
|
|
11
|
+
# @param public_base_url [String] absolute public base URL of your shop from your configuration
|
|
12
|
+
# @param logger [Logger]
|
|
13
|
+
def initialize(merchant, orders, public_base_url, logger)
|
|
14
|
+
@merchant = merchant
|
|
15
|
+
@orders = orders
|
|
16
|
+
@public_base_url = public_base_url
|
|
17
|
+
@logger = logger
|
|
18
|
+
@payment_status = PaymentStatusExample.new(merchant, orders)
|
|
19
|
+
end
|
|
20
|
+
|
|
21
|
+
# [START hosted-checkout-create]
|
|
22
|
+
# Returns the URL to redirect the customer to.
|
|
23
|
+
# @param order_id [String]
|
|
24
|
+
# @param amount_in_cents [Integer]
|
|
25
|
+
# @param currency_code [String]
|
|
26
|
+
# @return [String]
|
|
27
|
+
def start_checkout(order_id, amount_in_cents, currency_code)
|
|
28
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
29
|
+
amount_of_money.amount = amount_in_cents
|
|
30
|
+
amount_of_money.currency_code = currency_code
|
|
31
|
+
|
|
32
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
33
|
+
references.merchant_reference = order_id
|
|
34
|
+
|
|
35
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
36
|
+
order.amount_of_money = amount_of_money
|
|
37
|
+
order.references = references
|
|
38
|
+
|
|
39
|
+
checkout_input = OnlinePayments::SDK::Domain::HostedCheckoutSpecificInput.new
|
|
40
|
+
checkout_input.return_url = build_return_url(order_id)
|
|
41
|
+
checkout_input.locale = 'en-GB'
|
|
42
|
+
|
|
43
|
+
request = OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest.new
|
|
44
|
+
request.order = order
|
|
45
|
+
request.hosted_checkout_specific_input = checkout_input
|
|
46
|
+
|
|
47
|
+
response = create_hosted_checkout_with_retry(request)
|
|
48
|
+
hosted_checkout_id = response.hosted_checkout_id
|
|
49
|
+
returnmac = response.returnmac
|
|
50
|
+
redirect_url = response.redirect_url
|
|
51
|
+
if hosted_checkout_id.nil? || returnmac.nil? || redirect_url.nil?
|
|
52
|
+
raise "Incomplete hosted checkout response for order #{order_id}"
|
|
53
|
+
end
|
|
54
|
+
|
|
55
|
+
# Store both values with the order before the customer leaves your site.
|
|
56
|
+
orders.save_hosted_checkout(order_id, hosted_checkout_id, returnmac)
|
|
57
|
+
# Redirect to this URL exactly as returned. Do not build it from partial_redirect_url.
|
|
58
|
+
redirect_url
|
|
59
|
+
end
|
|
60
|
+
|
|
61
|
+
# The return URL comes from your configuration (an absolute public base URL), never from the Host header of the
|
|
62
|
+
# request, which the sender controls. The order reference is escaped for the query string.
|
|
63
|
+
# @param order_id [String]
|
|
64
|
+
# @return [String]
|
|
65
|
+
def build_return_url(order_id)
|
|
66
|
+
"#{public_base_url}/return?#{URI.encode_www_form('orderId' => order_id)}"
|
|
67
|
+
end
|
|
68
|
+
# [END hosted-checkout-create]
|
|
69
|
+
|
|
70
|
+
# [START hosted-checkout-retry]
|
|
71
|
+
# CreateHostedCheckout does not support idempotent requests: the platform ignores an idempotence key, so every
|
|
72
|
+
# resend creates a new session. That is harmless until the customer pays in it; the unused session expires.
|
|
73
|
+
# Send it again after no answer or after an error marked retriable. The waiting happens inside the customer's
|
|
74
|
+
# request, so the browser waits too: keep the attempts few and the delays short, or move the call to a
|
|
75
|
+
# background job.
|
|
76
|
+
# @param request [OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest]
|
|
77
|
+
# @return [OnlinePayments::SDK::Domain::CreateHostedCheckoutResponse]
|
|
78
|
+
def create_hosted_checkout_with_retry(request)
|
|
79
|
+
attempt = 1
|
|
80
|
+
begin
|
|
81
|
+
merchant.hosted_checkout.create_hosted_checkout(request)
|
|
82
|
+
rescue OnlinePayments::SDK::ApiException => e
|
|
83
|
+
# The error of a Hosted Checkout call is a plain error response, so logging it is fine here: log at least the
|
|
84
|
+
# error ID, status and error codes.
|
|
85
|
+
codes = e.errors.map { |error| "#{error.error_code} #{error.property_name}" }.join('; ')
|
|
86
|
+
logger.error("create_hosted_checkout failed: status #{e.status_code}, error_id #{e.error_id}: #{codes}")
|
|
87
|
+
# Only an error marked retriable is sent again. Other errors reach the caller.
|
|
88
|
+
raise if attempt >= 3 || e.errors.none? { |error| error.retriable == true }
|
|
89
|
+
|
|
90
|
+
sleep(attempt)
|
|
91
|
+
attempt += 1
|
|
92
|
+
retry
|
|
93
|
+
rescue OnlinePayments::SDK::Communication::CommunicationException
|
|
94
|
+
# No answer (timeout or connection error): the session may or may not exist. Send the request again.
|
|
95
|
+
raise if attempt >= 3
|
|
96
|
+
|
|
97
|
+
sleep(attempt)
|
|
98
|
+
attempt += 1
|
|
99
|
+
retry
|
|
100
|
+
end
|
|
101
|
+
end
|
|
102
|
+
# [END hosted-checkout-retry]
|
|
103
|
+
|
|
104
|
+
# [START hosted-checkout-return]
|
|
105
|
+
# Called when the customer comes back on your return URL, e.g. with params['RETURNMAC'] in Sinatra or Rails.
|
|
106
|
+
# @param order_id [String]
|
|
107
|
+
# @param returnmac_from_query [String, nil]
|
|
108
|
+
# @return [Symbol] one of the OrderPaymentState values
|
|
109
|
+
def handle_return(order_id, returnmac_from_query)
|
|
110
|
+
stored = orders.get_hosted_checkout(order_id)
|
|
111
|
+
# The platform appends RETURNMAC to the return URL. It identifies the returning customer:
|
|
112
|
+
# a missing or different value means the request does not belong to this checkout.
|
|
113
|
+
if returnmac_from_query.nil? || returnmac_from_query.empty? ||
|
|
114
|
+
!constant_time_equal?(stored.returnmac, returnmac_from_query)
|
|
115
|
+
raise "RETURNMAC does not match the stored value for order #{order_id}"
|
|
116
|
+
end
|
|
117
|
+
|
|
118
|
+
# Never trust the redirect alone: read the result from the platform.
|
|
119
|
+
begin
|
|
120
|
+
hosted_checkout = merchant.hosted_checkout.get_hosted_checkout(stored.hosted_checkout_id)
|
|
121
|
+
rescue OnlinePayments::SDK::ReferenceException => e
|
|
122
|
+
# The API reference documents a 404 for this call. If it fails with not found, read the payment instead,
|
|
123
|
+
# with the payment ID that your webhook handler stored. Without a stored payment ID
|
|
124
|
+
# this returns :pending, and the webhook or your reconciliation job settles the order: do not mark it failed.
|
|
125
|
+
# Other errors reach the caller, including the 409 and 410 that the SDK also raises as ReferenceException.
|
|
126
|
+
raise unless e.status_code == 404
|
|
127
|
+
|
|
128
|
+
logger.warn("get_hosted_checkout failed for order #{order_id}: status #{e.status_code}, error_id #{e.error_id}")
|
|
129
|
+
return payment_status.refresh_payment_state(order_id)
|
|
130
|
+
end
|
|
131
|
+
payment = hosted_checkout.created_payment_output&.payment
|
|
132
|
+
payment_id = payment&.id
|
|
133
|
+
if hosted_checkout.status == 'PAYMENT_CREATED' && payment && payment_id
|
|
134
|
+
orders.save_payment_id(order_id, payment_id)
|
|
135
|
+
state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
|
|
136
|
+
orders.save_state(order_id, state)
|
|
137
|
+
return state
|
|
138
|
+
end
|
|
139
|
+
if hosted_checkout.status == 'CANCELLED_BY_CONSUMER'
|
|
140
|
+
# The customer cancelled, or the session expired (the created payment is then cancelled with the error id
|
|
141
|
+
# CANCELLED_BY_EXPIRATION).
|
|
142
|
+
orders.save_state(order_id, OrderPaymentState::CANCELLED)
|
|
143
|
+
return OrderPaymentState::CANCELLED
|
|
144
|
+
end
|
|
145
|
+
|
|
146
|
+
# IN_PROGRESS: the customer has not finished. A webhook will report the result.
|
|
147
|
+
OrderPaymentState::PENDING
|
|
148
|
+
end
|
|
149
|
+
|
|
150
|
+
# Compares in constant time, so the comparison does not reveal the stored value. OpenSSL.secure_compare would do
|
|
151
|
+
# this, but it does not exist on Ruby 2.3 to 2.7 (the SDK supports Ruby 2.3 and higher). Hashing both values
|
|
152
|
+
# first makes them the same length, so a different length is not visible either.
|
|
153
|
+
# @param expected [String]
|
|
154
|
+
# @param actual [String]
|
|
155
|
+
# @return [Boolean]
|
|
156
|
+
def constant_time_equal?(expected, actual)
|
|
157
|
+
expected_bytes = OpenSSL::Digest::SHA256.digest(expected).bytes
|
|
158
|
+
actual_bytes = OpenSSL::Digest::SHA256.digest(actual).bytes
|
|
159
|
+
difference = 0
|
|
160
|
+
expected_bytes.each_with_index { |byte, index| difference |= byte ^ actual_bytes.fetch(index) }
|
|
161
|
+
difference.zero?
|
|
162
|
+
end
|
|
163
|
+
# [END hosted-checkout-return]
|
|
164
|
+
|
|
165
|
+
private
|
|
166
|
+
|
|
167
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
168
|
+
attr_reader :merchant
|
|
169
|
+
|
|
170
|
+
# @return [OrderStore]
|
|
171
|
+
attr_reader :orders
|
|
172
|
+
|
|
173
|
+
# @return [String]
|
|
174
|
+
attr_reader :public_base_url
|
|
175
|
+
|
|
176
|
+
# @return [Logger]
|
|
177
|
+
attr_reader :logger
|
|
178
|
+
|
|
179
|
+
# @return [PaymentStatusExample]
|
|
180
|
+
attr_reader :payment_status
|
|
181
|
+
end
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
require_relative 'create_payment_response_handler'
|
|
4
|
+
require_relative 'payment_attempt'
|
|
5
|
+
|
|
6
|
+
class HostedFieldsExample
|
|
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 hosted-fields-create]
|
|
15
|
+
# Creates the session that the Hosted Fields script on your checkout page needs.
|
|
16
|
+
# @param checkout_page_origin [String] the origin of your checkout page, e.g. https://shop.example
|
|
17
|
+
# @return [OnlinePayments::SDK::Domain::CreateHostedFieldsSessionResponse]
|
|
18
|
+
def create_session(checkout_page_origin)
|
|
19
|
+
request = OnlinePayments::SDK::Domain::CreateHostedFieldsSessionRequest.new
|
|
20
|
+
request.locale = 'en-GB'
|
|
21
|
+
request.origin = checkout_page_origin
|
|
22
|
+
response = merchant.hosted_fields.create_hosted_fields_session(request)
|
|
23
|
+
# Send sdk_url, sdk_sri and session_data to the page. Pass session_data on unchanged
|
|
24
|
+
# (as JSON: response.session_data.to_h).
|
|
25
|
+
response
|
|
26
|
+
end
|
|
27
|
+
# [END hosted-fields-create]
|
|
28
|
+
|
|
29
|
+
# [START hosted-fields-payment]
|
|
30
|
+
# The page calls tokenize() and tells your server the card is ready.
|
|
31
|
+
# hosted_fields_session_id is hosted_fields_session_id of the create_session response; session_data.hosted_fields_session_id holds the same value.
|
|
32
|
+
# @param order_id [String]
|
|
33
|
+
# @param hosted_fields_session_id [String]
|
|
34
|
+
# @param amount_in_cents [Integer]
|
|
35
|
+
# @param currency_code [String]
|
|
36
|
+
# @param device [OnlinePayments::SDK::Domain::CustomerDevice]
|
|
37
|
+
# @param return_url [String]
|
|
38
|
+
# @return [PaymentStep]
|
|
39
|
+
def pay(order_id, hosted_fields_session_id, amount_in_cents, currency_code, device, return_url)
|
|
40
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
41
|
+
amount_of_money.amount = amount_in_cents
|
|
42
|
+
amount_of_money.currency_code = currency_code
|
|
43
|
+
|
|
44
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
45
|
+
references.merchant_reference = order_id
|
|
46
|
+
|
|
47
|
+
customer = OnlinePayments::SDK::Domain::Customer.new
|
|
48
|
+
customer.device = device
|
|
49
|
+
|
|
50
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
51
|
+
order.amount_of_money = amount_of_money
|
|
52
|
+
order.references = references
|
|
53
|
+
order.customer = customer
|
|
54
|
+
|
|
55
|
+
redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
|
|
56
|
+
redirection_data.return_url = return_url
|
|
57
|
+
three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
|
|
58
|
+
three_d_secure.redirection_data = redirection_data
|
|
59
|
+
|
|
60
|
+
card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
|
|
61
|
+
card_input.authorization_mode = 'SALE'
|
|
62
|
+
card_input.three_d_secure = three_d_secure
|
|
63
|
+
|
|
64
|
+
request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
|
|
65
|
+
request.hosted_fields_session_id = hosted_fields_session_id
|
|
66
|
+
request.order = order
|
|
67
|
+
request.card_payment_method_specific_input = card_input
|
|
68
|
+
|
|
69
|
+
context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
|
|
70
|
+
response = merchant.payments.create_payment(request, context)
|
|
71
|
+
CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
|
|
72
|
+
end
|
|
73
|
+
# [END hosted-fields-payment]
|
|
74
|
+
|
|
75
|
+
private
|
|
76
|
+
|
|
77
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
78
|
+
attr_reader :merchant
|
|
79
|
+
|
|
80
|
+
# @return [OrderStore]
|
|
81
|
+
attr_reader :orders
|
|
82
|
+
end
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
require_relative 'create_payment_response_handler'
|
|
4
|
+
require_relative 'payment_attempt'
|
|
5
|
+
|
|
6
|
+
class HostedTokenizationExample
|
|
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 hosted-tokenization-create]
|
|
15
|
+
# Creates the session for the card form iframe on your checkout page.
|
|
16
|
+
# @return [OnlinePayments::SDK::Domain::CreateHostedTokenizationResponse]
|
|
17
|
+
def create_session
|
|
18
|
+
request = OnlinePayments::SDK::Domain::CreateHostedTokenizationRequest.new
|
|
19
|
+
request.locale = 'en-GB'
|
|
20
|
+
# Optional: request.variant = 'MyTemplate.html', the file name of a custom template.
|
|
21
|
+
response = merchant.hosted_tokenization.create_hosted_tokenization(request)
|
|
22
|
+
# Send hosted_tokenization_url (iframe URL) and sri (script integrity) to the page.
|
|
23
|
+
response
|
|
24
|
+
end
|
|
25
|
+
# [END hosted-tokenization-create]
|
|
26
|
+
|
|
27
|
+
# [START hosted-tokenization-payment]
|
|
28
|
+
# The page calls tokenizer.submitTokenization() and posts result.hostedTokenizationId to your server.
|
|
29
|
+
# @param order_id [String]
|
|
30
|
+
# @param hosted_tokenization_id [String]
|
|
31
|
+
# @param amount_in_cents [Integer]
|
|
32
|
+
# @param currency_code [String]
|
|
33
|
+
# @param device [OnlinePayments::SDK::Domain::CustomerDevice]
|
|
34
|
+
# @param return_url [String]
|
|
35
|
+
# @return [PaymentStep]
|
|
36
|
+
def pay(order_id, hosted_tokenization_id, amount_in_cents, currency_code, device, return_url)
|
|
37
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
38
|
+
amount_of_money.amount = amount_in_cents
|
|
39
|
+
amount_of_money.currency_code = currency_code
|
|
40
|
+
|
|
41
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
42
|
+
references.merchant_reference = order_id
|
|
43
|
+
|
|
44
|
+
customer = OnlinePayments::SDK::Domain::Customer.new
|
|
45
|
+
customer.device = device
|
|
46
|
+
|
|
47
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
48
|
+
order.amount_of_money = amount_of_money
|
|
49
|
+
order.references = references
|
|
50
|
+
order.customer = customer
|
|
51
|
+
|
|
52
|
+
redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
|
|
53
|
+
redirection_data.return_url = return_url
|
|
54
|
+
three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
|
|
55
|
+
three_d_secure.redirection_data = redirection_data
|
|
56
|
+
|
|
57
|
+
card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
|
|
58
|
+
card_input.authorization_mode = 'SALE'
|
|
59
|
+
card_input.three_d_secure = three_d_secure
|
|
60
|
+
|
|
61
|
+
request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
|
|
62
|
+
request.hosted_tokenization_id = hosted_tokenization_id
|
|
63
|
+
request.order = order
|
|
64
|
+
request.card_payment_method_specific_input = card_input
|
|
65
|
+
|
|
66
|
+
context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
|
|
67
|
+
response = merchant.payments.create_payment(request, context)
|
|
68
|
+
CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
|
|
69
|
+
end
|
|
70
|
+
# [END hosted-tokenization-payment]
|
|
71
|
+
|
|
72
|
+
private
|
|
73
|
+
|
|
74
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
75
|
+
attr_reader :merchant
|
|
76
|
+
|
|
77
|
+
# @return [OrderStore]
|
|
78
|
+
attr_reader :orders
|
|
79
|
+
end
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
require 'securerandom'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
|
|
4
|
+
# [START payment-attempt-key]
|
|
5
|
+
# One idempotence key per payment attempt, stored with the order.
|
|
6
|
+
module PaymentAttempt
|
|
7
|
+
# Call start when the customer begins to pay, for example when you show the payment form, and again before a new
|
|
8
|
+
# attempt after a decline or a rejected request. It stores the key before any create_payment call.
|
|
9
|
+
# @param order_id [String]
|
|
10
|
+
# @param orders [OrderStore]
|
|
11
|
+
# @return [String]
|
|
12
|
+
def self.start(order_id, orders)
|
|
13
|
+
key = SecureRandom.uuid
|
|
14
|
+
orders.save_idempotence_key(order_id, key)
|
|
15
|
+
key
|
|
16
|
+
end
|
|
17
|
+
|
|
18
|
+
# The request that creates the payment reads the stored key. A double submit, a retry after a timeout and a restart
|
|
19
|
+
# then send the same key, so the platform does not create a second payment.
|
|
20
|
+
# @param order_id [String]
|
|
21
|
+
# @param orders [OrderStore]
|
|
22
|
+
# @return [String]
|
|
23
|
+
def self.key_for(order_id, orders)
|
|
24
|
+
key = orders.get_idempotence_key(order_id)
|
|
25
|
+
raise "No payment attempt was started for order #{order_id}" if key.nil?
|
|
26
|
+
|
|
27
|
+
key
|
|
28
|
+
end
|
|
29
|
+
end
|
|
30
|
+
# [END payment-attempt-key]
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
require 'date'
|
|
2
|
+
require 'onlinepayments/sdk'
|
|
3
|
+
|
|
4
|
+
class PaymentLinksExample
|
|
5
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
6
|
+
def initialize(merchant)
|
|
7
|
+
@merchant = merchant
|
|
8
|
+
end
|
|
9
|
+
|
|
10
|
+
# [START payment-link-create]
|
|
11
|
+
# Returns the link to send to the customer (email, chat, invoice).
|
|
12
|
+
# @param order_id [String]
|
|
13
|
+
# @param amount_in_cents [Integer]
|
|
14
|
+
# @param currency_code [String]
|
|
15
|
+
# @param description [String]
|
|
16
|
+
# @return [OnlinePayments::SDK::Domain::PaymentLinkResponse]
|
|
17
|
+
def create_link(order_id, amount_in_cents, currency_code, description)
|
|
18
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
19
|
+
amount_of_money.amount = amount_in_cents
|
|
20
|
+
amount_of_money.currency_code = currency_code
|
|
21
|
+
|
|
22
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
23
|
+
references.merchant_reference = order_id
|
|
24
|
+
|
|
25
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
26
|
+
order.amount_of_money = amount_of_money
|
|
27
|
+
order.references = references
|
|
28
|
+
|
|
29
|
+
link_input = OnlinePayments::SDK::Domain::PaymentLinkSpecificInput.new
|
|
30
|
+
link_input.description = description
|
|
31
|
+
# Required. A DateTime (not a Time), at most 6 months in the future.
|
|
32
|
+
link_input.expiration_date = (Time.now + (7 * 24 * 60 * 60)).to_datetime
|
|
33
|
+
|
|
34
|
+
request = OnlinePayments::SDK::Domain::CreatePaymentLinkRequest.new
|
|
35
|
+
request.order = order
|
|
36
|
+
request.payment_link_specific_input = link_input
|
|
37
|
+
|
|
38
|
+
# CreatePaymentLink does not support idempotent requests, so no idempotence key is sent.
|
|
39
|
+
link = merchant.payment_links.create_payment_link(request)
|
|
40
|
+
# Store payment_link_id with the order. Send redirection_url exactly as returned.
|
|
41
|
+
# The paymentlink.paid webhook (or get_payment_link_by_id) tells you when it is paid.
|
|
42
|
+
# Once paid, the link's payment_id has no attempt suffix: use it with "_0" appended in
|
|
43
|
+
# GetPaymentDetails, and read the payment's status.
|
|
44
|
+
link
|
|
45
|
+
end
|
|
46
|
+
# [END payment-link-create]
|
|
47
|
+
|
|
48
|
+
private
|
|
49
|
+
|
|
50
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
51
|
+
attr_reader :merchant
|
|
52
|
+
end
|
|
@@ -0,0 +1,62 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
|
|
4
|
+
class PaymentStatusExample
|
|
5
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
6
|
+
# @param orders [OrderStore]
|
|
7
|
+
def initialize(merchant, orders)
|
|
8
|
+
@merchant = merchant
|
|
9
|
+
@orders = orders
|
|
10
|
+
end
|
|
11
|
+
|
|
12
|
+
# [START payment-status]
|
|
13
|
+
# @param order_id [String]
|
|
14
|
+
# @return [Symbol] one of the OrderPaymentState values
|
|
15
|
+
def refresh_payment_state(order_id)
|
|
16
|
+
payment_id = orders.get_payment_id(order_id)
|
|
17
|
+
# No payment ID stored yet: the webhook or your reconciliation job will settle the order.
|
|
18
|
+
return OrderPaymentState::PENDING if payment_id.nil?
|
|
19
|
+
|
|
20
|
+
details = merchant.payments.get_payment_details(payment_id)
|
|
21
|
+
state = PaymentStatusExample.to_order_state(details.status, details.status_output)
|
|
22
|
+
orders.save_state(order_id, state)
|
|
23
|
+
state
|
|
24
|
+
end
|
|
25
|
+
|
|
26
|
+
# Decide on status_category. status and status_code give more detail.
|
|
27
|
+
# status_output or status_category can be missing in a response: that is pending, never paid.
|
|
28
|
+
# @param status [String, nil]
|
|
29
|
+
# @param status_output [OnlinePayments::SDK::Domain::PaymentStatusOutput, nil]
|
|
30
|
+
# @return [Symbol] one of the OrderPaymentState values
|
|
31
|
+
def self.to_order_state(status, status_output)
|
|
32
|
+
case status_output&.status_category
|
|
33
|
+
when 'COMPLETED'
|
|
34
|
+
OrderPaymentState::PAID
|
|
35
|
+
when 'PENDING_MERCHANT'
|
|
36
|
+
# PENDING_CAPTURE: authorized but not captured yet, capture or cancel it.
|
|
37
|
+
# Any other status (CANCELLED, waiting for its final result) is not final.
|
|
38
|
+
status == 'PENDING_CAPTURE' ? OrderPaymentState::AUTHORIZED : OrderPaymentState::PENDING
|
|
39
|
+
when 'REFUNDED'
|
|
40
|
+
OrderPaymentState::REFUNDED
|
|
41
|
+
when 'REVERSED'
|
|
42
|
+
# Not paid: do not treat the order as paid.
|
|
43
|
+
OrderPaymentState::REVERSED
|
|
44
|
+
when 'UNSUCCESSFUL'
|
|
45
|
+
status == 'CANCELLED' ? OrderPaymentState::CANCELLED : OrderPaymentState::FAILED
|
|
46
|
+
else
|
|
47
|
+
# CREATED, PENDING_PAYMENT, PENDING_CONNECT_OR_3RD_PARTY: not final.
|
|
48
|
+
# A missing status_output or status_category (nil) and categories added later also end up here: not paid.
|
|
49
|
+
# Wait for a webhook or check again later.
|
|
50
|
+
OrderPaymentState::PENDING
|
|
51
|
+
end
|
|
52
|
+
end
|
|
53
|
+
# [END payment-status]
|
|
54
|
+
|
|
55
|
+
private
|
|
56
|
+
|
|
57
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
58
|
+
attr_reader :merchant
|
|
59
|
+
|
|
60
|
+
# @return [OrderStore]
|
|
61
|
+
attr_reader :orders
|
|
62
|
+
end
|