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,966 @@
1
+ # Integration flows
2
+
3
+ Steps and code for each integration method of Worldline Direct, for the Ruby SDK.
4
+ The client setup is in `ruby.md`. In the code, the order store stands for your own database code; replace
5
+ it.
6
+
7
+ Contents:
8
+
9
+ - Decision guide
10
+ - Hosted Checkout
11
+ - Payment attempt and idempotence key (server-to-server, Hosted Tokenization, Hosted Fields, client integration)
12
+ - Handling a CreatePayment response (server-to-server, Hosted Tokenization, Hosted Fields, client integration)
13
+ - Server-to-server
14
+ - Hosted Tokenization
15
+ - Hosted Fields
16
+ - Client integration
17
+ - Payment Links
18
+ - After-payment operations: capture, refund, cancel
19
+ - Recurring payments
20
+ - Payment status
21
+
22
+ ## Decision guide
23
+
24
+ 1. Does the user want the least work and no card data on their servers? Use **Hosted Checkout**.
25
+ 2. Must the card form be part of their own checkout page? Use **Hosted Tokenization** (one iframe) or
26
+ **Hosted Fields** (one field per iframe, more styling control).
27
+ 3. Is it a native mobile app, or must the form be fully their own? Use **Client integration**.
28
+ 4. Is the payer not on a checkout page at all (invoice, email, call centre)? Use **Payment Links**.
29
+ 5. Do they already hold card data under PCI DSS SAQ D, or charge a stored token? Use **Server-to-server**.
30
+ 6. Subscriptions and other charges without the customer: first payment with one of the methods above, later charges
31
+ as in **Recurring payments**.
32
+
33
+ Card payments created from your server (all methods except Hosted Checkout and Payment Links) need 3-D Secure data:
34
+ the customer's browser details and a return URL.
35
+
36
+ ## Hosted Checkout
37
+
38
+ The customer pays on a page hosted by the platform. Your server creates a session, redirects the customer, and reads
39
+ the result when the customer comes back.
40
+
41
+ 1. Create the session with the amount, your order reference and a return URL that contains your own order reference.
42
+ Build the return URL from configuration: an absolute public base URL of your shop, checked at startup. Never
43
+ build it from the request's `Host` header, which the sender controls. Escape the order reference in the query
44
+ string. The platform rejects a `returnUrl` without a protocol but does not check that it points to your shop, so
45
+ check your base URL yourself. The order reference (`merchantReference`) is at most 40 characters; a longer one is
46
+ rejected with a 400.
47
+ 2. Store `HostedCheckoutId` and `RETURNMAC` with the order after the call (mandatory rule 2).
48
+ 3. Redirect the customer to `redirectUrl` exactly as returned (mandatory rule 3). Do not open it in an iframe.
49
+ It is valid for the session timeout: 3 hours by default (`sessionTimeout`, 1 to 1440 minutes).
50
+
51
+ ```ruby
52
+ # Returns the URL to redirect the customer to.
53
+ # @param order_id [String]
54
+ # @param amount_in_cents [Integer]
55
+ # @param currency_code [String]
56
+ # @return [String]
57
+ def start_checkout(order_id, amount_in_cents, currency_code)
58
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
59
+ amount_of_money.amount = amount_in_cents
60
+ amount_of_money.currency_code = currency_code
61
+
62
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
63
+ references.merchant_reference = order_id
64
+
65
+ order = OnlinePayments::SDK::Domain::Order.new
66
+ order.amount_of_money = amount_of_money
67
+ order.references = references
68
+
69
+ checkout_input = OnlinePayments::SDK::Domain::HostedCheckoutSpecificInput.new
70
+ checkout_input.return_url = build_return_url(order_id)
71
+ checkout_input.locale = 'en-GB'
72
+
73
+ request = OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest.new
74
+ request.order = order
75
+ request.hosted_checkout_specific_input = checkout_input
76
+
77
+ response = create_hosted_checkout_with_retry(request)
78
+ hosted_checkout_id = response.hosted_checkout_id
79
+ returnmac = response.returnmac
80
+ redirect_url = response.redirect_url
81
+ if hosted_checkout_id.nil? || returnmac.nil? || redirect_url.nil?
82
+ raise "Incomplete hosted checkout response for order #{order_id}"
83
+ end
84
+
85
+ # Store both values with the order before the customer leaves your site.
86
+ orders.save_hosted_checkout(order_id, hosted_checkout_id, returnmac)
87
+ # Redirect to this URL exactly as returned. Do not build it from partial_redirect_url.
88
+ redirect_url
89
+ end
90
+
91
+ # The return URL comes from your configuration (an absolute public base URL), never from the Host header of the
92
+ # request, which the sender controls. The order reference is escaped for the query string.
93
+ # @param order_id [String]
94
+ # @return [String]
95
+ def build_return_url(order_id)
96
+ "#{public_base_url}/return?#{URI.encode_www_form('orderId' => order_id)}"
97
+ end
98
+ ```
99
+
100
+ If the create call got no answer, or failed with an error marked `retriable`, send it again.
101
+ `CreateHostedCheckout` does not support idempotent requests (mandatory rule 1), so send no idempotence key: every
102
+ resend creates a new session. That is harmless until the customer pays in it; the unused session expires. The
103
+ waiting happens inside the customer's request, so the browser waits too: keep the attempts few and the delays
104
+ short.
105
+
106
+ ```ruby
107
+ # CreateHostedCheckout does not support idempotent requests: the platform ignores an idempotence key, so every
108
+ # resend creates a new session. That is harmless until the customer pays in it; the unused session expires.
109
+ # Send it again after no answer or after an error marked retriable. The waiting happens inside the customer's
110
+ # request, so the browser waits too: keep the attempts few and the delays short, or move the call to a
111
+ # background job.
112
+ # @param request [OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest]
113
+ # @return [OnlinePayments::SDK::Domain::CreateHostedCheckoutResponse]
114
+ def create_hosted_checkout_with_retry(request)
115
+ attempt = 1
116
+ begin
117
+ merchant.hosted_checkout.create_hosted_checkout(request)
118
+ rescue OnlinePayments::SDK::ApiException => e
119
+ # The error of a Hosted Checkout call is a plain error response, so logging it is fine here: log at least the
120
+ # error ID, status and error codes.
121
+ codes = e.errors.map { |error| "#{error.error_code} #{error.property_name}" }.join('; ')
122
+ logger.error("create_hosted_checkout failed: status #{e.status_code}, error_id #{e.error_id}: #{codes}")
123
+ # Only an error marked retriable is sent again. Other errors reach the caller.
124
+ raise if attempt >= 3 || e.errors.none? { |error| error.retriable == true }
125
+
126
+ sleep(attempt)
127
+ attempt += 1
128
+ retry
129
+ rescue OnlinePayments::SDK::Communication::CommunicationException
130
+ # No answer (timeout or connection error): the session may or may not exist. Send the request again.
131
+ raise if attempt >= 3
132
+
133
+ sleep(attempt)
134
+ attempt += 1
135
+ retry
136
+ end
137
+ end
138
+ ```
139
+
140
+ 4. When the customer comes back, the platform appends `RETURNMAC` and `hostedCheckoutId` to the query string of your
141
+ return URL, e.g. `https://shop.example/return?orderId=123&RETURNMAC=37159fa4-...&hostedCheckoutId=4501638561`. Load the
142
+ stored values for the order and compare them in constant time: if `RETURNMAC` is missing or differs from the
143
+ stored value, the request does not belong to this checkout; reject it and do not change the order.
144
+ 5. Then call `GetHostedCheckout` to read the result. `status` is `PAYMENT_CREATED`, `IN_PROGRESS` or
145
+ `CANCELLED_BY_CONSUMER`. When a payment was created, use its status as described in "Payment status". The created
146
+ payment output also carries a payment status category (`paymentStatusCategory`: `SUCCESSFUL`, `REJECTED` or
147
+ `STATUS_UNKNOWN`); decide on the payment's `statusOutput`, as everywhere else. `CANCELLED_BY_CONSUMER` means the
148
+ customer cancelled or the session expired. For an expired session the created payment output holds a cancelled
149
+ payment with the error id `CANCELLED_BY_EXPIRATION`; the order is cancelled. A session can hold several payment
150
+ attempts (`<id>_0`, `<id>_1`, ...) that belong to one payment; `GetHostedCheckout` returns the latest attempt
151
+ (see "Process" in `webhooks.md`).
152
+ 6. Customers can close the browser before returning. The webhooks (see `webhooks.md`) cover that case.
153
+ `GetHostedCheckout` can also fail with a not-found error (the API reference documents a 404 for this call). Then
154
+ read the payment with `GetPaymentDetails` and the payment ID that your webhook handler stored. If no payment ID
155
+ is stored yet, keep the order pending and let the webhook or your reconciliation job settle it; do not mark it
156
+ failed. Handle only the not-found error this way; let other errors reach the caller. An expired session is not an
157
+ error: `GetHostedCheckout` answers it with `CANCELLED_BY_CONSUMER` (step 5).
158
+
159
+ ```ruby
160
+ # Called when the customer comes back on your return URL, e.g. with params['RETURNMAC'] in Sinatra or Rails.
161
+ # @param order_id [String]
162
+ # @param returnmac_from_query [String, nil]
163
+ # @return [Symbol] one of the OrderPaymentState values
164
+ def handle_return(order_id, returnmac_from_query)
165
+ stored = orders.get_hosted_checkout(order_id)
166
+ # The platform appends RETURNMAC to the return URL. It identifies the returning customer:
167
+ # a missing or different value means the request does not belong to this checkout.
168
+ if returnmac_from_query.nil? || returnmac_from_query.empty? ||
169
+ !constant_time_equal?(stored.returnmac, returnmac_from_query)
170
+ raise "RETURNMAC does not match the stored value for order #{order_id}"
171
+ end
172
+
173
+ # Never trust the redirect alone: read the result from the platform.
174
+ begin
175
+ hosted_checkout = merchant.hosted_checkout.get_hosted_checkout(stored.hosted_checkout_id)
176
+ rescue OnlinePayments::SDK::ReferenceException => e
177
+ # The API reference documents a 404 for this call. If it fails with not found, read the payment instead,
178
+ # with the payment ID that your webhook handler stored. Without a stored payment ID
179
+ # this returns :pending, and the webhook or your reconciliation job settles the order: do not mark it failed.
180
+ # Other errors reach the caller, including the 409 and 410 that the SDK also raises as ReferenceException.
181
+ raise unless e.status_code == 404
182
+
183
+ logger.warn("get_hosted_checkout failed for order #{order_id}: status #{e.status_code}, error_id #{e.error_id}")
184
+ return payment_status.refresh_payment_state(order_id)
185
+ end
186
+ payment = hosted_checkout.created_payment_output&.payment
187
+ payment_id = payment&.id
188
+ if hosted_checkout.status == 'PAYMENT_CREATED' && payment && payment_id
189
+ orders.save_payment_id(order_id, payment_id)
190
+ state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
191
+ orders.save_state(order_id, state)
192
+ return state
193
+ end
194
+ if hosted_checkout.status == 'CANCELLED_BY_CONSUMER'
195
+ # The customer cancelled, or the session expired (the created payment is then cancelled with the error id
196
+ # CANCELLED_BY_EXPIRATION).
197
+ orders.save_state(order_id, OrderPaymentState::CANCELLED)
198
+ return OrderPaymentState::CANCELLED
199
+ end
200
+
201
+ # IN_PROGRESS: the customer has not finished. A webhook will report the result.
202
+ OrderPaymentState::PENDING
203
+ end
204
+
205
+ # Compares in constant time, so the comparison does not reveal the stored value. OpenSSL.secure_compare would do
206
+ # this, but it does not exist on Ruby 2.3 to 2.7 (the SDK supports Ruby 2.3 and higher). Hashing both values
207
+ # first makes them the same length, so a different length is not visible either.
208
+ # @param expected [String]
209
+ # @param actual [String]
210
+ # @return [Boolean]
211
+ def constant_time_equal?(expected, actual)
212
+ expected_bytes = OpenSSL::Digest::SHA256.digest(expected).bytes
213
+ actual_bytes = OpenSSL::Digest::SHA256.digest(actual).bytes
214
+ difference = 0
215
+ expected_bytes.each_with_index { |byte, index| difference |= byte ^ actual_bytes.fetch(index) }
216
+ difference.zero?
217
+ end
218
+ ```
219
+
220
+ ## Payment attempt and idempotence key
221
+
222
+ Server-to-server, Hosted Tokenization, Hosted Fields and client integration all create the payment with a
223
+ `CreatePayment` call, which needs an idempotence key (mandatory rule 1). For `CreatePayment` one operation is one
224
+ payment attempt:
225
+
226
+ - Start an attempt when the customer begins to pay, for example when you show the payment form. Create the key and
227
+ store it with the order before the first `CreatePayment` call.
228
+ - The request that creates the payment reads the stored key. A double submit, a retry after a timeout and a restart
229
+ then send the same key, so the platform does not create a second payment: it returns the first result, or 409
230
+ while the first request is still running (see `errors.md`).
231
+ - Start a new attempt before the customer tries again after a decline or a rejected request. With the old key the
232
+ platform returns the old answer, even when the request is different.
233
+
234
+ ```ruby
235
+ # One idempotence key per payment attempt, stored with the order.
236
+ module PaymentAttempt
237
+ # Call start when the customer begins to pay, for example when you show the payment form, and again before a new
238
+ # attempt after a decline or a rejected request. It stores the key before any create_payment call.
239
+ # @param order_id [String]
240
+ # @param orders [OrderStore]
241
+ # @return [String]
242
+ def self.start(order_id, orders)
243
+ key = SecureRandom.uuid
244
+ orders.save_idempotence_key(order_id, key)
245
+ key
246
+ end
247
+
248
+ # The request that creates the payment reads the stored key. A double submit, a retry after a timeout and a restart
249
+ # then send the same key, so the platform does not create a second payment.
250
+ # @param order_id [String]
251
+ # @param orders [OrderStore]
252
+ # @return [String]
253
+ def self.key_for(order_id, orders)
254
+ key = orders.get_idempotence_key(order_id)
255
+ raise "No payment attempt was started for order #{order_id}" if key.nil?
256
+
257
+ key
258
+ end
259
+ end
260
+ ```
261
+
262
+ ## Handling a CreatePayment response
263
+
264
+ Server-to-server, Hosted Tokenization, Hosted Fields and client integration all end with a `CreatePayment` call.
265
+ Handle the response the same way:
266
+
267
+ - Store the payment ID with the order.
268
+ - If `merchantAction.actionType` is `REDIRECT`, redirect the customer to `merchantAction.redirectData.redirectURL`
269
+ (3-D Secure challenge or a third-party page). When the customer comes back on your return URL, read the status with
270
+ `GetPaymentDetails` (see "Payment status").
271
+ - Otherwise the result is already in `payment.statusOutput`.
272
+ - The other action types are not covered by the examples; the API reference describes their data:
273
+ - `SHOW_FORM`: show the customer a form (data in `merchantAction.showFormData`); the customer's input goes back to
274
+ the platform in a `CompletePayment` request.
275
+ - `SHOW_INSTRUCTIONS`: show the customer the payment instructions (`merchantAction.showInstructionsData.showData`).
276
+ - `SHOW_TRANSACTION_RESULTS`: show the customer the transaction result.
277
+ - `MOBILE_THREEDS_CHALLENGE`: the customer completes a 3-D Secure challenge inside your mobile app; pass
278
+ `merchantAction.mobileThreeDSecureChallengeParameters` to the EMVCo-certified Mobile SDK.
279
+ - `CALL_THIRD_PARTY`: your server calls a third party with the data from the response.
280
+
281
+ ```ruby
282
+ # Use for every create_payment response: server-to-server, Hosted Tokenization, Hosted Fields and client integration.
283
+ # @param response [OnlinePayments::SDK::Domain::CreatePaymentResponse]
284
+ # @param order_id [String]
285
+ # @param orders [OrderStore]
286
+ # @return [PaymentStep]
287
+ def self.handle_create_payment_response(response, order_id, orders)
288
+ payment = response.payment
289
+ payment_id = payment&.id
290
+ raise "The create payment response for order #{order_id} has no payment" if payment.nil? || payment_id.nil?
291
+
292
+ orders.save_payment_id(order_id, payment_id)
293
+
294
+ redirect_url = response.merchant_action&.redirect_data&.redirect_url
295
+ if response.merchant_action&.action_type == 'REDIRECT' && redirect_url && !redirect_url.empty?
296
+ # 3-D Secure challenge or a third-party page. Redirect to the URL exactly as returned.
297
+ # The customer comes back on your return URL; then read the status with get_payment_details.
298
+ return PaymentStep.new(redirect_url: redirect_url)
299
+ end
300
+
301
+ # No customer action needed: the result is already known.
302
+ state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
303
+ orders.save_state(order_id, state)
304
+ PaymentStep.new(state: state)
305
+ end
306
+ ```
307
+
308
+ 3-D Secure needs the customer's browser details in `order.customer.device`:
309
+
310
+ ```ruby
311
+ # 3-D Secure needs details about the customer's browser. Collect the browser values with JavaScript on the checkout
312
+ # page and read the rest from the HTTP request (e.g. in Sinatra or Rails: request.env['HTTP_ACCEPT'],
313
+ # request.user_agent, request.ip).
314
+ # @param accept_header [String]
315
+ # @param user_agent [String]
316
+ # @param ip_address [String]
317
+ # @param browser [BrowserInfo]
318
+ # @return [OnlinePayments::SDK::Domain::CustomerDevice]
319
+ def self.build_customer_device(accept_header, user_agent, ip_address, browser)
320
+ browser_data = OnlinePayments::SDK::Domain::BrowserData.new
321
+ browser_data.color_depth = browser.color_depth
322
+ browser_data.java_enabled = browser.java_enabled
323
+ browser_data.java_script_enabled = true
324
+ browser_data.screen_height = browser.screen_height.to_s
325
+ browser_data.screen_width = browser.screen_width.to_s
326
+
327
+ device = OnlinePayments::SDK::Domain::CustomerDevice.new
328
+ device.accept_header = accept_header
329
+ device.user_agent = user_agent
330
+ device.ip_address = ip_address
331
+ device.locale = browser.locale
332
+ device.timezone_offset_utc_minutes = browser.timezone_offset_utc_minutes.to_s
333
+ device.browser_data = browser_data
334
+ device
335
+ end
336
+ ```
337
+
338
+ ## Server-to-server
339
+
340
+ Your server sends the card data in `CreatePayment`. Only for merchants certified for PCI DSS SAQ D. Never log the
341
+ request (mandatory rule 6). `paymentProductId` is required with card data: without it the platform answers 400
342
+ `UNKNOWN_PRODUCT_ID`. The idempotence key is the stored key of the payment attempt (see "Payment attempt and idempotence
343
+ key").
344
+
345
+ ```ruby
346
+ # Card data on your server puts you in scope of PCI DSS SAQ D.
347
+ # Use Hosted Tokenization or Hosted Fields unless you are certified for it.
348
+ # @param order_id [String]
349
+ # @param amount_in_cents [Integer]
350
+ # @param currency_code [String]
351
+ # @param payment_product_id [Integer] e.g. 1 = Visa, 3 = Mastercard.
352
+ # @param card [CardInput]
353
+ # @param device [OnlinePayments::SDK::Domain::CustomerDevice]
354
+ # @param return_url [String]
355
+ # @return [PaymentStep]
356
+ def pay_with_card(order_id, amount_in_cents, currency_code, payment_product_id, card, device, return_url)
357
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
358
+ amount_of_money.amount = amount_in_cents
359
+ amount_of_money.currency_code = currency_code
360
+
361
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
362
+ references.merchant_reference = order_id
363
+
364
+ customer = OnlinePayments::SDK::Domain::Customer.new
365
+ customer.device = device
366
+
367
+ order = OnlinePayments::SDK::Domain::Order.new
368
+ order.amount_of_money = amount_of_money
369
+ order.references = references
370
+ order.customer = customer
371
+
372
+ card_data = OnlinePayments::SDK::Domain::Card.new
373
+ card_data.card_number = card.number
374
+ card_data.cardholder_name = card.holder_name
375
+ card_data.expiry_date = card.expiry_date
376
+ card_data.cvv = card.cvv
377
+
378
+ redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
379
+ redirection_data.return_url = return_url
380
+ three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
381
+ three_d_secure.redirection_data = redirection_data
382
+
383
+ card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
384
+ card_input.payment_product_id = payment_product_id
385
+ card_input.card = card_data
386
+ # SALE: authorised and captured at once. Acquirers that do not support it ignore it.
387
+ # FINAL_AUTHORIZATION: capture the full amount within 7 days.
388
+ # PRE_AUTHORIZATION: can be reversed; capture the authorised amount or less within 30 days.
389
+ card_input.authorization_mode = 'SALE'
390
+ card_input.three_d_secure = three_d_secure
391
+
392
+ request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
393
+ request.order = order
394
+ request.card_payment_method_specific_input = card_input
395
+
396
+ # The idempotence key is a positional argument.
397
+ context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
398
+ # Raises DeclinedPaymentException if the payment is declined, and other ApiException subclasses for errors;
399
+ # see ErrorHandlingExample for handling each case.
400
+ response = merchant.payments.create_payment(request, context)
401
+ CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
402
+ end
403
+ ```
404
+
405
+ If the payment is declined, the SDK reports a declined-payment error that holds the created payment; see `errors.md`.
406
+
407
+ ## Hosted Tokenization
408
+
409
+ The card form is an iframe from the platform on your checkout page. Your server never sees the card data.
410
+
411
+ 1. Server: create a session and send `hostedTokenizationUrl` and `sri` to the page.
412
+
413
+ ```ruby
414
+ # Creates the session for the card form iframe on your checkout page.
415
+ # @return [OnlinePayments::SDK::Domain::CreateHostedTokenizationResponse]
416
+ def create_session
417
+ request = OnlinePayments::SDK::Domain::CreateHostedTokenizationRequest.new
418
+ request.locale = 'en-GB'
419
+ # Optional: request.variant = 'MyTemplate.html', the file name of a custom template.
420
+ response = merchant.hosted_tokenization.create_hosted_tokenization(request)
421
+ # Send hosted_tokenization_url (iframe URL) and sri (script integrity) to the page.
422
+ response
423
+ end
424
+ ```
425
+
426
+ 2. Page: load `tokenizer.min.js` from the platform (not from your own server) with the `sri` value as `integrity`,
427
+ create a `Tokenizer` with the `hostedTokenizationUrl` and the ID of the `div` for the iframe, and call
428
+ `initialize()`. When the customer pays, call `submitTokenization()` and post `result.hostedTokenizationId` to your
429
+ server, together with the browser details for 3-D Secure.
430
+ 3. Server: create the payment with the `hostedTokenizationId` and handle the response as described above. If
431
+ `submitTokenization()` has not completed, the platform answers 400 with the error id
432
+ `HOSTED_TOKENIZATION_SESSION_NOT_SUBMITTED`; an unknown id gives `HOSTED_TOKENIZATION_SESSION_NOT_FOUND`. The
433
+ idempotence key is the stored key of the payment attempt (see "Payment attempt and idempotence key").
434
+
435
+ ```ruby
436
+ # The page calls tokenizer.submitTokenization() and posts result.hostedTokenizationId to your server.
437
+ # @param order_id [String]
438
+ # @param hosted_tokenization_id [String]
439
+ # @param amount_in_cents [Integer]
440
+ # @param currency_code [String]
441
+ # @param device [OnlinePayments::SDK::Domain::CustomerDevice]
442
+ # @param return_url [String]
443
+ # @return [PaymentStep]
444
+ def pay(order_id, hosted_tokenization_id, amount_in_cents, currency_code, device, return_url)
445
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
446
+ amount_of_money.amount = amount_in_cents
447
+ amount_of_money.currency_code = currency_code
448
+
449
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
450
+ references.merchant_reference = order_id
451
+
452
+ customer = OnlinePayments::SDK::Domain::Customer.new
453
+ customer.device = device
454
+
455
+ order = OnlinePayments::SDK::Domain::Order.new
456
+ order.amount_of_money = amount_of_money
457
+ order.references = references
458
+ order.customer = customer
459
+
460
+ redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
461
+ redirection_data.return_url = return_url
462
+ three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
463
+ three_d_secure.redirection_data = redirection_data
464
+
465
+ card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
466
+ card_input.authorization_mode = 'SALE'
467
+ card_input.three_d_secure = three_d_secure
468
+
469
+ request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
470
+ request.hosted_tokenization_id = hosted_tokenization_id
471
+ request.order = order
472
+ request.card_payment_method_specific_input = card_input
473
+
474
+ context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
475
+ response = merchant.payments.create_payment(request, context)
476
+ CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
477
+ end
478
+ ```
479
+
480
+ ## Hosted Fields
481
+
482
+ Each card field (card number, cardholder name, card brands, expiry date, CVV) is a separate iframe that you place in
483
+ your page and customise with CSS.
484
+
485
+ 1. Server: create a session (`locale` is required) and send `sdkUrl`, `sdkSri` and `sessionData` to the page. Pass
486
+ `sessionData` on unchanged.
487
+
488
+ ```ruby
489
+ # Creates the session that the Hosted Fields script on your checkout page needs.
490
+ # @param checkout_page_origin [String] the origin of your checkout page, e.g. https://shop.example
491
+ # @return [OnlinePayments::SDK::Domain::CreateHostedFieldsSessionResponse]
492
+ def create_session(checkout_page_origin)
493
+ request = OnlinePayments::SDK::Domain::CreateHostedFieldsSessionRequest.new
494
+ request.locale = 'en-GB'
495
+ request.origin = checkout_page_origin
496
+ response = merchant.hosted_fields.create_hosted_fields_session(request)
497
+ # Send sdk_url, sdk_sri and session_data to the page. Pass session_data on unchanged
498
+ # (as JSON: response.session_data.to_h).
499
+ response
500
+ end
501
+ ```
502
+
503
+ 2. Page: load the script from `sdkUrl` with `sdkSri` as `integrity` and `crossorigin="anonymous"`. Create the Hosted
504
+ Fields instance with `sessionData` and the IDs of your field containers. On submit call `tokenize(storeToken)`;
505
+ `true` stores the card for later use and needs the customer's consent. Then tell your server to pay.
506
+ 3. Server: create the payment with the `hostedFieldsSessionId` and handle the response as described above. The
507
+ session response has the ID at its top level and, with the same value, inside `sessionData`. If `tokenize()` has not
508
+ completed, the platform answers 400 with the error id `HOSTED_FIELDS_SESSION_NOT_SUBMITTED` (property
509
+ `hostedFieldsSessionId`). The idempotence key is the stored key of the payment attempt (see "Payment attempt and
510
+ idempotence key").
511
+
512
+ ```ruby
513
+ # The page calls tokenize() and tells your server the card is ready.
514
+ # hosted_fields_session_id is hosted_fields_session_id of the create_session response; session_data.hosted_fields_session_id holds the same value.
515
+ # @param order_id [String]
516
+ # @param hosted_fields_session_id [String]
517
+ # @param amount_in_cents [Integer]
518
+ # @param currency_code [String]
519
+ # @param device [OnlinePayments::SDK::Domain::CustomerDevice]
520
+ # @param return_url [String]
521
+ # @return [PaymentStep]
522
+ def pay(order_id, hosted_fields_session_id, amount_in_cents, currency_code, device, return_url)
523
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
524
+ amount_of_money.amount = amount_in_cents
525
+ amount_of_money.currency_code = currency_code
526
+
527
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
528
+ references.merchant_reference = order_id
529
+
530
+ customer = OnlinePayments::SDK::Domain::Customer.new
531
+ customer.device = device
532
+
533
+ order = OnlinePayments::SDK::Domain::Order.new
534
+ order.amount_of_money = amount_of_money
535
+ order.references = references
536
+ order.customer = customer
537
+
538
+ redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
539
+ redirection_data.return_url = return_url
540
+ three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
541
+ three_d_secure.redirection_data = redirection_data
542
+
543
+ card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
544
+ card_input.authorization_mode = 'SALE'
545
+ card_input.three_d_secure = three_d_secure
546
+
547
+ request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
548
+ request.hosted_fields_session_id = hosted_fields_session_id
549
+ request.order = order
550
+ request.card_payment_method_specific_input = card_input
551
+
552
+ context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
553
+ response = merchant.payments.create_payment(request, context)
554
+ CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
555
+ end
556
+ ```
557
+
558
+ ## Client integration
559
+
560
+ A Client SDK (JavaScript, iOS, Android, Flutter, ...) encrypts the card data on the customer's device. Your server
561
+ creates the session and the payment.
562
+
563
+ 1. Server: create a client session and send its values to the app. The API key never leaves your server.
564
+
565
+ ```ruby
566
+ # Creates the session that a Client SDK (JavaScript, iOS, Android, Flutter...) needs to encrypt card data.
567
+ # @return [OnlinePayments::SDK::Domain::SessionResponse]
568
+ def create_client_session
569
+ session = merchant.sessions.create_session(OnlinePayments::SDK::Domain::SessionRequest.new)
570
+ # Send client_session_id, customer_id, client_api_url and asset_url to the app. Never send your API key.
571
+ session
572
+ end
573
+ ```
574
+
575
+ 2. App: initialise the Client SDK with the session, collect the card data, and create the encrypted customer input.
576
+ Post that string to your server. Client SDK documentation:
577
+ https://docs.direct.worldline-solutions.com/en/integration/how-to-integrate/client-sdks/javascript
578
+ 3. Server: create the payment with `encryptedCustomerInput` and handle the response as described above. The string
579
+ holds encrypted card data and can be submitted only once: do not store it. It is at most 5000 characters. A string
580
+ the platform cannot read is a 400 with the error id `INVALID_CONSUMER_INPUT_ENCRYPTION`. The idempotence key is the
581
+ stored key of the payment attempt (see "Payment attempt and idempotence key").
582
+
583
+ ```ruby
584
+ # The Client SDK returns an encrypted string; the app posts it to your server.
585
+ # @param order_id [String]
586
+ # @param encrypted_customer_input [String]
587
+ # @param amount_in_cents [Integer]
588
+ # @param currency_code [String]
589
+ # @param device [OnlinePayments::SDK::Domain::CustomerDevice]
590
+ # @param return_url [String]
591
+ # @return [PaymentStep]
592
+ def pay(order_id, encrypted_customer_input, amount_in_cents, currency_code, device, return_url)
593
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
594
+ amount_of_money.amount = amount_in_cents
595
+ amount_of_money.currency_code = currency_code
596
+
597
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
598
+ references.merchant_reference = order_id
599
+
600
+ customer = OnlinePayments::SDK::Domain::Customer.new
601
+ customer.device = device
602
+
603
+ order = OnlinePayments::SDK::Domain::Order.new
604
+ order.amount_of_money = amount_of_money
605
+ order.references = references
606
+ order.customer = customer
607
+
608
+ redirection_data = OnlinePayments::SDK::Domain::RedirectionData.new
609
+ redirection_data.return_url = return_url
610
+ three_d_secure = OnlinePayments::SDK::Domain::ThreeDSecure.new
611
+ three_d_secure.redirection_data = redirection_data
612
+
613
+ card_input = OnlinePayments::SDK::Domain::CardPaymentMethodSpecificInput.new
614
+ card_input.authorization_mode = 'SALE'
615
+ card_input.three_d_secure = three_d_secure
616
+
617
+ request = OnlinePayments::SDK::Domain::CreatePaymentRequest.new
618
+ request.encrypted_customer_input = encrypted_customer_input
619
+ request.order = order
620
+ request.card_payment_method_specific_input = card_input
621
+
622
+ context = OnlinePayments::SDK::CallContext.new(PaymentAttempt.key_for(order_id, orders))
623
+ response = merchant.payments.create_payment(request, context)
624
+ CreatePaymentResponseHandler.handle_create_payment_response(response, order_id, orders)
625
+ end
626
+ ```
627
+
628
+ ## Payment Links
629
+
630
+ The platform hosts the payment page behind a link that you send to the customer.
631
+
632
+ 1. Create the link with the amount, your order reference and an expiry date. The expiry date is required, at most
633
+ 6 months ahead, in ISO 8601 with a UTC offset (or `Z`). A missing, past or too distant date is a 400 error.
634
+ 2. Store `paymentLinkId` with the order and send `redirectionUrl` as returned.
635
+ 3. The `paymentlink.paid` webhook tells you that a payment was processed with the link. You can also read the link
636
+ with `GetPaymentLinkById` (status `ACTIVE`, `PAID`, `CANCELLED` or `EXPIRED`). Once paid it holds the payment ID.
637
+ That ID has no attempt suffix: call `GetPaymentDetails` with the ID plus `_0`, then read the payment's status
638
+ before you decide anything (mandatory rule 5).
639
+
640
+ ```ruby
641
+ # Returns the link to send to the customer (email, chat, invoice).
642
+ # @param order_id [String]
643
+ # @param amount_in_cents [Integer]
644
+ # @param currency_code [String]
645
+ # @param description [String]
646
+ # @return [OnlinePayments::SDK::Domain::PaymentLinkResponse]
647
+ def create_link(order_id, amount_in_cents, currency_code, description)
648
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
649
+ amount_of_money.amount = amount_in_cents
650
+ amount_of_money.currency_code = currency_code
651
+
652
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
653
+ references.merchant_reference = order_id
654
+
655
+ order = OnlinePayments::SDK::Domain::Order.new
656
+ order.amount_of_money = amount_of_money
657
+ order.references = references
658
+
659
+ link_input = OnlinePayments::SDK::Domain::PaymentLinkSpecificInput.new
660
+ link_input.description = description
661
+ # Required. A DateTime (not a Time), at most 6 months in the future.
662
+ link_input.expiration_date = (Time.now + (7 * 24 * 60 * 60)).to_datetime
663
+
664
+ request = OnlinePayments::SDK::Domain::CreatePaymentLinkRequest.new
665
+ request.order = order
666
+ request.payment_link_specific_input = link_input
667
+
668
+ # CreatePaymentLink does not support idempotent requests, so no idempotence key is sent.
669
+ link = merchant.payment_links.create_payment_link(request)
670
+ # Store payment_link_id with the order. Send redirection_url exactly as returned.
671
+ # The paymentlink.paid webhook (or get_payment_link_by_id) tells you when it is paid.
672
+ # Once paid, the link's payment_id has no attempt suffix: use it with "_0" appended in
673
+ # GetPaymentDetails, and read the payment's status.
674
+ link
675
+ end
676
+ ```
677
+
678
+ ## After-payment operations
679
+
680
+ Pass an idempotence key to every capture, refund and cancel. Create it once per operation; retry rules are in `errors.md`.
681
+ Sending the same request again with the same key returns the first result and does not run the operation twice.
682
+
683
+ **Capture.** Only for payments that are authorized and not captured: status `PENDING_CAPTURE`, status category
684
+ `PENDING_MERCHANT`. A payment with authorization mode `FINAL_AUTHORIZATION` must be captured for the full amount within
685
+ 7 days. One with `PRE_AUTHORIZATION` can be captured within 30 days, also for less than the authorized amount. Without
686
+ an amount, the full amount is captured and the capture is final; `isFinal` true also makes a capture final. After a
687
+ final capture no further capture is accepted, and an amount above the authorized amount is rejected. A capture that is
688
+ not final leaves the payment in `PENDING_CAPTURE`. The capture response has status `CAPTURE_REQUESTED`. The capture is
689
+ done when its operation (for a final capture, the payment) reads `CAPTURED`, which does not happen immediately: check
690
+ again later.
691
+
692
+ ```ruby
693
+ # Captures an authorized payment (status PENDING_CAPTURE). Without an amount, the full amount is captured.
694
+ # @param payment_id [String]
695
+ # @param amount_in_cents [Integer]
696
+ # @param is_final [Boolean] true: this capture is final, no further capture is accepted.
697
+ # @param idempotence_key [String]
698
+ # @return [OnlinePayments::SDK::Domain::CaptureResponse]
699
+ def capture(payment_id, amount_in_cents, is_final, idempotence_key)
700
+ details = merchant.payments.get_payment_details(payment_id)
701
+ raise "Payment #{payment_id} cannot be captured in status #{details.status}" if details.status != 'PENDING_CAPTURE'
702
+
703
+ request = OnlinePayments::SDK::Domain::CapturePaymentRequest.new
704
+ request.amount = amount_in_cents
705
+ request.is_final = is_final
706
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
707
+ merchant.payments.capture_payment(payment_id, request, context)
708
+ end
709
+ ```
710
+
711
+ **Refund.** Only when `statusOutput.isRefundable` is true (the payment is captured; the flag is false while the status
712
+ is `CAPTURE_REQUESTED`). Several refunds, partial or full, are allowed on one payment as long as their total does not
713
+ exceed the amount paid; a refund above the remaining amount is rejected. A refund is `REFUND_REQUESTED` while the
714
+ platform waits for the result and then becomes `REFUNDED` or `REJECTED`. Check the refund `status`; only `REFUNDED` is
715
+ done. The payment becomes `REFUNDED` only when the full amount is refunded. A partly refunded payment stays
716
+ `COMPLETED`; its operations list the refunds.
717
+
718
+ ```ruby
719
+ # Refunds a captured payment, fully or partly.
720
+ # @param payment_id [String]
721
+ # @param amount_in_cents [Integer]
722
+ # @param currency_code [String]
723
+ # @param idempotence_key [String]
724
+ # @return [OnlinePayments::SDK::Domain::RefundResponse]
725
+ def refund(payment_id, amount_in_cents, currency_code, idempotence_key)
726
+ details = merchant.payments.get_payment_details(payment_id)
727
+ unless details.status_output&.is_refundable == true
728
+ raise "Payment #{payment_id} is not refundable in status #{details.status}"
729
+ end
730
+
731
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
732
+ amount_of_money.amount = amount_in_cents
733
+ amount_of_money.currency_code = currency_code
734
+ request = OnlinePayments::SDK::Domain::RefundRequest.new
735
+ request.amount_of_money = amount_of_money
736
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
737
+ # REFUND_REQUESTED: the platform is processing the refund and waiting for the result. The status then becomes
738
+ # REFUNDED or REJECTED; treat the refund as done only when it is REFUNDED.
739
+ merchant.payments.refund_payment(payment_id, request, context)
740
+ end
741
+ ```
742
+
743
+ **Cancel.** Cancels an authorization that is not captured. Only when `statusOutput.isCancellable` is true. Without an
744
+ amount, the full amount is cancelled. The acquirer decides the result, so the payment in the response is in one of
745
+ three states:
746
+
747
+ - Status `CANCELLED`, category `UNSUCCESSFUL`, status code 6: the authorization is cancelled. This is final.
748
+ - Status `CANCELLED`, category `PENDING_MERCHANT`, status code 61 or 62: the platform is waiting for the acquirer's
749
+ answer. This is not final; the payment moves to one of the other two states.
750
+ - Status `CANCELLATION_REJECTED`, category `UNSUCCESSFUL`, status code 63: the acquirer refused the cancel. The payment
751
+ stays authorized: do not treat it as failed. You can try the cancel again; an authorization that is not captured
752
+ expires.
753
+
754
+ ```ruby
755
+ # Cancels (voids) an authorization that is not captured yet. No amount cancels the full amount.
756
+ # @param payment_id [String]
757
+ # @param idempotence_key [String]
758
+ # @return [OnlinePayments::SDK::Domain::CancelPaymentResponse]
759
+ def cancel(payment_id, idempotence_key)
760
+ details = merchant.payments.get_payment_details(payment_id)
761
+ unless details.status_output&.is_cancellable == true
762
+ raise "Payment #{payment_id} is not cancellable in status #{details.status}"
763
+ end
764
+
765
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
766
+ merchant.payments.cancel_payment(payment_id, OnlinePayments::SDK::Domain::CancelPaymentRequest.new, context)
767
+ end
768
+ ```
769
+
770
+ An operation that the payment's current state does not allow (a capture after the final capture or after a cancel, a
771
+ refund before the capture or above the remaining amount, a second cancel) is answered with HTTP 400 and the error id
772
+ `ACTION_NOT_ALLOWED_ON_TRANSACTION`, without a property name. Read the payment with `GetPaymentDetails`; do not retry.
773
+
774
+ ## Recurring payments
775
+
776
+ A subscription has one payment made by the customer and later charges that you start without the customer.
777
+
778
+ 1. First payment: mark it as the first of a recurring series. With Hosted Checkout set
779
+ `hostedCheckoutSpecificInput.isRecurring` to `true`; that marks the payment as the first of the series. The example
780
+ uses Hosted Checkout and the same helpers as the Hosted Checkout flow: the return URL is built from your configured
781
+ public base URL, and the create call uses the same retry helper. With `CreatePayment` set
782
+ `cardPaymentMethodSpecificInput.isRecurring` to `true` and
783
+ `cardPaymentMethodSpecificInput.recurring.recurringPaymentSequenceIndicator` to `first`.
784
+ 2. When the first payment is authorised or captured (Hosted Checkout return or webhook), store its payment ID with
785
+ the customer. The stored ID keeps working for later charges after a capture. A rejected first payment cannot be
786
+ charged again: the subsequent payment fails with a 400 error (`ACTION_NOT_ALLOWED_ON_TRANSACTION`).
787
+
788
+ ```ruby
789
+ # First payment of a subscription, made by the customer on the Hosted Checkout Page.
790
+ # The recurring flag marks it as the first payment of the series.
791
+ # It follows the Hosted Checkout flow: the return URL is built from your configuration and the call goes through
792
+ # the same retry helper. Handle the return as there.
793
+ # @param order_id [String]
794
+ # @param amount_in_cents [Integer]
795
+ # @param currency_code [String]
796
+ # @return [String] the URL to redirect the customer to
797
+ def start_subscription(order_id, amount_in_cents, currency_code)
798
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
799
+ amount_of_money.amount = amount_in_cents
800
+ amount_of_money.currency_code = currency_code
801
+
802
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
803
+ references.merchant_reference = order_id
804
+
805
+ order = OnlinePayments::SDK::Domain::Order.new
806
+ order.amount_of_money = amount_of_money
807
+ order.references = references
808
+
809
+ checkout_input = OnlinePayments::SDK::Domain::HostedCheckoutSpecificInput.new
810
+ # The return URL is built from your configured public base URL, as in the Hosted Checkout flow.
811
+ checkout_input.return_url = hosted_checkout.build_return_url(order_id)
812
+ checkout_input.is_recurring = true
813
+
814
+ request = OnlinePayments::SDK::Domain::CreateHostedCheckoutRequest.new
815
+ request.order = order
816
+ request.hosted_checkout_specific_input = checkout_input
817
+
818
+ response = hosted_checkout.create_hosted_checkout_with_retry(request)
819
+ hosted_checkout_id = response.hosted_checkout_id
820
+ returnmac = response.returnmac
821
+ redirect_url = response.redirect_url
822
+ if hosted_checkout_id.nil? || returnmac.nil? || redirect_url.nil?
823
+ raise "Incomplete hosted checkout response for order #{order_id}"
824
+ end
825
+
826
+ orders.save_hosted_checkout(order_id, hosted_checkout_id, returnmac)
827
+ redirect_url
828
+ end
829
+
830
+ # When the first payment is authorised or captured, keep its payment ID: later charges refer to it.
831
+ # @param customer_id [String]
832
+ # @param first_payment_id [String]
833
+ # @return [void]
834
+ def on_first_payment_succeeded(customer_id, first_payment_id)
835
+ orders.save_recurring_payment_id(customer_id, first_payment_id)
836
+ end
837
+ ```
838
+
839
+ 3. Later charges: call the subsequent payment operation on the first payment's ID with `subsequentType`
840
+ `Recurring` (fixed amount, regular intervals of at most one year, started by you). The allowed values are
841
+ `Recurring`, `Unscheduled`, `Installment`, `NoShow`, `DelayedCharge`, `PartialShipment`, `Resubmission`,
842
+ `RecurringVariable` and `UnscheduledFixed`; any other value is a 400 error on `subsequentType`. The new payment is
843
+ in the response (`payment`). A declined charge is reported like a declined `CreatePayment` (see `errors.md`).
844
+ Create one idempotence key per charge and store it with the charge before the first call; retry rules are in
845
+ `errors.md`.
846
+
847
+ ```ruby
848
+ # Later charge started by you, without the customer (merchant-initiated).
849
+ # The caller creates ONE idempotence key per charge and stores it with the charge (orders.save_idempotence_key)
850
+ # before the first call. Retries of the same charge reuse that key; the rules are in the error handling example.
851
+ # @param customer_id [String]
852
+ # @param order_id [String]
853
+ # @param amount_in_cents [Integer]
854
+ # @param currency_code [String]
855
+ # @param idempotence_key [String]
856
+ # @return [Symbol] one of the OrderPaymentState values
857
+ def charge_renewal(customer_id, order_id, amount_in_cents, currency_code, idempotence_key)
858
+ first_payment_id = orders.get_recurring_payment_id(customer_id)
859
+
860
+ amount_of_money = OnlinePayments::SDK::Domain::AmountOfMoney.new
861
+ amount_of_money.amount = amount_in_cents
862
+ amount_of_money.currency_code = currency_code
863
+
864
+ references = OnlinePayments::SDK::Domain::OrderReferences.new
865
+ references.merchant_reference = order_id
866
+
867
+ order = OnlinePayments::SDK::Domain::Order.new
868
+ order.amount_of_money = amount_of_money
869
+ order.references = references
870
+
871
+ card_input = OnlinePayments::SDK::Domain::SubsequentCardPaymentMethodSpecificInput.new
872
+ # Recurring = fixed amount, regular intervals (at most one year), started by you.
873
+ # Other allowed values: Unscheduled, Installment, NoShow, DelayedCharge, PartialShipment,
874
+ # Resubmission, RecurringVariable, UnscheduledFixed.
875
+ card_input.subsequent_type = 'Recurring'
876
+ # SALE: authorised and captured at once. Acquirers that do not support it ignore it.
877
+ card_input.authorization_mode = 'SALE'
878
+
879
+ request = OnlinePayments::SDK::Domain::SubsequentPaymentRequest.new
880
+ request.order = order
881
+ request.subsequentcard_payment_method_specific_input = card_input
882
+
883
+ context = OnlinePayments::SDK::CallContext.new(idempotence_key)
884
+ # A declined charge raises DeclinedPaymentException, as for create_payment.
885
+ response = merchant.subsequent.subsequent_payment(first_payment_id, request, context)
886
+ payment = response.payment
887
+ payment_id = payment&.id
888
+ raise "The subsequent payment response for order #{order_id} has no payment" if payment.nil? || payment_id.nil?
889
+
890
+ orders.save_payment_id(order_id, payment_id)
891
+ state = PaymentStatusExample.to_order_state(payment.status, payment.status_output)
892
+ orders.save_state(order_id, state)
893
+ state
894
+ end
895
+ ```
896
+
897
+ For one-click payments with a stored card (the customer is present), see the card-on-file guide:
898
+ https://docs.direct.worldline-solutions.com/en/payment-methods-and-features/advanced-features/card-on-file/api-endpoints-and-jsons-samples
899
+
900
+ ## Payment status
901
+
902
+ Read the status with `GetPaymentDetails` after a redirect back to your site, after a webhook, after a
903
+ declined-payment error, after a capture or a refund, and whenever you are unsure. `GetHostedCheckout` keeps showing
904
+ the payment as captured after a refund.
905
+
906
+ `statusOutput.statusCategory` decides the order state:
907
+
908
+ | statusCategory | Meaning | What to do |
909
+ |---|---|---|
910
+ | `COMPLETED` | Paid (captured or sale). A partly refunded payment stays `COMPLETED`. | Fulfil the order. |
911
+ | `PENDING_MERCHANT` | Authorized and waiting for a capture (status `PENDING_CAPTURE`), or a cancelled payment waiting for its final result (status `CANCELLED`). | `PENDING_CAPTURE`: capture or cancel. `CANCELLED`: wait for a webhook or check again later. |
912
+ | `PENDING_PAYMENT`, `PENDING_CONNECT_OR_3RD_PARTY`, `CREATED` | Not final: waiting for the result of 3-D Secure, an authorization, a capture (`CAPTURE_REQUESTED`) or a refund (`REFUND_REQUESTED`). | Wait for a webhook or check again later. |
913
+ | `UNSUCCESSFUL` | Declined, cancelled or failed (`status` tells which). | Do not fulfil. |
914
+ | `REFUNDED` | Fully refunded. | Update the order. |
915
+ | `REVERSED` | Reversed. | Do not treat as paid; check the payment's operations and follow up. |
916
+
917
+ `status` (`CREATED`, `CANCELLED`, `REJECTED`, `REJECTED_CAPTURE`, `REDIRECTED`, `PENDING_PAYMENT`, `PENDING_COMPLETION`,
918
+ `PENDING_CAPTURE`, `AUTHORIZATION_REQUESTED`, `CAPTURE_REQUESTED`, `CAPTURED`, `REVERSED`, `REFUND_REQUESTED`,
919
+ `REFUNDED`) and `statusCode` give more detail. `isCancellable` and `isRefundable` say whether a cancel or a refund is
920
+ possible; `isAuthorized` says that the transaction was authorized.
921
+ `statusOutput` can be missing in a response. Treat a missing `statusOutput` or `statusCategory` as not final
922
+ (pending), never as paid.
923
+ Status reference: https://docs.direct.worldline-solutions.com/en/integration/api-developer-guide/statuses
924
+
925
+ ```ruby
926
+ # @param order_id [String]
927
+ # @return [Symbol] one of the OrderPaymentState values
928
+ def refresh_payment_state(order_id)
929
+ payment_id = orders.get_payment_id(order_id)
930
+ # No payment ID stored yet: the webhook or your reconciliation job will settle the order.
931
+ return OrderPaymentState::PENDING if payment_id.nil?
932
+
933
+ details = merchant.payments.get_payment_details(payment_id)
934
+ state = PaymentStatusExample.to_order_state(details.status, details.status_output)
935
+ orders.save_state(order_id, state)
936
+ state
937
+ end
938
+
939
+ # Decide on status_category. status and status_code give more detail.
940
+ # status_output or status_category can be missing in a response: that is pending, never paid.
941
+ # @param status [String, nil]
942
+ # @param status_output [OnlinePayments::SDK::Domain::PaymentStatusOutput, nil]
943
+ # @return [Symbol] one of the OrderPaymentState values
944
+ def self.to_order_state(status, status_output)
945
+ case status_output&.status_category
946
+ when 'COMPLETED'
947
+ OrderPaymentState::PAID
948
+ when 'PENDING_MERCHANT'
949
+ # PENDING_CAPTURE: authorized but not captured yet, capture or cancel it.
950
+ # Any other status (CANCELLED, waiting for its final result) is not final.
951
+ status == 'PENDING_CAPTURE' ? OrderPaymentState::AUTHORIZED : OrderPaymentState::PENDING
952
+ when 'REFUNDED'
953
+ OrderPaymentState::REFUNDED
954
+ when 'REVERSED'
955
+ # Not paid: do not treat the order as paid.
956
+ OrderPaymentState::REVERSED
957
+ when 'UNSUCCESSFUL'
958
+ status == 'CANCELLED' ? OrderPaymentState::CANCELLED : OrderPaymentState::FAILED
959
+ else
960
+ # CREATED, PENDING_PAYMENT, PENDING_CONNECT_OR_3RD_PARTY: not final.
961
+ # A missing status_output or status_category (nil) and categories added later also end up here: not paid.
962
+ # Wait for a webhook or check again later.
963
+ OrderPaymentState::PENDING
964
+ end
965
+ end
966
+ ```