You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
@@ -454,6 +454,125 @@ if (applePayButton.canMakePayment()) {
454
454
455
455
_**Note:** The callback given to `mount()` is called on a successful payment, and is called with the merchants (your) Paytrail success redirect url. You can customize the actions after a successful payment. The example callback above will redirect the user to the success url after 1.5 seconds, to give time for the Apple Pay modal success-animation to finish._
456
456
457
+
## Klarna
458
+
459
+
For a comprehensive guide on optimizing your integration and boosting sales, please refer to [Klarna's dedicated Paytrail documentation](https://docs.klarna.com/acquirer/paytrail/get-started/ecosystem-overview/?utm_source=paytrail-docs).
460
+
461
+
For operational topics such as dispute handling, accessing the Klarna Partner Portal, and configuring payment methods, please visit the [Paytrail Help Center](https://support.paytrail.com/hc/en-us/sections/40564512581009-Klarna).
462
+
463
+
### Payments
464
+
465
+
#### Standard Integration
466
+
467
+
The standard Paytrail integration for Klarna doesn't require any Klarna-specific API calls. Payments are created using the normal **Create payment** API.
468
+
469
+
Klarna also supports **manual invoice activation (capture)**; see [Invoices](#invoices).
470
+
471
+
472
+
For payment reference and examples, see:
473
+
474
+
-[Create](#create)
475
+
-[List providers](#list-providers)
476
+
477
+
**How to present Klarna when you don't use Klarna Web SDK**
478
+
479
+
Klarna is shown either on the Paytrail hosted payment page or as a selectable payment method when rendering payment buttons in your store.
480
+
481
+
The Klarna payment option is returned as part of the standard payment method response in the credit [PaymentMethodGroup](#paymentmethodgroup).
482
+
483
+
#### Share customer data to increase conversion rates
484
+
485
+
Always share as much payment information as possible with Klarna. This is crucial for improving session continuity, enabling personalization, and increasing conversion rates. It also helps accelerate customer authentication, ensure consistency across all touchpoints, and streamline reconciliation and dispute management:
486
+
487
+
- Customer first and last name
488
+
- Customer email address
489
+
- Reference
490
+
- Items
491
+
- Invoicing address
492
+
- Delivery address
493
+
- Klarna Network Session Token
494
+
- Klarna Network Data
495
+
496
+
**Klarna Network Session Token:** When customers interact with Klarna's [Conversion features](#conversion-features), Klarna Web SDK returns a Klarna Network Session Token.
497
+
498
+
In such cases, when the Klarna Network Session Token is present, you must collect this token and share it in [Klarna provider details](#klarna-provider-details) under the `providerDetails` object when creating the payment session with Paytrail. This is required for session continuity, personalization, and improved conversion rates. Note that Paytrail simply passes the token along; it's your responsibility to obtain and handle it.
499
+
500
+
Sharing the `klarna.networkSessionToken` is required with the Conversion features.
501
+
502
+
**Klarna Network Data:** You can also send `klarna.networkData` in the `providerDetails` object as a serialized JSON. This enriched data helps increase approval rates and reduce false declines by enabling Klarna to make smarter decisions. Providing complete and accurate data improves acceptance rates. For more details, refer to Klarna's [Optimize Conversion Rate](https://docs.klarna.com/acquirer/paytrail/get-started/maximize-sales-with-klarna/optimize-conversion-rate/?utm_source=paytrail-docs) documentation and also check [Klarna Network Data Schema](https://docs.klarna.com/acquirer/paytrail/api/klarna-network-data-schema/?utm_source=paytrail-docs).
| networkSessionToken | string | <center>x</center> | Min length 1, max length 8192 | Klarna Network Session Token from the Web SDK (Conversion features). |
528
+
| networkData | string | <center>x</center> | Min length 1, max length 10240 | Optional serialized JSON; enriched data to improve approval rates. |
529
+
530
+
531
+
#### Highest-converting Klarna Integration
532
+
Integrate Klarna's Web SDK to deliver a seamless, optimized checkout experience on your site. Initialize the SDK, present Klarna in the payment selector, and finalize the flow with Klarna's payment button. You will also utilize the same Klarna Web SDK for [Conversion features](#conversion-features).
533
+
534
+
Refer to the Klarna documentation for [Implementing Klarna Web SDK](https://docs.klarna.com/acquirer/paytrail/recommended-integration/build-the-checkout/klarna-websdk/?utm_source=paytrail-docs).
535
+
536
+
### Presenting Klarna
537
+
538
+
Integrate Klarna into your checkout by following Klarna's branding and messaging guidelines to optimize the customer journey and maximize conversions.
539
+
540
+
Refer to the Klarna documentation for [Presenting Klarna in your checkout](https://docs.klarna.com/acquirer/paytrail/recommended-integration/klarna-in-your-checkout/?utm_source=paytrail-docs) and [Checkout form overview](https://docs.klarna.com/acquirer/paytrail/recommended-integration/build-the-checkout/overview/?utm_source=paytrail-docs).
541
+
542
+
### Conversion features
543
+
544
+
You can implement Klarna's [Conversion features](https://docs.klarna.com/acquirer/paytrail/additional-features/partner-portal/conversion-boosters/?utm_source=paytrail-docs) with your payments. These features should be implemented directly on your online store using the guidelines provided in Klarna Docs and the Klarna Partner Portal:
-[Sign in with Klarna](https://docs.klarna.com/acquirer/paytrail/sign-in-with-klarna/integration-prerequisites/?utm_source=paytrail-docs)
549
+
550
+
For Conversion features, make sure to add the `klarna_network_session_token` returned by the Klarna Web SDK to the `providerDetails.klarna.networkSessionToken` field in Paytrail's `/payments` call.
551
+
552
+
Alternative to the `/payments` endpoint, you can also utilize two other dedicated endpoints for Klarna:
Using one of these endpoints instead of the `/payments` endpoint helps create a faster checkout experience for your customers by shortening API response times and eliminating unnecessary redirection to a payment link when it's not required.
557
+
558
+
With these endpoints, you can use the exact same request body you already have for the `/payments` endpoint, however, their response would be different than `/payments`.
559
+
560
+
If `/payments/klarna/charge` or `/payments/klarna/authorization-hold` is successful, `HTTP 201` and the `transactionId` of the payment is directly returned. This means that the information provided with the `klarna.networkSessionToken` was sufficient to finalize the payment, so no further action is needed from the customer. You can then proceed to create the order in your system.
561
+
562
+
If the customer still needs to get redirected to take further action about the payment, `HTTP 403` along with the `transactionId` and `stepUpUrl` is returned. In this case, redirect the customer to the `stepUpUrl`, so that they can complete their purchase:
If you prefer to use `/payments/klarna/authorization-hold`;
573
+
- to capture the authorization, you need to call `/payments/{transactionId}/klarna/commit`
574
+
- to void (cancel) the authorization, you need to call `/payments/{transactionId}/klarna/revert`
575
+
457
576
## Token payments
458
577
459
578
Paytrail provides an API for tokenizing payment cards and issuing payments on those tokenized payment cards.
@@ -763,27 +882,91 @@ If the flow fails due to issues with the card itself (insufficient funds, fraud
763
882
764
883
## Invoices
765
884
766
-
### Manually activating invoices
885
+
### Manually activating payments
886
+
887
+
For Klarna and Walley B2C/B2B, you can activate the payment at a later time, for example for pre-ordered products.
888
+
Activation window:
889
+
890
+
- Klarna: up to 28 days
891
+
- Walley: up to 90 days
892
+
893
+
After this time, the payment **can no** longer be activated.
894
+
895
+
#### Creating payments with pending status
896
+
897
+
Set the `manualInvoiceActivation` flag to true. New payment is set to `pending` state.
898
+
If the payment is made with unsupported providers, this flag is ignored.
899
+
900
+
- with Klarna, an authorization hold is made for the amount and is kept for the maximum duration of activation window.
901
+
- with Walley, no authorization hold is made.
902
+
903
+
Refer to [create payment request body section](#create-payment)
904
+
905
+
```json
906
+
{
907
+
"stamp": "29858472953",
908
+
"reference": "9187445",
909
+
"amount": 1590,
910
+
"currency": "EUR",
911
+
"language": "FI",
912
+
"manualInvoiceActivation": true
913
+
"..."
914
+
}
915
+
```
916
+
917
+
### Capturing payments
918
+
919
+
!> Updated endpoint! Old endpoint remains functional but all new integrations should use the new endpoint.
920
+
921
+
`HTTP POST /payments/{transactionId}/capture-order` manually activates invoice by transaction ID.
922
+
923
+
Deprecated endpoint `HTTP POST /payments/{transactionId}/activate-invoice`
767
924
768
-
Paytrail provides customer an option to pay with invoice. For certain invoice payment methods (currently only Walley), it is possible to activate the invoice manually later. This can be used for example with preordered products.
925
+
Sending a capture-order request changes the payment status to `accepted` and with:
769
926
770
-
Walley will keep the incvoice open for a maximum of 90 days. An invoice **cannot** be activated after this 90 day period.
927
+
- Klarna, issues a charge for the authorization hold
928
+
- Walley, activates the invoice
771
929
772
-
####Payment creation to pending status
930
+
##### Request
773
931
774
-
Payment needs to be created with the `manualInvoiceActivation` flag set to true. If paid with invoice, the payment will be left to `pending` status and invoice will not be activated automatically.
932
+
No request body required.
775
933
776
-
####Activating invoice
934
+
##### Response
777
935
778
-
`HTTP POST /payments/{transactionId}/activate-invoice` manually activates invoice by transaction ID. Can only be used if payment was paid with Walley, is in pending status and the payment was created within 90 days of the activation call.
!> Relevant for Klarna payment method only, and only for payments made with `manualInvoiceActivation`. If you're looking to make a refund, please refer to [refund](#Refund) section.
946
+
947
+
`HTTP POST /payments/{transactionId}/cancel-order` cancels the payment and releases any authorization holds made.
948
+
949
+
Klarna payments made requiring manual invoice activation are going to be cancelled automatically after the activation window expires.
950
+
951
+
With `manualInvoiceActivation` you are issuing an authorization hold for the amount. It is advised to issue a cancel for the payment as soon as you know you are going to do so, even though this is an automatic operation at the end of expiry window.
779
952
780
953
##### Request
781
954
782
955
No request body required.
783
956
784
957
##### Response
785
958
786
-
Activation will return `HTTP 200` when successful.
959
+
Cancel will return `HTTP 201` when successful, or `HTTP 202` when request is received but response to cancellation cannot be given right away.
| manualInvoiceActivation | boolean | <center>-</center> | If paid with invoice payment method, the invoice will not be activated automatically immediately. Currently only supported with Walley.|
1211
+
| manualInvoiceActivation | boolean | <center>-</center> | If paid with invoice payment method, the invoice will not be activated automatically immediately. Supported with Walley and Klarna. |
1029
1212
| redirectUrls |[CallbackUrl](#callbackurl)| <center>x</center> | Where to redirect browser after a payment is paid or cancelled. A single redirect URL can have maximum of 300 characters. |
1030
1213
| callbackUrls |[CallbackUrl](#callbackurl)| <center>-</center> | Which url to ping after this payment is paid or cancelled. |
1031
1214
| callbackDelay | number | <center>-</center> | Callback URL polling delay in seconds. If callback URLs are given, the call can be delayed up to 900 seconds. Default: 0 |
1032
1215
| groups |[PaymentMethodGroup](#paymentmethodgroup)[]| <center>-</center> | Instead of all enabled payment methods, return only those of given groups. It is highly recommended to use [list providers](#list-providers) before initiating the payment if filtering by group. If the payment methods are rendered in the webshop the grouping functionality can be implemented based on the `group` attribute of each returned payment instead of filtering when creating a payment. |
1033
1216
| usePricesWithoutVat | boolean | <center>-</center> | If true, `amount` and `items.unitPrice` should be sent to API not including VAT, and final amount is calculated by Paytrail's system using the items' `unitPrice` and `vatPercentage` (with amounts rounded to closest cent). Also, when true, **items must be included** and all item unit prices must be positive. |
1217
+
| providerDetails |[ProviderDetails](#providerdetails)| <center>-</center> | Pass properties to payment methdos that support additional functionality. Content depends on payment method used. |
1034
1218
1035
1219
##### Item
1036
1220
@@ -1087,6 +1271,12 @@ These URLs must use HTTPS.
1087
1271
| amount | integer | <center>x</center> | 250 | Amount of commission in currency's minor units, e.g. for Euros use cents. VAT not applicable. |
1088
1272
| vatPercentage | integer | <center></center> | 25.5 | Commissions VAT percentage. Values between 0 and 100 are allowed with one number in decimal part. If not given, 25.5 will be used as default |
1089
1273
1274
+
##### ProviderDetails
1275
+
1276
+
| Field | Type | Required | Example | Description |
0 commit comments