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,127 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
require_relative 'hosted_checkout_example'
|
|
4
|
+
require_relative 'payment_status_example'
|
|
5
|
+
|
|
6
|
+
class RecurringPaymentsExample
|
|
7
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
8
|
+
# @param orders [OrderStore]
|
|
9
|
+
# @param hosted_checkout [HostedCheckoutExample] provides the return URL and the create call with retries
|
|
10
|
+
def initialize(merchant, orders, hosted_checkout)
|
|
11
|
+
@merchant = merchant
|
|
12
|
+
@orders = orders
|
|
13
|
+
@hosted_checkout = hosted_checkout
|
|
14
|
+
end
|
|
15
|
+
|
|
16
|
+
# [START recurring-first]
|
|
17
|
+
# First payment of a subscription, made by the customer on the Hosted Checkout Page.
|
|
18
|
+
# The recurring flag marks it as the first payment of the series.
|
|
19
|
+
# It follows the Hosted Checkout flow: the return URL is built from your configuration and the call goes through
|
|
20
|
+
# the same retry helper. Handle the return as there.
|
|
21
|
+
# @param order_id [String]
|
|
22
|
+
# @param amount_in_cents [Integer]
|
|
23
|
+
# @param currency_code [String]
|
|
24
|
+
# @return [String] the URL to redirect the customer to
|
|
25
|
+
def start_subscription(order_id, amount_in_cents, currency_code)
|
|
26
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
27
|
+
amount_of_money.amount = amount_in_cents
|
|
28
|
+
amount_of_money.currency_code = currency_code
|
|
29
|
+
|
|
30
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
31
|
+
references.merchant_reference = order_id
|
|
32
|
+
|
|
33
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
34
|
+
order.amount_of_money = amount_of_money
|
|
35
|
+
order.references = references
|
|
36
|
+
|
|
37
|
+
checkout_input = OnlinePayments::SDK::Domain::HostedCheckoutSpecificInput.new
|
|
38
|
+
# The return URL is built from your configured public base URL, as in the Hosted Checkout flow.
|
|
39
|
+
checkout_input.return_url = hosted_checkout.build_return_url(order_id)
|
|
40
|
+
checkout_input.is_recurring = true
|
|
41
|
+
|
|
42
|
+
request = OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest.new
|
|
43
|
+
request.order = order
|
|
44
|
+
request.hosted_checkout_specific_input = checkout_input
|
|
45
|
+
|
|
46
|
+
response = hosted_checkout.create_hosted_checkout_with_retry(request)
|
|
47
|
+
hosted_checkout_id = response.hosted_checkout_id
|
|
48
|
+
returnmac = response.returnmac
|
|
49
|
+
redirect_url = response.redirect_url
|
|
50
|
+
if hosted_checkout_id.nil? || returnmac.nil? || redirect_url.nil?
|
|
51
|
+
raise "Incomplete hosted checkout response for order #{order_id}"
|
|
52
|
+
end
|
|
53
|
+
|
|
54
|
+
orders.save_hosted_checkout(order_id, hosted_checkout_id, returnmac)
|
|
55
|
+
redirect_url
|
|
56
|
+
end
|
|
57
|
+
|
|
58
|
+
# When the first payment is authorised or captured, keep its payment ID: later charges refer to it.
|
|
59
|
+
# @param customer_id [String]
|
|
60
|
+
# @param first_payment_id [String]
|
|
61
|
+
# @return [void]
|
|
62
|
+
def on_first_payment_succeeded(customer_id, first_payment_id)
|
|
63
|
+
orders.save_recurring_payment_id(customer_id, first_payment_id)
|
|
64
|
+
end
|
|
65
|
+
# [END recurring-first]
|
|
66
|
+
|
|
67
|
+
# [START recurring-subsequent]
|
|
68
|
+
# Later charge started by you, without the customer (merchant-initiated).
|
|
69
|
+
# The caller creates ONE idempotence key per charge and stores it with the charge (orders.save_idempotence_key)
|
|
70
|
+
# before the first call. Retries of the same charge reuse that key; the rules are in the error handling example.
|
|
71
|
+
# @param customer_id [String]
|
|
72
|
+
# @param order_id [String]
|
|
73
|
+
# @param amount_in_cents [Integer]
|
|
74
|
+
# @param currency_code [String]
|
|
75
|
+
# @param idempotence_key [String]
|
|
76
|
+
# @return [Symbol] one of the OrderPaymentState values
|
|
77
|
+
def charge_renewal(customer_id, order_id, amount_in_cents, currency_code, idempotence_key)
|
|
78
|
+
first_payment_id = orders.get_recurring_payment_id(customer_id)
|
|
79
|
+
|
|
80
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
81
|
+
amount_of_money.amount = amount_in_cents
|
|
82
|
+
amount_of_money.currency_code = currency_code
|
|
83
|
+
|
|
84
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
85
|
+
references.merchant_reference = order_id
|
|
86
|
+
|
|
87
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
88
|
+
order.amount_of_money = amount_of_money
|
|
89
|
+
order.references = references
|
|
90
|
+
|
|
91
|
+
card_input = OnlinePayments::SDK::Domain::SubsequentCardPaymentMethodSpecificInput.new
|
|
92
|
+
# Recurring = fixed amount, regular intervals (at most one year), started by you.
|
|
93
|
+
# Other allowed values: Unscheduled, Installment, NoShow, DelayedCharge, PartialShipment,
|
|
94
|
+
# Resubmission, RecurringVariable, UnscheduledFixed.
|
|
95
|
+
card_input.subsequent_type = 'Recurring'
|
|
96
|
+
# SALE: authorised and captured at once. Acquirers that do not support it ignore it.
|
|
97
|
+
card_input.authorization_mode = 'SALE'
|
|
98
|
+
|
|
99
|
+
request = OnlinePayments::SDK::Domain::SubsequentPaymentRequest.new
|
|
100
|
+
request.order = order
|
|
101
|
+
request.subsequentcard_payment_method_specific_input = card_input
|
|
102
|
+
|
|
103
|
+
context = OnlinePayments::SDK::CallContext.new(idempotence_key)
|
|
104
|
+
# A declined charge raises DeclinedPaymentException, as for create_payment.
|
|
105
|
+
response = merchant.subsequent.subsequent_payment(first_payment_id, request, context)
|
|
106
|
+
payment = response.payment
|
|
107
|
+
payment_id = payment&.id
|
|
108
|
+
raise "The subsequent payment response for order #{order_id} has no payment" if payment.nil? || payment_id.nil?
|
|
109
|
+
|
|
110
|
+
orders.save_payment_id(order_id, payment_id)
|
|
111
|
+
state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
|
|
112
|
+
orders.save_state(order_id, state)
|
|
113
|
+
state
|
|
114
|
+
end
|
|
115
|
+
# [END recurring-subsequent]
|
|
116
|
+
|
|
117
|
+
private
|
|
118
|
+
|
|
119
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
120
|
+
attr_reader :merchant
|
|
121
|
+
|
|
122
|
+
# @return [OrderStore]
|
|
123
|
+
attr_reader :orders
|
|
124
|
+
|
|
125
|
+
# @return [HostedCheckoutExample]
|
|
126
|
+
attr_reader :hosted_checkout
|
|
127
|
+
end
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
require_relative 'create_payment_response_handler'
|
|
4
|
+
require_relative 'payment_attempt'
|
|
5
|
+
|
|
6
|
+
class ServerToServerExample
|
|
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 server-to-server-create]
|
|
15
|
+
# Card data on your server puts you in scope of PCI DSS SAQ D.
|
|
16
|
+
# Use Hosted Tokenization or Hosted Fields unless you are certified for it.
|
|
17
|
+
# @param order_id [String]
|
|
18
|
+
# @param amount_in_cents [Integer]
|
|
19
|
+
# @param currency_code [String]
|
|
20
|
+
# @param payment_product_id [Integer] e.g. 1 = Visa, 3 = Mastercard.
|
|
21
|
+
# @param card [CardInput]
|
|
22
|
+
# @param device [OnlinePayments::SDK::Domain::CustomerDevice]
|
|
23
|
+
# @param return_url [String]
|
|
24
|
+
# @return [PaymentStep]
|
|
25
|
+
def pay_with_card(order_id, amount_in_cents, currency_code, payment_product_id, card, device, return_url)
|
|
26
|
+
amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
|
|
27
|
+
amount_of_money.amount = amount_in_cents
|
|
28
|
+
amount_of_money.currency_code = currency_code
|
|
29
|
+
|
|
30
|
+
references = OnlinePayments::SDK::Domain::OrderReferences.new
|
|
31
|
+
references.merchant_reference = order_id
|
|
32
|
+
|
|
33
|
+
customer = OnlinePayments::SDK::Domain::Customer.new
|
|
34
|
+
customer.device = device
|
|
35
|
+
|
|
36
|
+
order = OnlinePayments::SDK::Domain::Order.new
|
|
37
|
+
order.amount_of_money = amount_of_money
|
|
38
|
+
order.references = references
|
|
39
|
+
order.customer = customer
|
|
40
|
+
|
|
41
|
+
card_data = OnlinePayments::SDK::Domain::Card.new
|
|
42
|
+
card_data.card_number = card.number
|
|
43
|
+
card_data.cardholder_name = card.holder_name
|
|
44
|
+
card_data.expiry_date = card.expiry_date
|
|
45
|
+
card_data.cvv = card.cvv
|
|
46
|
+
|
|
47
|
+
redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
|
|
48
|
+
redirection_data.return_url = return_url
|
|
49
|
+
three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
|
|
50
|
+
three_d_secure.redirection_data = redirection_data
|
|
51
|
+
|
|
52
|
+
card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
|
|
53
|
+
card_input.payment_product_id = payment_product_id
|
|
54
|
+
card_input.card = card_data
|
|
55
|
+
# SALE: authorised and captured at once. Acquirers that do not support it ignore it.
|
|
56
|
+
# FINAL_AUTHORIZATION: capture the full amount within 7 days.
|
|
57
|
+
# PRE_AUTHORIZATION: can be reversed; capture the authorised amount or less within 30 days.
|
|
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.order = order
|
|
63
|
+
request.card_payment_method_specific_input = card_input
|
|
64
|
+
|
|
65
|
+
# The idempotence key is a positional argument.
|
|
66
|
+
context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
|
|
67
|
+
# Raises DeclinedPaymentException if the payment is declined, and other ApiException subclasses for errors;
|
|
68
|
+
# see ErrorHandlingExample for handling each case.
|
|
69
|
+
response = merchant.payments.create_payment(request, context)
|
|
70
|
+
CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
|
|
71
|
+
end
|
|
72
|
+
# [END server-to-server-create]
|
|
73
|
+
|
|
74
|
+
private
|
|
75
|
+
|
|
76
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
77
|
+
attr_reader :merchant
|
|
78
|
+
|
|
79
|
+
# @return [OrderStore]
|
|
80
|
+
attr_reader :orders
|
|
81
|
+
end
|
|
@@ -0,0 +1,40 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'app_types'
|
|
3
|
+
require_relative 'payment_status_example'
|
|
4
|
+
|
|
5
|
+
class WebhookEventProcessor
|
|
6
|
+
# @param merchant [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
7
|
+
# @param orders [OrderStore]
|
|
8
|
+
def initialize(merchant, orders)
|
|
9
|
+
@merchant = merchant
|
|
10
|
+
@orders = orders
|
|
11
|
+
end
|
|
12
|
+
|
|
13
|
+
# [START webhooks-process]
|
|
14
|
+
# Runs in the background. Events can arrive twice and out of order, so read the current
|
|
15
|
+
# status instead of trusting the event; repeating this is harmless.
|
|
16
|
+
# @param webhooks_event [OnlinePayments::SDK::Webhooks::WebhooksEvent]
|
|
17
|
+
# @return [void]
|
|
18
|
+
def process(webhooks_event)
|
|
19
|
+
payment = webhooks_event.payment
|
|
20
|
+
payment_id = payment&.id
|
|
21
|
+
# Refund, payment link, payout and token events carry other objects, e.g. webhooks_event.refund.
|
|
22
|
+
return if payment.nil? || payment_id.nil?
|
|
23
|
+
|
|
24
|
+
order_id = payment.payment_output&.references&.merchant_reference
|
|
25
|
+
return if order_id.nil? || order_id.empty?
|
|
26
|
+
|
|
27
|
+
details = merchant.payments.get_payment_details(payment_id)
|
|
28
|
+
orders.save_payment_id(order_id, details.id || payment_id)
|
|
29
|
+
orders.save_state(order_id, PaymentStatusExample.to_order_state(details.status, details.status_output))
|
|
30
|
+
end
|
|
31
|
+
# [END webhooks-process]
|
|
32
|
+
|
|
33
|
+
private
|
|
34
|
+
|
|
35
|
+
# @return [OnlinePayments::SDK::Merchant::MerchantClient]
|
|
36
|
+
attr_reader :merchant
|
|
37
|
+
|
|
38
|
+
# @return [OrderStore]
|
|
39
|
+
attr_reader :orders
|
|
40
|
+
end
|
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
require 'logger'
|
|
2
|
+
require 'onlinepayments/sdk'
|
|
3
|
+
require_relative 'webhooks_setup'
|
|
4
|
+
|
|
5
|
+
class WebhooksEndpoint
|
|
6
|
+
# @param webhooks_helper [OnlinePayments::SDK::Webhooks::WebhooksHelper]
|
|
7
|
+
# @param inbox [WebhookInbox]
|
|
8
|
+
# @param logger [Logger]
|
|
9
|
+
def initialize(webhooks_helper, inbox, logger)
|
|
10
|
+
@webhooks_helper = webhooks_helper
|
|
11
|
+
@inbox = inbox
|
|
12
|
+
@logger = logger
|
|
13
|
+
end
|
|
14
|
+
|
|
15
|
+
# [START webhooks-receive]
|
|
16
|
+
# Call this from your HTTP endpoint with the raw body and the two signature headers, e.g. in Sinatra:
|
|
17
|
+
# post '/webhooks' do
|
|
18
|
+
# status endpoint.receive(request.body.read, request.env['HTTP_X_GCS_SIGNATURE'], request.env['HTTP_X_GCS_KEYID'])
|
|
19
|
+
# end
|
|
20
|
+
# In Rails use request.raw_post, request.headers['X-GCS-Signature'] and request.headers['X-GCS-KeyId'], and skip
|
|
21
|
+
# the CSRF check for this action. Pass the body unchanged: parsing it as JSON first breaks the signature check.
|
|
22
|
+
# The web layer has already collapsed repeated headers into one value here. If your framework exposes repeated
|
|
23
|
+
# headers, pass each received value as its own RequestHeader and never merge them: the helper rejects a duplicate
|
|
24
|
+
# X-GCS-Signature or X-GCS-KeyId, and a merged value would hide it.
|
|
25
|
+
# Returns the HTTP status to answer with.
|
|
26
|
+
# @param body [String]
|
|
27
|
+
# @param signature [String, nil]
|
|
28
|
+
# @param key_id [String, nil]
|
|
29
|
+
# @return [Integer]
|
|
30
|
+
def receive(body, signature, key_id)
|
|
31
|
+
# A nil header value makes the SDK raise TypeError or NoMethodError instead of SignatureValidationException:
|
|
32
|
+
# reject it first.
|
|
33
|
+
return 401 if signature.nil? || signature.empty? || key_id.nil? || key_id.empty?
|
|
34
|
+
|
|
35
|
+
request_headers = [
|
|
36
|
+
OnlinePayments::SDK::Communication::RequestHeader.new('X-GCS-Signature', signature),
|
|
37
|
+
OnlinePayments::SDK::Communication::RequestHeader.new('X-GCS-KeyId', key_id)
|
|
38
|
+
]
|
|
39
|
+
begin
|
|
40
|
+
# Checks the signature before parsing the event.
|
|
41
|
+
webhooks_event = webhooks_helper.unmarshal(body, request_headers)
|
|
42
|
+
rescue OnlinePayments::SDK::Webhooks::SignatureValidationException
|
|
43
|
+
# Wrong or missing signature, or an unknown key ID (SecretKeyNotAvailableException is a subclass).
|
|
44
|
+
# Not sent by the platform, or the wrong secret is configured. Do nothing with it.
|
|
45
|
+
return 401
|
|
46
|
+
rescue OnlinePayments::SDK::Webhooks::ApiVersionMismatchException,
|
|
47
|
+
OnlinePayments::SDK::JSON::MarshallerSyntaxException => e
|
|
48
|
+
# The signature is valid, so the platform sent it, but this SDK cannot read it. Neither class is a subclass
|
|
49
|
+
# of SignatureValidationException. Do not answer with an error: a retry sends the same body and fails the same
|
|
50
|
+
# way. Keep the raw body to replay it after you upgrade the SDK, and raise an alert.
|
|
51
|
+
inbox.save_unreadable_body(body, e.class.name.to_s)
|
|
52
|
+
logger.error("ALERT: verified webhook that the SDK cannot read (#{e.class}), raw body saved")
|
|
53
|
+
return 200
|
|
54
|
+
end
|
|
55
|
+
# Save the verified event before you answer. Do not count on the platform sending the event again after a 2xx,
|
|
56
|
+
# so an event that only lives in memory when the process dies can be lost. The inbox ignores duplicates.
|
|
57
|
+
inbox.save_event(webhooks_event)
|
|
58
|
+
# A background job processes the saved events. Slow or failed answers are retried by the platform.
|
|
59
|
+
200
|
|
60
|
+
end
|
|
61
|
+
# [END webhooks-receive]
|
|
62
|
+
|
|
63
|
+
private
|
|
64
|
+
|
|
65
|
+
# @return [OnlinePayments::SDK::Webhooks::WebhooksHelper]
|
|
66
|
+
attr_reader :webhooks_helper
|
|
67
|
+
|
|
68
|
+
# @return [WebhookInbox]
|
|
69
|
+
attr_reader :inbox
|
|
70
|
+
|
|
71
|
+
# @return [Logger]
|
|
72
|
+
attr_reader :logger
|
|
73
|
+
end
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
require 'onlinepayments/sdk'
|
|
2
|
+
require_relative 'client_setup'
|
|
3
|
+
|
|
4
|
+
module WebhooksSetup
|
|
5
|
+
# [START webhooks-setup]
|
|
6
|
+
# Create the helper once. The key ID and secret come from the Merchant Portal (Developer > Webhooks).
|
|
7
|
+
# Keep them like the API secret: in a secret store of your platform or, locally, in your own environment, never in
|
|
8
|
+
# a file in the repository. A blank value stops the application at startup.
|
|
9
|
+
# In production you can pass your own object that includes OnlinePayments::SDK::Webhooks::SecretKeyStore and
|
|
10
|
+
# implements get_secret_key(key_id) on top of your secret storage.
|
|
11
|
+
# @return [OnlinePayments::SDK::Webhooks::WebhooksHelper]
|
|
12
|
+
def self.create_webhooks_helper
|
|
13
|
+
secret_key_store = OnlinePayments::SDK::Webhooks::InMemorySecretKeyStore.instance
|
|
14
|
+
secret_key_store.store_secret_key(ClientSetup.required_env('onlinePayments_webhooks_keyId'),
|
|
15
|
+
ClientSetup.required_env('onlinePayments_webhooks_secret'))
|
|
16
|
+
OnlinePayments::SDK::Webhooks::WebhooksHelper.new(OnlinePayments::SDK::JSON::DefaultMarshaller.instance,
|
|
17
|
+
secret_key_store)
|
|
18
|
+
end
|
|
19
|
+
# [END webhooks-setup]
|
|
20
|
+
end
|
|
21
|
+
|
|
22
|
+
# Stand-in for your durable storage of received events: a database table or a persistent queue.
|
|
23
|
+
# A background job reads the saved events and processes them, see WebhookEventProcessor.
|
|
24
|
+
class WebhookInbox
|
|
25
|
+
# Save a verified event. Ignore a duplicate: the platform can send the same event more than once, and the
|
|
26
|
+
# webhooks guide identifies a duplicate by identical payment.id and type.
|
|
27
|
+
# @param webhooks_event [OnlinePayments::SDK::Webhooks::WebhooksEvent]
|
|
28
|
+
# @return [void]
|
|
29
|
+
def save_event(webhooks_event)
|
|
30
|
+
raise NotImplementedError
|
|
31
|
+
end
|
|
32
|
+
|
|
33
|
+
# Save the raw body of an event that passed verification but that the SDK cannot read, to replay it after you
|
|
34
|
+
# upgrade the SDK.
|
|
35
|
+
# @param raw_body [String]
|
|
36
|
+
# @param reason [String]
|
|
37
|
+
# @return [void]
|
|
38
|
+
def save_unreadable_body(raw_body, reason)
|
|
39
|
+
raise NotImplementedError
|
|
40
|
+
end
|
|
41
|
+
end
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Error handling
|
|
2
|
+
|
|
3
|
+
When the platform answers with an error, the SDK reports it as an exception or as an error response, depending on
|
|
4
|
+
the SDK; `ruby.md` describes how this SDK does it and names its error types. Every API error carries the HTTP
|
|
5
|
+
status code and a list of errors with an `errorCode` and an `id`; a validation error names the field in
|
|
6
|
+
`propertyName` when it is about one field. A 404 also carries an `errorId` (quote it to support) and a `message`. A 400 validation error can
|
|
7
|
+
come without `errorId`, `message` and `retriable`: do not rely on them being set, and log the error codes, ids and
|
|
8
|
+
property names. A Hosted Checkout validation error does not repeat the values you sent.
|
|
9
|
+
|
|
10
|
+
## What to do per error
|
|
11
|
+
|
|
12
|
+
| Situation | HTTP | What to do |
|
|
13
|
+
|---|---|---|
|
|
14
|
+
| Payment declined | error with a payment result in the body (402 for an acquirer decline, 403 for a failed 3-D Secure authentication) | The payment exists. Read its status with `GetPaymentDetails` before deciding anything (mandatory rule 5). Show the customer a neutral message and let them try again. |
|
|
15
|
+
| Request still running for this idempotence key | 409 | The first request with the same key is still being processed. Wait a moment and send the same request with the same key. |
|
|
16
|
+
| Invalid request | 400 | Fix the request. Do not retry. The errors list names the property, if the error is about one. |
|
|
17
|
+
| Operation not allowed in the payment's state | 400 | The error id is `ACTION_NOT_ALLOWED_ON_TRANSACTION` and no property is named: for example a capture after the final capture or after a cancel, a refund before the capture or above the remaining amount, a second cancel. Read the status with `GetPaymentDetails`. Do not retry. |
|
|
18
|
+
| Wrong credentials or merchant ID | 403 with the error id `ACCESS_TO_MERCHANT_NOT_ALLOWED` and no payment in the body | Check the API key ID, secret, merchant ID and endpoint. Do not retry. |
|
|
19
|
+
| Object not found | 404 | Check the ID. |
|
|
20
|
+
| Technical error marked retriable | check `retriable` | If an error in the list has `retriable` = true, the request was not processed. Send it again with a **new** idempotence key, with a growing delay. Without `retriable`, do not retry. |
|
|
21
|
+
| Timeout or connection error | none | The request may or may not have been processed. Retry with the same idempotence key. For an operation that supports idempotence (see mandatory rule 1) the platform returns the original result instead of processing it twice. If retries fail, check with `GetPaymentDetails` before creating a new payment. |
|
|
22
|
+
|
|
23
|
+
## Rules
|
|
24
|
+
|
|
25
|
+
- Handle the most specific error first, for example a declined payment before a general API error. How the SDK
|
|
26
|
+
reports errors, and which error type is the most general, differs per SDK; see `ruby.md`.
|
|
27
|
+
- Reuse the idempotence key only when you got no answer (timeout, connection error) or a 409 for a request that is
|
|
28
|
+
still running: the outcome is unknown, and a new key could create a second payment.
|
|
29
|
+
- Use a new key only when the platform answered with an error marked `retriable`: that request was not processed.
|
|
30
|
+
- Log fields, not bodies: the `errorId`, HTTP status, error codes and error ids. A payment ID with its status is
|
|
31
|
+
also fine. Never log the request yourself. The SDK's own logging masks card data; it is off by default.
|
|
32
|
+
- Printing or serialising the SDK's error object can include the platform's response body; `ruby.md` says
|
|
33
|
+
how for this SDK. For Hosted Checkout create and get calls the body is a plain error response (an error ID and a
|
|
34
|
+
list of errors), so logging the error object is fine there. Never log the body of a response that carries a
|
|
35
|
+
payment: the error of a declined payment, or a successful `GetPaymentDetails` or `GetHostedCheckout`
|
|
36
|
+
response. It holds the card's expiry date, which mandatory rule 6 forbids in logs, and customer data;
|
|
37
|
+
only the card number arrives masked.
|
|
38
|
+
- Waiting between retries blocks the thread, and inside a customer's request it blocks the customer's browser. Keep
|
|
39
|
+
the number of attempts and the delays small there, or hand the call to a background job.
|
|
40
|
+
- Show customers a neutral message. Do not show error codes or decline reasons.
|
|
41
|
+
|
|
42
|
+
```ruby
|
|
43
|
+
# idempotence_key is the stored key of the payment attempt (PaymentAttempt.key_for). Reuse it when a request
|
|
44
|
+
# got no answer; replace it, stored again, only when the platform answered with an error marked retriable.
|
|
45
|
+
# @param order_id [String]
|
|
46
|
+
# @param request [OnlinePayments::SDK::Domain::CreatePaymentRequest]
|
|
47
|
+
# @param idempotence_key [String]
|
|
48
|
+
# @return [PaymentStep]
|
|
49
|
+
def create_payment(order_id, request, idempotence_key)
|
|
50
|
+
context = OnlinePayments::SDK::CallContext.new(idempotence_key)
|
|
51
|
+
attempt = 1
|
|
52
|
+
begin
|
|
53
|
+
response = merchant.payments.create_payment(request, context)
|
|
54
|
+
rescue OnlinePayments::SDK::DeclinedPaymentException => e
|
|
55
|
+
# Declined: the payment exists. Read its status before deciding anything.
|
|
56
|
+
return handle_declined(order_id, e)
|
|
57
|
+
rescue OnlinePayments::SDK::IdempotenceException
|
|
58
|
+
# The first request with this key is still running. Wait, then send the same request again.
|
|
59
|
+
raise if attempt >= 3
|
|
60
|
+
|
|
61
|
+
sleep(2 * attempt)
|
|
62
|
+
attempt += 1
|
|
63
|
+
retry
|
|
64
|
+
rescue OnlinePayments::SDK::ValidationException => e
|
|
65
|
+
# 400: the request is invalid. Fix the request; retrying does not help.
|
|
66
|
+
# Log the error codes and the error ID, never the request (it can hold card data).
|
|
67
|
+
codes = e.errors.map { |error| "#{error.error_code} #{error.property_name}" }.join('; ')
|
|
68
|
+
logger.error("create_payment rejected, error_id #{e.error_id}: #{codes}")
|
|
69
|
+
raise
|
|
70
|
+
rescue OnlinePayments::SDK::ApiException => e
|
|
71
|
+
# A technical error marked retriable (e.g. PlatformException, 500, 502 or 503): the request was not
|
|
72
|
+
# processed. Send it again with a new key. Other errors are not retried: AuthorizationException
|
|
73
|
+
# (403) for a wrong API key, secret or merchant ID, ReferenceException (404, 409,
|
|
74
|
+
# 410) for an object not found, and server errors without a retriable error.
|
|
75
|
+
raise if attempt >= 3 || e.errors.none? { |error| error.retriable == true }
|
|
76
|
+
|
|
77
|
+
# The new key is stored before the call, like the first one.
|
|
78
|
+
context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.start(order_id, orders))
|
|
79
|
+
sleep(2 * attempt)
|
|
80
|
+
attempt += 1
|
|
81
|
+
retry
|
|
82
|
+
rescue OnlinePayments::SDK::Communication::CommunicationException
|
|
83
|
+
# No answer: timeout or connection error. The payment may or may not exist.
|
|
84
|
+
# Retry with the same key; the platform returns the original result instead of creating a second
|
|
85
|
+
# payment.
|
|
86
|
+
raise if attempt >= 3
|
|
87
|
+
|
|
88
|
+
sleep(2 * attempt)
|
|
89
|
+
attempt += 1
|
|
90
|
+
retry
|
|
91
|
+
end
|
|
92
|
+
CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
|
|
93
|
+
end
|
|
94
|
+
|
|
95
|
+
private
|
|
96
|
+
|
|
97
|
+
# @param order_id [String]
|
|
98
|
+
# @param e [OnlinePayments::SDK::DeclinedPaymentException]
|
|
99
|
+
# @return [PaymentStep]
|
|
100
|
+
def handle_declined(order_id, e)
|
|
101
|
+
payment_id = e.payment_result&.payment&.id
|
|
102
|
+
if payment_id.nil?
|
|
103
|
+
orders.save_state(order_id, OrderPaymentState::FAILED)
|
|
104
|
+
return PaymentStep.new(state: OrderPaymentState::FAILED)
|
|
105
|
+
end
|
|
106
|
+
|
|
107
|
+
orders.save_payment_id(order_id, payment_id)
|
|
108
|
+
details = merchant.payments.get_payment_details(payment_id)
|
|
109
|
+
state = PaymentStatusExample.to_order_state(details.status, details.status_output)
|
|
110
|
+
orders.save_state(order_id, state)
|
|
111
|
+
PaymentStep.new(state: state)
|
|
112
|
+
end
|
|
113
|
+
```
|