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
@@ -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