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,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
|
+
```
|