diff --git a/_includes/cobadge-dankort.md b/_includes/cobadge-dankort.md index 1119b2406f..0db61a62dc 100644 --- a/_includes/cobadge-dankort.md +++ b/_includes/cobadge-dankort.md @@ -1,19 +1,20 @@ ## Co-badge Card Choice For Dankort -Due to [EU regulations from 2016-06-09][eu-regulation] regarding cards with more -than one payment application, we have developed support for end users of -Dankort to be able to choose their preferred payment application on the Swedbank -Pay payment page. If you are a Dankort user, read more about this feature at -[Dankort][dankort-eu]. +Due to [EU regulations from 2016-06-09][eu-regulation]{:target="_blank"} +regarding cards with more than one payment application, we have developed +support for end users of Dankort to be able to choose their preferred payment +application on the Swedbank Pay payment page. If you are a Dankort user, read +more about this feature at [Dankort][dankort-eu]{:target="_blank"}. As a merchant you can set a priority selection of payment application by -contacting [Swedbank Pay Support][swedbankpay-support]. The payer will always -be able to override this priority selection on the payment page. +contacting [Swedbank Pay Support][swedbankpay-support]{:target="_blank"}. +The payer will always be able to override this priority selection on the payment +page. If you want more information about Co-badge Card Choice for Dankort users, -please contact [Swedbank Pay Support][swedbankpay-support]. The example below -shows the payment window where the payer can choose between Dankort or Visa -before completing the payment. +please contact [Swedbank Pay Support][swedbankpay-support]{:target="_blank"}. +The example below shows the payment window where the payer can choose between +Dankort or Visa before completing the payment. ## How It Looks diff --git a/_includes/custom-styling.md b/_includes/custom-styling.md index 9e85bdf4b9..403da43236 100644 --- a/_includes/custom-styling.md +++ b/_includes/custom-styling.md @@ -11,7 +11,8 @@ below). ## Customizable Elements -With the arrival of our [accessibility compliant payment UI][wcag-presentation], +With the arrival of our +[accessibility compliant payment UI][wcag-presentation]{:target="_blank"}, the elements you can adjust are related to the CTA button. Available changes are: @@ -49,7 +50,7 @@ You can make the adjustments you want in the `style` object and include it in the `style` node of the script that loads the UI. Do you want to see the changes live before you put them to use? Stop by the -[Swedbank Pay Playground][playground] and give it a go! +[Swedbank Pay Playground][playground]{:target="_blank"} and give it a go! {:.code-view-header} **Payment UI loading script** diff --git a/_includes/instrument-mode.md b/_includes/instrument-mode.md index 9acbc10c9e..2e5b574b67 100644 --- a/_includes/instrument-mode.md +++ b/_includes/instrument-mode.md @@ -48,9 +48,9 @@ menu. Swedbank Pay provides a script to do this check, with the URL `ecom..payex.com/checkout/core/integration.` Environments available for you are `externalintegration` and `production`, and you can switch -integration between `checkout` and `paymentmenu`. Follow these links for [test -environment][test-env] and [production environment][prod-env] **Checkout** -scripts. +integration between `checkout` and `paymentmenu`. Follow these links for +[test environment][test-env]{:target="_blank"} and +[production environment][prod-env]{:target="_blank"} **Checkout** scripts. Add the script tag to your website and perform the javascript call `await payex.getAcceptedWallets()`. We will return a string array with the diff --git a/_includes/mobile-sdk-debugging.md b/_includes/mobile-sdk-debugging.md index 4b9a3f77d6..8c19fef45c 100644 --- a/_includes/mobile-sdk-debugging.md +++ b/_includes/mobile-sdk-debugging.md @@ -99,7 +99,7 @@ let configuration = SwedbankPaySDK.MerchantBackendConfiguration( ``` After you have verified that a domain works with WKWebView, please file an -[issue][ios-issues] to have it added to the SDK's bundled list. +[issue][ios-issues]{:target="_blank"} to have it added to the SDK's bundled list. [ios-issues]: https://github.com/SwedbankPay/swedbank-pay-sdk-ios/issues [ios-payment-url]: /checkout-v3/modules-sdks/mobile-sdk/ios#payment-url-and-external-applications diff --git a/_includes/payment-url.md b/_includes/payment-url.md index c657fa52b4..310f7b90c5 100644 --- a/_includes/payment-url.md +++ b/_includes/payment-url.md @@ -72,9 +72,10 @@ in {% if technical_reference_url contains "/checkout-v2" %} {% endif %} When implementing the Seamless View flow into a WebView in your mobile app, you -should use a [custom scheme][custom-scheme] or [Universal Link][universal-link] -in the `paymentUrl` for handling automatic switching between your app and the -payment app on the mobile device. +should use a [custom scheme][custom-scheme]{:target="_blank"} or +[Universal Link][universal-link]{:target="_blank"} in the `paymentUrl` for +handling automatic switching between your app and the payment app on the mobile +device. {% endif %} [custom-scheme]: https://developer.apple.com/documentation/uikit/inter-process_communication/allowing_apps_and_websites_to_link_to_your_content/defining_a_custom_url_scheme_for_your_app diff --git a/_includes/user-agent.md b/_includes/user-agent.md index a0607f3539..702282e5f0 100644 --- a/_includes/user-agent.md +++ b/_includes/user-agent.md @@ -1,9 +1,9 @@ ## User-Agent -The term [user agent][user-agent] is used for both the web browser used by the -payer as well as the system making HTTP requests towards Swedbank Pay's APIs. -The difference between these two and how they relate to each other is -illustrated in the below sequence diagram: +The term [user agent][user-agent]{:target="_blank"} is used for both the web +browser used by the payer as well as the system making HTTP requests towards +Swedbank Pay's APIs. The difference between these two and how they relate to +each other is illustrated in the below sequence diagram: ```plantuml @startuml "User Agents" diff --git a/checkout-v3/get-started/fundamental-principles.md b/checkout-v3/get-started/fundamental-principles.md index 8adfecdfd2..f5fcdae878 100644 --- a/checkout-v3/get-started/fundamental-principles.md +++ b/checkout-v3/get-started/fundamental-principles.md @@ -9,11 +9,12 @@ description: | ## Foundation -The **Swedbank Pay API Platform** is built using the [REST architectural -style][rest] and the request and responses come in the [JSON] format. The API -has predictable, resource-oriented URLs and use default HTTP features, like HTTP -authentication (using OAuth 2), HTTP methods and headers. These techniques are -widely used and understood by most HTTP client libraries. +The **Swedbank Pay API Platform** is built using the +[REST architectural style][rest]{:target="_blank"} and the request and responses +come in the [JSON] format. The API has predictable, resource-oriented URLs and +use default HTTP features, like HTTP authentication (using OAuth 2), HTTP +methods and headers. These techniques are widely used and understood by most +HTTP client libraries. ## Connection and Protocol @@ -24,16 +25,17 @@ connecting to Swedbank Pay's APIs. This is most likely due to the connection being made from the client with TLS 1.0 or even SSL, which are all insecure and deprecated. If such is the case, ensure that you are able to connect over a TLS 1.2 connection by reading information regarding your programming languages -and environments ([Java][java-tls], [PHP Curl][php-curl-tls], -[PHP Zend][php-zend-tls], [Ruby][ruby-tls], [Python][python-tls], -[Node.js Request][node-tls]). +and environments ([Java][java-tls]{:target="_blank"}, +[PHP Curl][php-curl-tls]{:target="_blank"}, [PHP Zend][php-zend-tls],{:target="_blank"} +[Ruby][ruby-tls]{:target="_blank"}, [Python][python-tls]{:target="_blank"}, +[Node.js Request][node-tls]{:target="_blank"}). -You can inspect [Swedbank Pay's TLS and cipher suite][ssllabs] support at -SSL Labs. Support for HTTP/2 in our APIs is being investigated. +You can inspect [Swedbank Pay's TLS and cipher suite][ssllabs]{:target="_blank"} +support at SSL Labs. Support for HTTP/2 in our APIs is being investigated. ## Postel's Robustness Principle -We encourage you to keep [Postel's robustness principle][robustness-principle] +We encourage you to keep [Postel's robustness principle][robustness-principle]{:target="_blank"} in mind. Build your integration in a way that is resilient to change, wherever it may come. Don't confine yourself to the limits of our current documentation examples. A `string` looking like a `guid` must still be handled and stored like @@ -91,8 +93,8 @@ different operations in the client, this task is moved to the server. The client simply follows links and performs operations provided by the API, given the current state of the resource. The server controls the state and lets the client know through hypermedia what's possible in the current state of the resource. To -get an [introduction to **hypermedia**, please watch this 20 minute -video][the-rest-and-then-some]. +get an +[introduction to **hypermedia**, please watch this 20 minute video][the-rest-and-then-some]{:target="_blank"}. {% include alert.html type="warning" icon="warning" header="Don't build URLs" body=" It is very important that only the base URLs of Swedbank Pay's APIs are @@ -252,20 +254,20 @@ manner across the entire API Platform. ### Currency -All currencies are expressed according to the [ISO 4217][iso-4217] standard, -e.g `SEK`, `EUR`, `NOK`. +All currencies are expressed according to the +[ISO 4217][iso-4217]{:target="_blank"} standard, e.g `SEK`, `EUR`, `NOK`. ### Dates -All dates are expressed according to the [ISO 8601][iso-8601] standard that -combine dates, time and timezone data into a string, e.g. +All dates are expressed according to the [ISO 8601][iso-8601]{:target="_blank"} +standard that combine dates, time and timezone data into a string, e.g. `2018-09-14T13:21:57.6627579Z`. ### Locale -When defining locale, we use the combination of [language][iso-639-1] -and [country codes][iso-3166]. Our payment menu UI is currently limited to -`nb-NO`, `sv-SE`, `da-DK` `fi-FI` and `en-US`. +When defining locale, we use the combination of [language][iso-639-1]{:target="_blank"} +and [country codes][iso-3166]{:target="_blank"}. Our payment menu UI is +currently limited to `nb-NO`, `sv-SE`, `da-DK` `fi-FI` and `en-US`. ### Monetary Amounts diff --git a/checkout-v3/get-started/setup.md b/checkout-v3/get-started/setup.md index 7636516413..a33866fb3b 100644 --- a/checkout-v3/get-started/setup.md +++ b/checkout-v3/get-started/setup.md @@ -48,7 +48,7 @@ with an access token. How to generate your access token: -**Log in to:** [The External Integration Merchant Portal](https://merchantportal.externalintegration.swedbankpay.com ) - For +**Log in to:** [The External Integration Merchant Portal](https://merchantportal.externalintegration.swedbankpay.com){:target="_blank"} - For testing environment. **Merchant details:** Here you will find information about your diff --git a/checkout-v3/get-started/terminology.md b/checkout-v3/get-started/terminology.md index b9e982c57b..619cd82775 100644 --- a/checkout-v3/get-started/terminology.md +++ b/checkout-v3/get-started/terminology.md @@ -51,7 +51,7 @@ menu_order: 12 {:.table .table-striped} | **One-phase payment flow** | A [one-phase][fundamentals] payment is a payment done in one step. The amount is settled in one transactional step. | | **Operation** | A payment operation determines what kind of payment that should be implemented. Available payment operations vary, depending on payment method. The most common operation all payment methods share is the Purchase operation. Card Payments have several others, such as [Verify][verify-url] and [Recur][recur]. | -| **Operations** | Operations consist of an array of contextual links / actions that direct the payment flow in a given state of the payment resource (i.e. creating a capture transaction, creating a reversal transaction, returning a redirect URL, etc). Operations are [HATEOAS][hateoas] driven and managed through API calls. | +| **Operations** | Operations consist of an array of contextual links / actions that direct the payment flow in a given state of the payment resource (i.e. creating a capture transaction, creating a reversal transaction, returning a redirect URL, etc). Operations are [HATEOAS][hateoas]{:target="_blank"} driven and managed through API calls. | ### P diff --git a/checkout-v3/modules-sdks/development-guidelines/code-of-conduct.md b/checkout-v3/modules-sdks/development-guidelines/code-of-conduct.md index 5b309d1f55..f4366d05d2 100644 --- a/checkout-v3/modules-sdks/development-guidelines/code-of-conduct.md +++ b/checkout-v3/modules-sdks/development-guidelines/code-of-conduct.md @@ -9,7 +9,8 @@ menu_order: 900 It is important that the projects governed by Swedbank Pay foster a collaborative, open, inclusive, positive and tolerant community. To underscore this, a `CODE_OF_CONDUCT.md` file from -[Contributor Covenant][contributor-covenant] should be added to the project: +[Contributor Covenant][contributor-covenant]{:target="_blank"} should be added +to the project: ## Contributor Code of Conduct @@ -55,8 +56,9 @@ appropriate to the circumstances. Maintainers are obligated to maintain confidentiality with regard to the reporter of an incident. This Code of Conduct is adapted from the -[Contributor Covenant][contributor-covenant], version 1.3.0, available at -[http://contributor-covenant.org/version/1/3/0/][version] +[Contributor Covenant][contributor-covenant]{:target="_blank"}, version 1.3.0, +available at +[http://contributor-covenant.org/version/1/3/0/][version]{:target="_blank"} The Code of Conduct should then be referenced from the `CONTRIBUTING` file, for example with the following paragraphs: diff --git a/checkout-v3/modules-sdks/development-guidelines/contributing.md b/checkout-v3/modules-sdks/development-guidelines/contributing.md index f8b4e316e5..af02bd2393 100644 --- a/checkout-v3/modules-sdks/development-guidelines/contributing.md +++ b/checkout-v3/modules-sdks/development-guidelines/contributing.md @@ -17,8 +17,8 @@ things you need to know. ## Getting Started -* Read and make sure you agree with the [Code of Conduct][coc]. -* Make sure you have a [GitHub account][github]. +* Read and make sure you agree with the [Code of Conduct][coc]{:target="_blank"}. +* Make sure you have a [GitHub account][github]{:target="_blank"}. * Then, you have three options: 1. Submit a ticket for your issue, assuming one does not already exist. * Clearly describe the issue including steps to reproduce when it is a @@ -32,14 +32,16 @@ If you choose option 3 (forking the repository), then please read on. ## Making Changes -* Create a new [branch][branching] from where you want to base your work. +* Create a new [branch][branching]{:target="_blank"} from where you want to + base your work. * This is usually the `master` or `develop` branch. * Please avoid working directly on the `master` and `develop` branch. -* Make [commits][commit] of logical units in the new branch. +* Make [commits][commit]{:target="_blank"} of logical units in the new branch. * Check for unnecessary space with `git diff --check` before committing. * Make sure your [commit messages][commit-practice] are well written and in the proper format. -* [Push][push] the branch to your [forked repository (remote)][remote]. +* [Push][push]{:target="_blank"} the branch to your + [forked repository (remote)][remote]{:target="_blank"}. * Submit a pull request for the pushed branch. [coc]: /checkout-v3/modules-sdks/development-guidelines/code-of-conduct diff --git a/checkout-v3/modules-sdks/development-guidelines/good-commit-practice.md b/checkout-v3/modules-sdks/development-guidelines/good-commit-practice.md index 32b4da8ea2..30c0f14181 100644 --- a/checkout-v3/modules-sdks/development-guidelines/good-commit-practice.md +++ b/checkout-v3/modules-sdks/development-guidelines/good-commit-practice.md @@ -5,15 +5,15 @@ menu_order: 1100 --- The following document is a fork of -[OpenStack's Git Commit Good Practice][good-practice], rewritten to suit -Swedbank Pay needs. It is based on experience doing code development, bug -troubleshooting and code review across a number of projects using Git. -Examination of other open source projects suggested they all follow a fairly -common practice. It is motivated by a desire to improve the quality of the -Git history in any repository. Quality is a hard term to define in computing; -one person's "Thing of Beauty" is another's "Evil Hack". We can, however, -come up with some general guidelines for what to do, or conversely what not -to do, when publishing Git commits for merge with a project. This topic can +[OpenStack's Git Commit Good Practice][good-practice]{:target="_blank"}, +rewritten to suit Swedbank Pay needs. It is based on experience doing code +development, bug troubleshooting and code review across a number of projects +using Git. Examination of other open source projects suggested they all follow a +fairly common practice. It is motivated by a desire to improve the quality of +the Git history in any repository. Quality is a hard term to define in +computing; one person's "Thing of Beauty" is another's "Evil Hack". We can, +however, come up with some general guidelines for what to do, or conversely what +not to do, when publishing Git commits for merge with a project. This topic can be split into two areas of concern: 1. The structured set/split of the code changes @@ -55,9 +55,9 @@ rule: * If a change is found to be flawed later, it may be necessary to revert the broken commit. This is much easier to do if there are not other unrelated code changes entangled with the original commit. -* When troubleshooting problems using Git's [bisect][bisect] capability, small - well defined changes will aid in isolating exactly where the code problem - was introduced. +* When troubleshooting problems using Git's [bisect][bisect]{:target="_blank"} + capability, small well defined changes will aid in isolating exactly where + the code problem was introduced. * When browsing history using Git annotate/blame, small well defined changes also aid in isolating exactly where & why a piece of code came from. diff --git a/checkout-v3/modules-sdks/development-guidelines/index.md b/checkout-v3/modules-sdks/development-guidelines/index.md index b2785503ad..00be2c8e2b 100644 --- a/checkout-v3/modules-sdks/development-guidelines/index.md +++ b/checkout-v3/modules-sdks/development-guidelines/index.md @@ -51,9 +51,9 @@ Code quality of course depends on a lot of other factors too, such as: written in. * Adhering to established style guides. * Good understanding of - [The Principles of Object Oriented Design][principles-of-object-oriented-design]. + [The Principles of Object Oriented Design][principles-of-object-oriented-design]{:target="_blank"}. * A good domain architecture, modeled after - [Domain Driven Design][domain-driven-design]. + [Domain Driven Design][domain-driven-design]{:target="_blank"}. ### Accessibility @@ -93,28 +93,29 @@ be perceived as accessible: on a developer machine without installing any external services, tools or libraries, unless they are handled by a package manager like NuGet. 3. Contributed code should be checked by a - [continuous integration][continuous-integration] server that labels the - status of pull request accordingly. If a test fails, the contributor - should be alerted of its failure through GitHub’s interface. + [continuous integration][continuous-integration]{:target="_blank"} + server that labels the status of pull request accordingly. If a test + fails, the contributor should be alerted of its failure through GitHub’s + interface. 6. All code contributions should be run through a public continuous integration server so build failures are visible to the contributor such that it can be fixed without any project manager’s involvement. 7. The development and branching process should preferably be based on an - existing scheme such as [GitFlow][gitflow] or GitHub Flow. + existing scheme such as [GitFlow][gitflow]{:target="_blank"} or GitHub Flow. 8. All development should be done in public. 1. Code should be pushed to GitHub regularly, so it’s possible to see progress. - 2. For incomplete features and bugfixes, [GitFlow][gitflow] with branch - prefixes such as `feature/` and `hotfix/` should be used + 2. For incomplete features and bugfixes, [GitFlow][gitflow]{:target="_blank"} + with branch prefixes such as `feature/` and `hotfix/` should be used 3. All code in development should be pushed as often as possible. ### Security All source code should be written in a secure way so it avoids the problems -enumerated in [OWASP Top 10][owasp-top-10] and [SANS 25][sans-25]. It should -preferably exist a test for each of these problems such that it is continually -verified that the code does not contain any of these problems now or in the -future. +enumerated in [OWASP Top 10][owasp-top-10]{:target="_blank"} and +[SANS 25][sans-25]{:target="_blank"}. It should preferably exist a test for each +of these problems such that it is continually verified that the code does not +contain any of these problems now or in the future. No source code should contain secrets, passwords or otherwise sensitive information. If such code is committed by accident, history should be @@ -123,7 +124,8 @@ rewritten through interactive rebasing as soon as possible and force-pushed. ## Licensing All of Swedbank Pay' open source software should be licensed under a liberal and -enterprise, closed source-compatible [software license][software-license]. +enterprise, closed source-compatible +[software license][software-license]{:target="_blank"}. ## Copyright @@ -154,11 +156,12 @@ They will be described in the following chapters. ### Versioning To release software, it needs to be versioned. Swedbank Pay's open source -packages should be versioned according to [semantic -versioning][semantic-versioning]. This means that whenever backward -compatibility is broken, the major version should be incremented. When a new -feature is added, the minor version should be incremented and when bug fixes and -other minor changes are introduced, the revision number should be incremented. +packages should be versioned according to +[semantic versioning][semantic-versioning]{:target="_blank"}. This means that +whenever backward compatibility is broken, the major version should be +incremented. When a new feature is added, the minor version should be +incremented and when bug fixes and other minor changes are introduced, the +revision number should be incremented. A version of the software should correspond to a commit in the Git repository. This commit should be tagged with the version number it represents and the @@ -171,14 +174,14 @@ representing that version should be tagged in Git with the value `1.2.5` and the commit should exist in the master branch. To help with automating versioning in .NET based projects, -[GitVersion][git-version] can be used. For most uses, -[GitVersionTask][gitversion-task] performs the job perfectly. -It understands [GitFlow][gitflow] and increments the version number -automatically based on which branch the code being built exists on. +[GitVersion][git-version]{:target="_blank"} can be used. For most uses, +[GitVersionTask][gitversion-task]{:target="_blank"} performs the job perfectly. +It understands [GitFlow][gitflow]{:target="_blank"} and increments the version +number automatically based on which branch the code being built exists on. ### Branching strategy -To make versioning easier, the Git repository should follow [GitFlow][gitflow], +To make versioning easier, the Git repository should follow [GitFlow][gitflow]{:target="_blank"}, GitHub Flow or derivates, so released and stable code is kept in the master branch, while unstable and pre-released code — if such is required — is kept in the develop branch. @@ -193,8 +196,9 @@ prefixes `feature`, `hotfix/`, etc. Software written for an environment that has a marketplace or other official storefront for applications (or “modules”, “extensions” and what have you) such as -[Apple’s App Store][apple-app-store] or [Google Play][google-play], -should try to publish the released software in these marketplaces. +[Apple’s App Store][apple-app-store]{:target="_blank"} or +[Google Play][google-play]{:target="_blank"}, should try to publish the released +software in these marketplaces. Releases should correspond to a tagged version number and a Release for the version should be created on GitHub. The GitHub Release should @@ -203,7 +207,7 @@ possibly by referring to blog entries or similar that describes them in more detail. To help with writing release notes, projects can use the tool -[GitReleaseNotes][git-release-notes]. +[GitReleaseNotes][git-release-notes]{:target="_blank"}. [apple-app-store]: https://appstore.com [code-of-conduct]: /checkout-v3/modules-sdks/development-guidelines/code-of-conduct diff --git a/checkout-v3/modules-sdks/development-guidelines/license.md b/checkout-v3/modules-sdks/development-guidelines/license.md index f4ed8d327a..6d16acce5e 100644 --- a/checkout-v3/modules-sdks/development-guidelines/license.md +++ b/checkout-v3/modules-sdks/development-guidelines/license.md @@ -7,9 +7,10 @@ menu_order: 1200 ## Licensing The licensing of Swedbank Pay's open source software should be one approved by -the [Open Source Initiative][osi] and preferably one that is compatible with -closed source, enterprise software. The [Apache 2.0 License][license] is -therefore a good fit and should be chosen when possible: +the [Open Source Initiative][osi]{:target="_blank"} and preferably one that is +compatible with closed source, enterprise software. The +[Apache 2.0 License][license]{:target="_blank"} is therefore a good fit and +should be chosen when possible: ```license Apache License diff --git a/checkout-v3/modules-sdks/index.md b/checkout-v3/modules-sdks/index.md index 9625331849..fd2770bc53 100644 --- a/checkout-v3/modules-sdks/index.md +++ b/checkout-v3/modules-sdks/index.md @@ -51,7 +51,7 @@ Swedbank Pay. {:.table .table-striped} | Platform | Module | Repository | | :--------------------------: | :--------------------------------------------------------------- | :-------------------------------------------- | -| ![WooCommerce][woo-icon] | [Swedbank Pay Payment Menu for WooCommerce][woo-checkout-link] | [`…woocommerce-checkout`][woo-checkout-repo] | +| ![WooCommerce][woo-icon] | [Swedbank Pay Payment Menu for WooCommerce][woo-checkout-link]{:target="_blank"} | [`…woocommerce-checkout`][woo-checkout-repo]{:target="_blank"} | ## Official SDKs @@ -68,10 +68,10 @@ SDKs are often used as a building block to construct a *Module*. {:.table .table-striped} | Platform | SDK | Repository | | :----------------------: | :------------------------------------------- | :----------------------------- | -| ![Android][android-icon] | [Swedbank Pay SDK for Android][android-link] | [`…sdk-android`][android-repo] | -| ![iOS][ios-icon] | [Swedbank Pay SDK for iOS][ios-link] | [`…sdk-ios`][ios-repo] | -| ![.NET][dotnet-icon] | [Swedbank Pay SDK for .NET][dotnet-link] | [`…sdk-dotnet`][dotnet-repo] | -| ![PHP][php-icon] | [Swedbank Pay SDK for PHP][php-link] | [`…sdk-php`][php-repo] | +| ![Android][android-icon] | [Swedbank Pay SDK for Android][android-link]{:target="_blank"} | [`…sdk-android`][android-repo]{:target="_blank"} | +| ![iOS][ios-icon] | [Swedbank Pay SDK for iOS][ios-link]{:target="_blank"} | [`…sdk-ios`][ios-repo]{:target="_blank"} | +| ![.NET][dotnet-icon] | [Swedbank Pay SDK for .NET][dotnet-link]{:target="_blank"} | [`…sdk-dotnet`][dotnet-repo]{:target="_blank"} | +| ![PHP][php-icon] | [Swedbank Pay SDK for PHP][php-link]{:target="_blank"} | [`…sdk-php`][php-repo]{:target="_blank"} | ## Official Libraries @@ -83,8 +83,8 @@ SDKs are often used as a building block to construct a *Module*. {:.table .table-striped} | Platform | Library | Repository | | :----------------------: | :---------------------------------------------------------- | :------------------------------------ | -| ![WooCommerce][woo-icon] | [Swedbank Pay Core plugin for WooCommerce][woo-core-link] | [`…woocommerce-core`][woo-core-repo] | -| ![.NET][dotnet-icon] | [Swedbank Pay SDK Extensions for .NET][dotnet-link] | [`…sdk-dotnet`][dotnet-repo] | +| ![WooCommerce][woo-icon] | [Swedbank Pay Core plugin for WooCommerce][woo-core-link]{:target="_blank"} | [`…woocommerce-core`][woo-core-repo]{:target="_blank"} | +| ![.NET][dotnet-icon] | [Swedbank Pay SDK Extensions for .NET][dotnet-link]{:target="_blank"} | [`…sdk-dotnet`][dotnet-repo]{:target="_blank"} | [android-icon]: /assets/img/logos/android.svg [android-link]: https://search.maven.org/artifact/com.swedbankpay.mobilesdk/mobilesdk diff --git a/checkout-v3/modules-sdks/mobile-sdk/android.md b/checkout-v3/modules-sdks/mobile-sdk/android.md index 2fbf8e195f..839aff0a53 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/android.md +++ b/checkout-v3/modules-sdks/mobile-sdk/android.md @@ -18,11 +18,11 @@ differences will be highlighted in the chapter on custom backends. The Android component of the Swedbank Pay Mobile SDK is distributed through Maven Central. It is split into two libraries in the -[`com.swedbankpay.mobilesdk`][maven-group] group: +[`com.swedbankpay.mobilesdk`][maven-group]{:target="_blank"} group: -* Core SDK: [`com.swedbankpay.mobilesdk:mobilesdk`][sdk-maven] +* Core SDK: [`com.swedbankpay.mobilesdk:mobilesdk`][sdk-maven]{:target="_blank"} * Merchant Backend Utilities: - [`com.swedbankpay.mobilesdk:mobilesdk-merchantbackend`][merchantbackend-maven] + [`com.swedbankpay.mobilesdk:mobilesdk-merchantbackend`][merchantbackend-maven]{:target="_blank"} If you are not using the Merchant Backend API in your backend, you only need to use the first one. Otherwise, you should add both libraries to your project to @@ -126,19 +126,21 @@ sequenceDiagram ``` The public API of the Android SDK is in the package -[`com.swedbankpay.mobilesdk`][dokka-pkg]. The main component is -[`PaymentFragment`][dokka-payfrag], a `Fragment` that handles a single payment -order. To use a `PaymentFragment`, it must have a -[`Configuration`][dokka-config]. In most cases it is enough to construct a -single `Configuration` and set it as the [default][dokka-payfrag-defconf]. In -more advanced cases you will need to subclass `PaymentFragment` and override -[`getConfiguration`][dokka-payfrag-getconf]. +[`com.swedbankpay.mobilesdk`][dokka-pkg]{:target="_blank"}. The main component +is [`PaymentFragment`][dokka-payfrag]{:target="_blank"}, a `Fragment` that +handles a single payment order. To use a `PaymentFragment`, it must have a +[`Configuration`][dokka-config]{:target="_blank"}. In most cases it is enough to +construct a single `Configuration` and set it as the +[default][dokka-payfrag-defconf]{:target="_blank"}. In more advanced cases you +will need to subclass `PaymentFragment` and override +[`getConfiguration`][dokka-payfrag-getconf]{:target="_blank"}. For using a backend implementing the Merchant Backend API, the SDK also provides utility classes in the package -[`com.swedbankpay.mobilesdk.merchantbackend`][dokka-pkg-merch]. The examples on -this page make use of these, including the `Configuration` implementation -[`MerchantBackendConfiguration`][dokka-merchconfig]. +[`com.swedbankpay.mobilesdk.merchantbackend`][dokka-pkg-merch]{:target="_blank"}. +The examples on this page make use of these, including the `Configuration` +implementation +[`MerchantBackendConfiguration`][dokka-merchconfig]{:target="_blank"}. ```kotlin val backendUrl = "https://example.com/swedbank-pay-mobile/" @@ -148,13 +150,14 @@ val configuration = MerchantBackendConfiguration.Builder(backendUrl) PaymentFragment.defaultConfiguration = configuration ``` -To start a payment, you need a [`PaymentOrder`][dokka-paymentorder], and, unless -making a guest payment, a [`Consumer`][dokka-consumer]. Using a `Consumer` makes -future payments by the same payer easier. +To start a payment, you need a +[`PaymentOrder`][dokka-paymentorder]{:target="_blank"}, and, unless making a +guest payment, a [`Consumer`][dokka-consumer]{:target="_blank"}. Using a +`Consumer` makes future payments by the same payer easier. -The semantics of `Consumer` properties are the same as the fields of the [`POST -/psp/consumers`][checkin-consumer] request. There are default values for the -`operation` and `language` properties +The semantics of `Consumer` properties are the same as the fields of the +[`POST/psp/consumers`][checkin-consumer] request. There are default values for +the `operation` and `language` properties (`ConsumerOperation.INITIATE_CONSUMER_SESSION` and `Language.ENGLISH`, respectively). @@ -168,13 +171,13 @@ val consumer = Consumer( Similarly, the semantics of `PaymentOrder` properties are the same as the fields of the [`POST /psp/paymentorders`][checkin-paymentorder] request. Sensible default values are provided for many of the properties. The `urls` property has -no default per se, but there are [convenience -constructors][dokka-paymentorderurls-init] available for it, and it is -recommended that you use them. Assuming you have the Android Payment Url Helper -endpoint set up with the specified static path relative to your backend url -(i.e. `sdk-callback/android-intent`), then using the one of the -`PaymentOrderUrls(context: Context, backendUrl: String)` variants will set the -`paymentUrl` correctly. +no default per se, but there are +[convenience constructors][dokka-paymentorderurls-init]{:target="_blank"} +available for it, and it is recommended that you use them. Assuming you have the +Android Payment Url Helper endpoint set up with the specified static path +relative to your backend url (i.e. `sdk-callback/android-intent`), then using +the one of the `PaymentOrderUrls(context: Context, backendUrl: String)` variants +will set the `paymentUrl` correctly. ```kotlin val paymentOrder = PaymentOrder( @@ -221,12 +224,14 @@ val paymentOrder = PaymentOrder( To start a payment, create a `PaymentFragment` and set its arguments according to the payment. The -[`PaymentFragment.ArgumentsBuilder`][dokka-payfrag-argbuilder] class is provided -to help with creating the argument bundle. In most cases you only need to worry -about the [`paymentOrder`][dokka-payfrag-argbuilder-paymentorder] property. The -payment process starts as soon as the `PaymentFragment` is visible. Note that -Digital Payments is currently opt-in, so that merchants can upgrade without too -much breaking changes and start using the new Digital Payments when ready. +[`PaymentFragment.ArgumentsBuilder`][dokka-payfrag-argbuilder]{:target="_blank"} +class is provided to help with creating the argument bundle. In most cases you +only need to worry about the +[`paymentOrder`][dokka-payfrag-argbuilder-paymentorder]{:target="_blank"} +property. The payment process starts as soon as the `PaymentFragment` is +visible. Note that Digital Payments is currently opt-in, so that merchants can +upgrade without too much breaking changes and start using the new Digital +Payments when ready. ```kotlin val arguments = PaymentFragment.ArgumentsBuilder() @@ -245,8 +250,8 @@ paymentFragment.arguments = arguments Note that the SDK only supports customer-checkin for version 2, and provides fallback for merchants in need of this. Then you need to supply a -[`consumer`][dokka-payfrag-argbuilder-consumer] and the ckeckoutV3 setting -becomes irrelevant. +[`consumer`][dokka-payfrag-argbuilder-consumer]{:target="_blank"} and the +Checkout v3 setting becomes irrelevant. ```kotlin val arguments = PaymentFragment.ArgumentsBuilder() @@ -260,11 +265,15 @@ paymentFragment.arguments = arguments // Now handle the fragment the same way as previously. ``` -To observe the payment process, use the [`PaymentViewModel`][dokka-paymentvm] -[of the containing `Activity`][dokka-activity-paymentvm]. When the -`PaymentViewModel` [signals][dokka-paymentvm-livestate] that the payment process -has reached a [final][dokka-paymentvm-state-isfinal] state, you should remove -the `PaymentFragment` and inform the user of the result. +To observe the payment process, use the +[`PaymentViewModel`][dokka-paymentvm]{:target="_blank"} +[of the containing `Activity`][dokka-activity-paymentvm]{:target="_blank"}. +When the +`PaymentViewModel` [signals][dokka-paymentvm-livestate]{:target="_blank"} +that the payment process has reached a +[final][dokka-paymentvm-state-isfinal]{:target="_blank"} state, you should +remove the `PaymentFragment` and inform the user of the +result. ```kotlin paymentViewModel.state.observe(this, Observer { @@ -278,8 +287,8 @@ paymentViewModel.state.observe(this, Observer { Note that checking the payment status after completion is outside the scope of the Mobile SDK. Your backend should collect any information it needs to perform -this check when it services the request to the [Payment Orders -endpoint][backend-payment-orders] made by the `PaymentFragment`. +this check when it services the request to the +[Payment Orders endpoint][backend-payment-orders] made by the `PaymentFragment`. ## Errors @@ -292,16 +301,16 @@ on the `PaymentViewModel`. When the state is `FAILURE` or `RETRYABLE_ERROR`, and the error condition was caused by an exception thrown from the `Configuration`, that exception is available in -[`PaymentViewModel.richState.exception`][dokka-paymentvm-richstate-exception]. +[`PaymentViewModel.richState.exception`][dokka-paymentvm-richstate-exception]{:target="_blank"}. The exception will be of any type throw by your `Configuration`. When using `MerchantBackendConfiguration`, this means it will be an `IOException` if there was a problem communicating with the backend, and an `IllegalStateException` if you have made a programming error (consult the exception message). A particular `IOException` to check for is -[`RequestProblemException`][dokka-problem-exception], which signals that the -backend responded with a Problem message. Another one is -[`UnexpectedResponseException`][dokka-unexpected-exception], which signals that -the SDK did not understand the backend response. +[`RequestProblemException`][dokka-problem-exception]{:target="_blank"}, which +signals that the backend responded with a Problem message. Another one is +[`UnexpectedResponseException`][dokka-unexpected-exception]{:target="_blank"}, +which signals that the SDK did not understand the backend response. ## Problems @@ -317,26 +326,28 @@ Android SDK will parse any RFC 7807 problem, but it has specialized data types for known problem types, namely the [Common Problems][swedbankpay-problems] and the [Merchand Backend Problems][backend-problems]. -Problems are presented as a [class hierarchy][dokka-problem] representing -different problem categories. All problems parsed from RFC 7807 messages are -classified as either [`Client`][dokka-problem-client] or -[`Server`][dokka-problem-server] problems. A `Client` problem is one caused by -client behavior, and is to be fixed by changing the request made to the server. -Generally, a `Client` problem is a programming error, with the possible -exception of -[`Problem.Client.MobileSDK.Unauthorized`][dokka-problem-client-mobilesdk-unauthorized]. +Problems are presented as a [class hierarchy][dokka-problem]{:target="_blank"} +representing different problem categories. All problems parsed from RFC 7807 +messages are classified as either +[`Client`][dokka-problem-client]{:target="_blank"} or +[`Server`][dokka-problem-server]{:target="_blank"} problems. A `Client` problem +is one caused by client behavior, and is to be fixed by changing the request +made to the server. Generally, a `Client` problem is a programming error, with +the possible exception of +[`Problem.Client.MobileSDK.Unauthorized`][dokka-problem-client-mobilesdk-unauthorized]{:target="_blank"}. A `Server` problem is one caused by a malfunction or lack of service in the server evironment. A `Server` problem is fixed by correcting the behavior of the malfunctioning server, or simply trying again later. Further, both `Client` and `Server` problems are categorized as `MobileSDK`, -`SwedbankPay`, or `Unknown`. `MobileSDK` problems are ones with [Merchant -Backend problem types][backend-problems], while `SwedbankPay` problems have -[Swedbank Pay API problem types][swedbankpay-problems]. `Unknown` problems are -of types that the SDK has no knowledge of. There is also the interface -[`SwedbankPayProblem`][dokka-swedbankpayproblem], which encompasses both -[`Client`][dokka-problem-client-swedbankpay] and -[`Server`][dokka-problem-server-swedbankpay] type `SwedbankPay` problems. +`SwedbankPay`, or `Unknown`. `MobileSDK` problems are ones with +[Merchant Backend problem types][backend-problems], while `SwedbankPay` problems +have [Swedbank Pay API problem types][swedbankpay-problems]. `Unknown` problems +are of types that the SDK has no knowledge of. There is also the interface +[`SwedbankPayProblem`][dokka-swedbankpayproblem]{:target="_blank"}, which +encompasses both [`Client`][dokka-problem-client-swedbankpay]{:target="_blank"} +and [`Server`][dokka-problem-server-swedbankpay]{:target="_blank"} type +`SwedbankPay` problems. ```kotlin paymentViewModel.richState.observe(this, Observer { @@ -389,15 +400,17 @@ payment menu. This requires no additional setup. If a third party application is launched, it will signal the return to the payment menu by opening the payment url, using a standard `ACTION_VIEW` -`Intent`. The payment url is built such that it uses the [Android Payment Url -Helper][android-helper], which serves an html page that converts the url to an -[intent url][android-intent-scheme] and redirects to it. The SDK has an intent -filter for that intent, so the SDK will receive it, bringing the containing -application to the foreground, and reloading the payment menu. If your Merchant -Backend serves the Android Payment Url Helper endpoint at the specified path, no -further setup is needed. - -Note that there is an [argument][dokka-payfrag-argbuilder-usebrowser] for +`Intent`. The payment url is built such that it uses the +[Android Payment Url Helper][android-helper]{:target="_blank"}, which serves an +html page that converts the url to an +[intent url][android-intent-scheme]{:target="_blank"} and redirects to it. The +SDK has an intent filter for that intent, so the SDK will receive it, bringing +the containing application to the foreground, and reloading the payment menu. If +your Merchant Backend serves the Android Payment Url Helper endpoint at the +specified path, no further setup is needed. + +Note that there is an +[argument][dokka-payfrag-argbuilder-usebrowser]{:target="_blank"} for debugging purposes that cause third-party web pages to be opened in an external application. In that case the process continues analogously to the external application case. Using this argument should not be necessary, however. If you diff --git a/checkout-v3/modules-sdks/mobile-sdk/bare-minimum-implementation.md b/checkout-v3/modules-sdks/mobile-sdk/bare-minimum-implementation.md index 0ee92a3fb6..df05889c97 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/bare-minimum-implementation.md +++ b/checkout-v3/modules-sdks/mobile-sdk/bare-minimum-implementation.md @@ -210,7 +210,7 @@ CocoaPods. ### Swift Package Manager The package repository URL for the SDK is -[`https://github.com/SwedbankPay/swedbank-pay-sdk-ios.git`][sdk-package-repo]. +[`https://github.com/SwedbankPay/swedbank-pay-sdk-ios.git`][sdk-package-repo]{:target="_blank"}. Add the `SwedbankPaySDK` library, there is no need to add the `SwedbankPaySDKMerchantBackend` library for the bare minimum implementation. @@ -246,9 +246,9 @@ You can also edit the `Info.plist` file directly, if you wish. ![Payment url scheme added in Info.plist editor][custom-scheme-2] To forward the custom-scheme payment urls to the SDK, implement the -[`application(_:open:options:)`][uiappdelegate-openurl] method in your -application delegate, and call `SwedbankPaySDK.open(url: url)` to let the SDK -handle the url. +[`application(_:open:options:)`][uiappdelegate-openurl]{:target="_blank"} method +in your application delegate, and call `SwedbankPaySDK.open(url: url)` to let +the SDK handle the url. ```swift func application(_ app: UIApplication, open url: URL, options: [UIApplication.OpenURLOptionsKey : Any] = [:]) -> Bool { @@ -371,17 +371,17 @@ backend. In this minimal implementation, we used custom URL scheme for the payment URL. This causes several issues in a production environment: -* On iOS, using custom URL schemes instead of Universal Links comes with several +* On iOS, using custom URL schemes instead of Universal Links comes with several drawbacks, including prompting the user with an additional confirmation popup as well as being unable to verify URL ownership to your specific app (other apps can declare the same custom URL scheme outside of your control). -* On Android, the SDK expects the app to be launched by external apps using an +* On Android, the SDK expects the app to be launched by external apps using an `intent:` scheme URL. This ties into the intent filter contained in the SDK, that will bring the containing application to the foreground and reload the payment menu. Because we're using the simpler custom URL scheme in this implementation, the payment menu will not reload and this will result in some payment instruments not behaving correctly. -* There are a few, albeit rare, scenarios where the user can end up launching +* There are a few, albeit rare, scenarios where the user can end up launching the Payment URL in the mobile browser on their phone. For URLs with custom schemes that's handled nicely, but for universal URLs, it's more problematic. This means that browsing to the payment URL ideally should return a view that diff --git a/checkout-v3/modules-sdks/mobile-sdk/configuration.md b/checkout-v3/modules-sdks/mobile-sdk/configuration.md index 8922bc6357..cbaf44cd64 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/configuration.md +++ b/checkout-v3/modules-sdks/mobile-sdk/configuration.md @@ -65,9 +65,10 @@ protocol. The protocol has two required methods: ## Android The Configuration is a subclass of the abstract class -[`Configuration`][dokka-config]. The class has two abstract methods. These -methods are suspending (asynchronous) Kotlin methods; a compatibility class is -provided if you need to implement your Configuration in Java instead. +[`Configuration`][dokka-config]{:target="_blank"}. The class has two abstract +methods. These methods are suspending (asynchronous) Kotlin methods; a +compatibility class is provided if you need to implement your Configuration in +Java instead. ```kotlin class MyConfiguration : Configuration() { diff --git a/checkout-v3/modules-sdks/mobile-sdk/custom-backend.md b/checkout-v3/modules-sdks/mobile-sdk/custom-backend.md index 58f87ac5b6..35127cd861 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/custom-backend.md +++ b/checkout-v3/modules-sdks/mobile-sdk/custom-backend.md @@ -13,16 +13,16 @@ SDK works with that as backend. ## Basic Backend Requirements -To support the SDK, your backend must be capable of at least [creating a payment -order][create-payment-order]. If you wish to use consumer identification, it -must also be able to [start an identification -session][initiate-consumer-session]. In addition to these, your backend should -serve the appropriate html documents at urls used for the -[`paymentUrl`][payment-url]; the content of these html documents will be +To support the SDK, your backend must be capable of at least +[creating a payment order][create-payment-order]. If you wish to use consumer +identification, it must also be able to +[start an identification session][initiate-consumer-session]. In addition to +these, your backend should serve the appropriate html documents at urls used for +the [`paymentUrl`][payment-url]; the content of these html documents will be discussed below, but it is noteworthy that they are different for payments from Android applications and those from iOS applications. Further, the urls used for as `paymentUrl` on iOS should be [configured as universal links for your iOS -application][ios-aasa]. +application][ios-aasa]{:target="_blank"}. ## Android Configuration @@ -316,11 +316,11 @@ action, if the Intent uri is equal to the `paymentUrl` of an ongoing payment (as reported by `ViewPaymentOrderInfo`), it will reload the payment menu of that payment. Therefore, if the `paymentUrl` is opened in the browser, that page must start an activity with such an Intent. This can be done by navigating to an -[intent scheme url][android-intent-scheme]. Note that the rules for following -intent-scheme navigations can sometimes cause redirects to those url not to -work. To work around this, the `paymentUrl` must serve a proper html page, which -attempts to immediately redirect to the intent-scheme url, but also has a link -the user can tap on. +[intent scheme url][android-intent-scheme]{:target="_blank"}. Note that the +rules for following intent-scheme navigations can sometimes cause redirects to +those url not to work. To work around this, the `paymentUrl` must serve a proper +html page, which attempts to immediately redirect to the intent-scheme url, but +also has a link the user can tap on. Refer to the intent scheme url documentation on how to form one. You should always include the package name so that your intent is not mistakenly routed to @@ -456,8 +456,8 @@ under the control of your backend. The purpose of this is to allow for one final escape hatch, in case the universal link mechanism fails to work. If this url is yet again opened in the browser, the backend responds with a redirect to to a custom-scheme url. (This _should_ only happen if your universal links -configuration is broken, or if iOS has somehow failed to load the [Apple -App-Site Association file][ios-aasa].) +configuration is broken, or if iOS has somehow failed to load the +[Apple App-Site Association file][ios-aasa]{:target="_blank"}.) {:.code-view-header} **Request** @@ -489,9 +489,9 @@ configuration. ## Apple App-Site Association As the iOS `paymentUrl` needs to be a universal link, the backend will also need -an [Apple App-Site Association file][ios-aasa]. This must be served at -`/.well-known/apple-app-site-association`, and it must associate any url used as -a `paymentUrl` with the app. +an [Apple App-Site Association file][ios-aasa]{:target="_blank"}. This must be +served at `/.well-known/apple-app-site-association`, and it must associate any +url used as a `paymentUrl` with the app. {:.code-view-header} **Request** @@ -663,9 +663,10 @@ Content-Type: text/plain Any exception you throw from your Configuration will be made available in `PaymentViewModel.exception` or `SwedbankPaySDKDelegate.paymentFailed(error:)`. You are therefore fully in control of the model you wish to use to report -errors. We recommend adopting the [Problem Details for HTTP APIs][rfc-7807] -convention for reporting errors from your backend. At the moment of writing, the -Android SDK also contains a [utility][dokka-problem] for parsing RFC 7807 +errors. We recommend adopting the +[Problem Details for HTTP APIs][rfc-7807]{:target="_blank"} convention for +reporting errors from your backend. At the moment of writing, the Android SDK +also contains a [utility][dokka-problem]{:target="_blank"} for parsing RFC 7807 messages to help with this. ## iOS Payment Menu Redirect Handling diff --git a/checkout-v3/modules-sdks/mobile-sdk/index.md b/checkout-v3/modules-sdks/mobile-sdk/index.md index 08fe0cd084..d4b2b1a508 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/index.md +++ b/checkout-v3/modules-sdks/mobile-sdk/index.md @@ -27,16 +27,16 @@ inside your application's native UI. It generates any html pages required to show the Swedbank Pay UI internally; it does not support using a Checkout or Payments web page that you host yourself. If doing the latter fits your case better, you can show your web page in a Web View instead. In that case, you may -benefit from the [collection of information about showing Checkout or Payments -in a Web View][plain-webview]. +benefit from the +[collection of information about showing Checkout or Payments in a Web View][plain-webview]. ## Prerequisites To start integrating the Swedbank Pay Mobile SDK, you need the following: * An agreement that includes [Swedbank Pay Digital Payments][checkout], - specifically [Enterprise][checkout-enterprise] or [Payments - Only][checkout-payments-only]. + specifically [Enterprise][checkout-enterprise] or + [Payments Only][checkout-payments-only]. * Obtained credentials (merchant Access Token) from Swedbank Pay through the Merchant Portal. Please observe that the Swedbank Pay Digital Payments implementations currently available encompasses the **`paymentmenu`** scope. diff --git a/checkout-v3/modules-sdks/mobile-sdk/ios.md b/checkout-v3/modules-sdks/mobile-sdk/ios.md index 1fe970f11e..1661aafc1e 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/ios.md +++ b/checkout-v3/modules-sdks/mobile-sdk/ios.md @@ -21,19 +21,20 @@ using a custom backend, you to not need to install the ## Swift Package Manager The SDK is available through the Swift Package Manager. This is the simplest way -of adding the SDK to an Xcode project. Follow the [Xcode -documentation][xcode-swiftpm] to add a SwiftPM dependency. +of adding the SDK to an Xcode project. Follow the +[Xcode documentation][xcode-swiftpm]{:target="_blank"} to add a SwiftPM +dependency. The package repository URL for the SDK is -[`https://github.com/SwedbankPay/swedbank-pay-sdk-ios.git`][sdk-package-repo]. +[`https://github.com/SwedbankPay/swedbank-pay-sdk-ios.git`][sdk-package-repo]{:target="_blank"}. Add the `SwedbankPaySDK` library, and the `SwedbankPaySDKMerchantBackend` if needed. ## CocoaPods -The SDK is also available through [CocoaPods][cocoapods]. There are two pods: -[SwedbankPaySDK][sdk-pod] for the core SDK, and `SwedbankPaySDKMerchantBackend` -for the Merchant Backend utilities. +The SDK is also available through [CocoaPods][cocoapods]{:target="_blank"}. +There are two pods: [SwedbankPaySDK][sdk-pod]{:target="_blank"} for the core +SDK, and `SwedbankPaySDKMerchantBackend` for the Merchant Backend utilities. Add the relevant dependencies in your `Podfile`: @@ -47,10 +48,10 @@ pod 'SwedbankPaySDKMerchantBackend', '~> {{ page.mobile_sdk_ios_version }}' ## Url Scheme and Associated Domain -The [Payment Url][payment-url] handling in the iOS SDK uses [Universal -Links][ios-universal-links], and additionally a [custom url -scheme][ios-custom-scheme] as a fallback mechanism. You must therefore set these -up in the app before using the SDK. +The [Payment Url][payment-url] handling in the iOS SDK uses +[Universal Links][ios-universal-links]{:target="_blank"}, and additionally a +[custom url scheme][ios-custom-scheme]{:target="_blank"} as a fallback mechanism. +You must therefore set these up in the app before using the SDK. The easiest way to add a url scheme to your app is to select the project file, go to the `Info` tab, scroll down to `URL Types`, and click the `+` button to @@ -67,11 +68,12 @@ You can also edit the `Info.plist` file directly, if you wish. ![Payment url scheme added in Info.plist editor][custom-scheme-2] -To set up universal links in your application, you first need to [add the -Associated Domains capability][xcode-add-cap]. Then, add your Merchant Backend's -domain as an [`applinks` associated domain][xcode-add-assoc-domain]. -Additionally, your merchant backend must have the appropriate [Apple App Site -Association][backend-aasa] file configured. +To set up universal links in your application, you first need to +[add the Associated Domains capability][xcode-add-cap]{:target="_blank"}. +Then, add your Merchant Backend's domain as an +[`applinks` associated domain][xcode-add-assoc-domain]{:target="_blank"}. +Additionally, your merchant backend must have the appropriate +[Apple App Site Association][backend-aasa] file configured. ![Associated Domains Configured][assoc-domains-entitlement] @@ -158,9 +160,9 @@ sequenceDiagram * ① Only pages tested to work with WKWebView are opened inside SwedbankPaySDKController. This list is updated as new pages are verified. -* ② Other pages are opened in Safari. See [the section on external - applications][ios-payment-url] for details on how the process returns to the - SDK afterwards. +* ② Other pages are opened in Safari. + See [the section on external applications][ios-payment-url] for details on + how the process returns to the SDK afterwards. * ③ See [the section on external applications][ios-payment-url] for details. The iOS SDK is contained in the module `SwedbankPaySDK`. @@ -328,8 +330,9 @@ func paymentFailed(error: Error) { Note that checking the payment status after completion is outside the scope of the Mobile SDK. Your backend should collect any information it needs to perform -this check when it services the request to the [Payment Orders -endpoint][backend-payment-orders] made by the `SwedbankPaySDKController`. +this check when it services the request to the +[Payment Orders endpoint][backend-payment-orders] made by the +`SwedbankPaySDKController`. ## Problems @@ -340,13 +343,13 @@ any type thrown by your `SwedbankPaySDKConfiguration`. In the case of `SwedbankPaySDK.MerchantBackendError`. If errors are encountered in the payment process, the Merchant Backend is -expected to respond with a [Problem Details for HTTP APIs (RFC 7807)][rfc-7807] +expected to respond with a [Problem Details for HTTP APIs (RFC 7807)][rfc-7807]{:target="_blank"} message. If the payment fails because of a problem, the `SwedbankPaySDK.MerchantBackendError` will be `.problem`, the associated value being the problem as parsed from the response. The iOS SDK will parse any RFC 7807 problem, but it has specialized data types for known problem types, namely -the [Common Problems][swedbankpay-problems] and the [Merchand Backend -Problems][backend-problems]. +the [Common Problems][swedbankpay-problems] and the +[Merchand Backend Problems][backend-problems]. Problems are expressed in Swift as `enum`s with associated values, representing a hierarchy of problem types. At the root of the hierarchy is `enum @@ -464,16 +467,16 @@ When the third party page wants to return to the payment menu, it navigates to the payment url. As this navigation is happening inside Safari, the payment url must provide some meaningful respose when Safari makes the request. However, even before that happens, consider the case where the payment url is a -[universal link][ios-universal-links] for the application using the SDK. -Assuming the [conditions][ios-universal-links-routing] for opening universal -links in the registered application are met, then Safari will never actually -request the payment url, but will instead open the application, giving it the -universal link in its Application Delegate's +[universal link][ios-universal-links]{:target="_blank"} for the application +using the SDK. Assuming the [conditions][ios-universal-links-routing]{:target="_blank"} +for opening universal links in the registered application are met, then Safari +will never actually request the payment url, but will instead open the +application, giving it the universal link in its Application Delegate's [`application(_:continue:restorationHandler:)`][uiappdelegate-continueuseractivity] -method. Recall that we enabled universal links for the backend url's domain [in -the installation instructions](#url-scheme-and-associated-domain). Note that the -merchant backend must also be properly configured to [enable universal -links][backend-aasa]. +method. Recall that we enabled universal links for the backend url's domain +[in the installation instructions](#url-scheme-and-associated-domain). Note that +thevmerchant backend must also be properly configured to +[enable universal links][backend-aasa]. The application delegate is, of course, squarely in the domain of the application; the SDK cannot hook into it automatically. Therefore, you need to @@ -519,24 +522,25 @@ the link from being opened in the application. As it stands, we need a way to get back to the application even when the payment url is opened in Safari. The simplest way of accomplishing this is to respond -with a redirect to a [custom scheme url][ios-custom-scheme]. Doing that will, -however, always show an unattractive confirmation alert before the user is -directed to the application. Therefore, let us first consider if there is a way -to reattempt the universal link navigation, while attempting to maximize the -chance of it being routed to the application. - -Reviewing the [conditions][ios-universal-links-routing] for universal links -opening in the registered application, we note two things: Firstly, the -navigation must originate from user interaction. Thus, opening the payment url -in Safari must produce a page with a control the user can interact with, which -must trigger a navigation to the payment url. Secondly, the navigation must be -to a domain different to the current page. This means that opening the payment -url must redirect to a page on a different domain, so that a navigation back to -the payment url from that page is given to the application to handle. - -As explained on the [mechant backend page][ios-paymenturl-helper], we solve this -by having the payment url respond with a redirect response to a page with a link -to the payment url (but see below). +with a redirect to a [custom scheme url][ios-custom-scheme]{:target="_blank"}. +Doing that will, however, always show an unattractive confirmation alert before +the user is directed to the application. Therefore, let us first consider if +there is a way to reattempt the universal link navigation, while attempting to +maximize the chance of it being routed to the application. + +Reviewing the [conditions][ios-universal-links-routing]{:target="_blank"} for +universal links opening in the registered application, we note two things: +Firstly, the navigation must originate from user interaction. Thus, opening the +payment url in Safari must produce a page with a control the user can interact +with, which must trigger a navigation to the payment url. Secondly, the +navigation must be to a domain different to the current page. This means that +opening the payment url must redirect to a page on a different domain, so that a +navigation back to the payment url from that page is given to the application to +handle. + +As explained on the [merchant backend page][ios-paymenturl-helper], we solve +this by having the payment url respond with a redirect response to a page with a +link to the payment url (but see below). ```mermaid sequenceDiagram @@ -579,9 +583,9 @@ may be removed or modified, though). This enables us to alter the behavior of the backend on the "same" payment url. To forward the custom-scheme payment urls to the SDK, implement the -[`application(_:open:options:)`][uiappdelegate-openurl] method in your -application delegate, and call `SwedbankPaySDK.open(url: url)` to let the SDK -handle the url. +[`application(_:open:options:)`][uiappdelegate-openurl]{:target="_blank"} method +in your application delegate, and call `SwedbankPaySDK.open(url: url)` to let +the SDK handle the url. ```swift func application( diff --git a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-sample-code.md b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-sample-code.md index d669c52960..15b90a4e36 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-sample-code.md +++ b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-sample-code.md @@ -7,11 +7,12 @@ description: | menu_order: 1300 --- -You can find sample implementations of the Merchant Backend at [this Github -repository][backend-samples]. Currently there are available the following: +You can find sample implementations of the Merchant Backend at +[this Github repository][backend-samples]{:target="_blank"}. Currently there are +available the following: -* [node.js][node-sample] -* [Java][java-sample] +* [node.js][node-sample]{:target="_blank"} +* [Java][java-sample]{:target="_blank"} Please refer to the sample code documentation for instructions for running a local development server, and/or deploying to selected cloud services. Do note @@ -28,7 +29,6 @@ a good starting point toward integration with your business systems. next_href="/checkout-v3/modules-sdks/mobile-sdk/other-features" next_title="Next: Other Features" %} - [backend-samples]: https://github.com/SwedbankPay/swedbank-pay-sdk-mobile-example-merchant [node-sample]: https://github.com/SwedbankPay/swedbank-pay-sdk-mobile-example-merchant/tree/main/examples/node.js/README.md [java-sample]: https://github.com/SwedbankPay/swedbank-pay-sdk-mobile-example-merchant/tree/main/examples/java/merchant/README.md diff --git a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-v2.md b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-v2.md index 1fa85d1aff..fdaf325114 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-v2.md +++ b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend-v2.md @@ -18,8 +18,8 @@ should behave. The Mobile SDK Merchant Backend API contains a total of six endpoints, three of which have statically defined paths. An OpenAPI specification is -[available][swagger]. (It may be easier to view it in the [Swagger -Editor][swagger-editor].) +[available][swagger]{:target="_blank"}. (It may be easier to view it in the +[Swagger Editor][swagger-editor]{:target="_blank"}.) The main part of the API is designed as a transparent wrapper around the Swedbank Pay API, which is the same one used in Checkout. Additionally, two @@ -101,15 +101,15 @@ hosts, you must manually allow them in your mobile app's configuration. ## Consumers Endpoint The `consumers` endpoint is used to start a consumer identification session. It -is specified as a transparent wrapper around the corresponding [Swedbank Pay -API][initiate-consumer-session]. The sample implementations do superficial input -validation, and forward the request to the Swedbank Pay API without further -processing. You are free to override this default behavior as you see fit in -your implementation, but the default should be fine for most use-cases. The -expected response is the same as the expected response to the Swedbank Pay API. -The default is to pass the response from Swedbank as-is; you should probably not -modify this behavior. Specifically, the response must contain the -`view-consumer-identification` operation. +is specified as a transparent wrapper around the corresponding +[Swedbank Pay API][initiate-consumer-session]. The sample implementations do +superficial input validation, and forward the request to the Swedbank Pay API +without further processing. You are free to override this default behavior as +you see fit in your implementation, but the default should be fine for most +use-cases. The expected response is the same as the expected response to the +Swedbank Pay API. The default is to pass the response from Swedbank as-is; you +should probably not modify this behavior. Specifically, the response must +contain the `view-consumer-identification` operation. {:.code-view-header} **Request** @@ -195,21 +195,21 @@ Content-Type: application/json ## Payment Orders Endpoint The `paymentorders` endpoint is used to create a new Payment Order. It is -specified as a transparent wrapper around the corresponding [Swedbank Pay -API][create-payment-order]. However, it is to be expected that your backend will -need to process the payment order both before making the Swedbank Pay API call, -and after receiving the response from Swedbank Pay. The sample implementations -validate the input, then create an internal unique identitifer for the payment -order, and set that as `paymentorder.payeeInfo.payeeReference`, before making -the Swedbank Pay call. After receiving the response, the backend stores the `id` -of the Payment Order for future use, and forwards the response to the SDK. - -Optionally, if your implementation uses [instrument mode -payments][instrument-mode], your backend can return the list of valid -instruments, along with an endpoint to change the instrument. If you do this, -you must also implement the Change Instrument endpoint. The Merchant Backend -Configuration on the client side can then use this endpoint to change the -instrument of an ongoing payment order. +specified as a transparent wrapper around the corresponding +[Swedbank Pay API][create-payment-order]. However, it is to be expected that +your backend will need to process the payment order both before making the +Swedbank Pay API call, and after receiving the response from Swedbank Pay. The +sample implementations validate the input, then create an internal unique +identifier for the payment order, and set that as +`paymentorder.payeeInfo.payeeReference`, before making the Swedbank Pay call. +After receiving the response, the backend stores the `id` of the Payment Order +for future use, and forwards the response to the SDK. + +Optionally, if your implementation uses [instrument mode payments][instrument-mode], +your backend can return the list of valid instruments, along with an endpoint to +change the instrument. If you do this, you must also implement the Change +Instrument endpoint. The Merchant Backend Configuration on the client side can +then use this endpoint to change the instrument of an ongoing payment order. A production implementation should validate the payment order also from a business logic perspective. This is, naturally, outside the scope of the SDK, as @@ -236,7 +236,8 @@ Content-Type: application/json | :--------------: | :------------- | :------- | :-------------------------- | | {% icon check %} | {% f paymentOrder, 0 %} | `object` | The payment order to create | -* ① The contents of `paymentorder` are omitted here. See [Checkout Documentation][create-payment-order] for details. +* ① The contents of `paymentorder` are omitted here. See + [Checkout Documentation][create-payment-order] for details. At this point, the Merchant Backend will preform necessary processing, and make a corresponding request to the Swedbank Pay API, using its secret access token. @@ -455,9 +456,9 @@ the root endpoint, and adding the `package` query parameter with the containing application's package name, and an `id` query parameter with a random value. The endpoint responds with an html document that attempts to immediately -redirect to an [Intent-scheme Url][android-intent-scheme]. That url is -constructed such that it uses the value of the `package` query parameter as the -target package of the intent. The action of the intent shall be +redirect to an [Intent-scheme Url][android-intent-scheme]{:target="_blank"}. +That url is constructed such that it uses the value of the `package` query +parameter as the target package of the intent. The action of the intent shall be `com.swedbankpay.mobilesdk.VIEW_PAYMENTORDER`; the SDK has an intent filter for this action. The uri (data) of the intent shall be the full url used in the request. The html document shall also contain a link to that same url. This is @@ -522,12 +523,12 @@ a specific `package`. ## iOS Payment Url Helper The iOS payment url helper endpoint is more involved than the Android one. While -a similar mechanism could be used with [custom url schemes][ios-custom-scheme], -doing so will not provide optimal user experience: custom schemes will show a -confirmation dialog before being routed to the handling application, and the -content of that dialog is not under developer control. Instead, the best -practice for assigning urls to applications is to use [Universal -Links][ios-universal-links]. +a similar mechanism could be used with +[custom url schemes][ios-custom-scheme]{:target="_blank"}, doing so will not +provide optimal user experience: custom schemes will show a confirmation +dialogue before being routed to the handling application, and the content of +that dialogue is not under developer control. Instead, the best practice for +assigning urls to applications is to use [Universal Links][ios-universal-links]{:target="_blank"}. With the merchant backend host and the iOS application using the SDK configured correctly, the payment url becomes a universal link. Universal links function @@ -538,16 +539,16 @@ this scenario, is does not matter what kind of response would be received by making a `GET` request to the payment url. Unfortunately, this is not guaranteed to happen. -As [documented][ios-universal-links-routing], universal links open the -registered application "when [the user] tap[s] links to your website within -Safari", but "When a user browses your website in Safari and taps a universal -link in the same domain, the system opens that link in Safari -- If the user -taps a universal link in a different domain, the system opens the link in your -app." This presents two preconditions: the navigation must originate from user -interaction, and the domain of the universal link must be different to the -domain of the current page. Also, practice has shown that universal links may -still sometimes fail to work as intended, so we must have some way of escaping -that situation. +As [documented][ios-universal-links-routing]{:target="_blank"}, universal links +open the registered application "when [the user] tap[s] links to your website +within Safari", but "When a user browses your website in Safari and taps a +universal link in the same domain, the system opens that link in Safari -- If +the user taps a universal link in a different domain, the system opens the link +in your app." This presents two preconditions: the navigation must originate +from user interaction, and the domain of the universal link must be different to +the domain of the current page. Also, practice has shown that universal links +may still sometimes fail to work as intended, so we must have some way of +escaping that situation. In order to have a foolproof system with optimal user experience, we must therefore work correctly in different scenarios: @@ -735,8 +736,8 @@ registered to the application. The iOS payment url helper endpoint must be configured as a universal link to the application for it to work correctly. Doing this requires an [Apple app site -association][ios-aasa] file on the host of the iOS payment url. This file must -be at a path relative to the host root (namely +association][ios-aasa]{:target="_blank"} file on the host of the iOS payment +url. This file must be at a path relative to the host root (namely `/.well-known/apple-app-site-association`), and is thus outside the scope of, but linked to, the merchant backend API. @@ -774,10 +775,10 @@ Content-Type: application/json ## Problems If there are any errors in servicing a request, they should be reported using -[Problem Details for HTTP APIs (RFC 7807)][rfc-7807] messages, like the -[Swedbank Pay APIs do][swedbankpay-problems]. In particular, if the Swedbank Pay -API response contains a problem, that problem should be forwarded to the client -making the original request. +[Problem Details for HTTP APIs (RFC 7807)][rfc-7807]{:target="_blank"} messages, +like the [Swedbank Pay APIs do][swedbankpay-problems]. In particular, if the +Swedbank Pay API response contains a problem, that problem should be forwarded +to the client making the original request. ## Merchant Backend Problems diff --git a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend.md b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend.md index c17bcfaff8..3b3b0ec26c 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/merchant-backend.md +++ b/checkout-v3/modules-sdks/mobile-sdk/merchant-backend.md @@ -20,8 +20,8 @@ should behave. The Mobile SDK Merchant Backend API contains a total of six endpoints, three of which have statically defined paths. An OpenAPI specification is -[available][swagger]. (It may be easier to view it in the [Swagger -Editor][swagger-editor].) +[available][swagger]{:target="_blank"}. (It may be easier to view it in the +[Swagger Editor][swagger-editor]{:target="_blank"}.) The main part of the API is designed as a transparent wrapper around the Swedbank Pay API, which is the same one used in Checkout. Additionally, two @@ -101,21 +101,22 @@ hosts, you must manually allow them in your mobile app's configuration. ## Payment Orders Endpoint The `paymentorders` endpoint is used to create a new Payment Order. It is -specified as a transparent wrapper around the corresponding [Swedbank Pay -API][create-payment-order]. However, it is to be expected that your backend will -need to process the payment order both before making the Swedbank Pay API call, -and after receiving the response from Swedbank Pay. The sample implementations -validate the input, then create an internal unique identitifer for the payment -order, and set that as `paymentorder.payeeInfo.payeeReference`, before making -the Swedbank Pay call. After receiving the response, the backend stores the `id` -of the Payment Order for future use, and forwards the response to the SDK. - -Optionally, if your implementation uses [instrument mode -payments][instrument-mode], your backend can return the list of valid -instruments, along with an endpoint to change the instrument. If you do this, -you must also implement the Change Instrument endpoint. The Merchant Backend -Configuration on the client side can then use this endpoint to change the -instrument of an ongoing payment order. +specified as a transparent wrapper around the corresponding +[Swedbank Pay API][create-payment-order]. However, it is to be expected that +your backend will need to process the payment order both before making the +Swedbank Pay API call, and after receiving the response from Swedbank Pay. The +sample implementations validate the input, then create an internal unique +identitifer for the payment order, and set that as +`paymentorder.payeeInfo.payeeReference`, before making the Swedbank Pay call. +After receiving the response, the backend stores the `id` of the Payment Order +for future use, and forwards the response to the SDK. + +Optionally, if your implementation uses +[instrument mode payments][instrument-mode], your backend can return the list of +valid instruments, along with an endpoint to change the instrument. If you do +this, you must also implement the Change Instrument endpoint. The Merchant +Backend Configuration on the client side can then use this endpoint to change +the instrument of an ongoing payment order. A production implementation should validate the payment order also from a business logic perspective. This is, naturally, outside the scope of the SDK, as @@ -142,8 +143,8 @@ Content-Type: application/json | :--------------: | :------------- | :------- | :-------------------------- | | {% icon check %} | {% f paymentOrder, 0 %} | `object` | The payment order to create | -* ① The contents of `paymentorder` are omitted here. See [Checkout - Documentation][create-payment-order] for details. +* ① The contents of `paymentorder` are omitted here. See + [Checkout Documentation][create-payment-order] for details. At this point, the Merchant Backend will preform necessary processing, and make a corresponding request to the Swedbank Pay API, using its secret access token. @@ -340,9 +341,9 @@ the root endpoint, and adding the `package` query parameter with the containing application's package name, and an `id` query parameter with a random value. The endpoint responds with an html document that attempts to immediately -redirect to an [Intent-scheme Url][android-intent-scheme]. That url is -constructed such that it uses the value of the `package` query parameter as the -target package of the intent. The action of the intent shall be +redirect to an [Intent-scheme Url][android-intent-scheme]{:target="_blank"}. +That url is constructed such that it uses the value of the `package` query +parameter as the target package of the intent. The action of the intent shall be `com.swedbankpay.mobilesdk.VIEW_PAYMENTORDER`; the SDK has an intent filter for this action. The uri (data) of the intent shall be the full url used in the request. The html document shall also contain a link to that same url. This is @@ -407,12 +408,12 @@ a specific `package`. ## iOS Payment Url Helper The iOS payment url helper endpoint is more involved than the Android one. While -a similar mechanism could be used with [custom url schemes][ios-custom-scheme], +a similar mechanism could be used with [custom url schemes][ios-custom-scheme]{:target="_blank"}, doing so will not provide optimal user experience: custom schemes will show a confirmation dialog before being routed to the handling application, and the content of that dialog is not under developer control. Instead, the best practice for assigning urls to applications is to use [Universal -Links][ios-universal-links]. +Links][ios-universal-links]{:target="_blank"}. With the merchant backend host and the iOS application using the SDK configured correctly, the payment url becomes a universal link. Universal links function @@ -423,16 +424,16 @@ this scenario, is does not matter what kind of response would be received by making a `GET` request to the payment url. Unfortunately, this is not guaranteed to happen. -As [documented][ios-universal-links-routing], universal links open the -registered application "when [the user] tap[s] links to your website within -Safari", but "When a user browses your website in Safari and taps a universal -link in the same domain, the system opens that link in Safari -- If the user -taps a universal link in a different domain, the system opens the link in your -app." This presents two preconditions: the navigation must originate from user -interaction, and the domain of the universal link must be different to the -domain of the current page. Also, practice has shown that universal links may -still sometimes fail to work as intended, so we must have some way of escaping -that situation. +As [documented][ios-universal-links-routing]{:target="_blank"}, universal links +open the registered application "when [the user] tap[s] links to your website +within Safari", but "When a user browses your website in Safari and taps a +universal link in the same domain, the system opens that link in Safari -- If +the user taps a universal link in a different domain, the system opens the link +in your app." This presents two preconditions: the navigation must originate +from user interaction, and the domain of the universal link must be different to +the domain of the current page. Also, practice has shown that universal links +may still sometimes fail to work as intended, so we must have some way of +escaping that situation. In order to have a foolproof system with optimal user experience, we must therefore work correctly in different scenarios: @@ -659,10 +660,10 @@ Content-Type: application/json ## Problems If there are any errors in servicing a request, they should be reported using -[Problem Details for HTTP APIs (RFC 7807)][rfc-7807] messages, like the -[Swedbank Pay APIs do][swedbankpay-problems]. In particular, if the Swedbank Pay -API response contains a problem, that problem should be forwarded to the client -making the original request. +[Problem Details for HTTP APIs (RFC 7807)][rfc-7807]{:target="_blank"} messages, +like the [Swedbank Pay APIs do][swedbankpay-problems]. In particular, if the +Swedbank Pay API response contains a problem, that problem should be forwarded +to the client making the original request. ## Merchant Backend Problems diff --git a/checkout-v3/modules-sdks/mobile-sdk/plain-webview.md b/checkout-v3/modules-sdks/mobile-sdk/plain-webview.md index 3fed2c8b33..f3fc1e7442 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/plain-webview.md +++ b/checkout-v3/modules-sdks/mobile-sdk/plain-webview.md @@ -25,14 +25,14 @@ Here is a list of common gotchas. Please read through the whole document, though * On Android, you need to set `webView.settings.domStorageEnabled = true` (used by some 3D-Secure pages) * Web Views will not launch apps by themselves. You _must_ intercept - navigations and launch apps yourself. See [External - Applications](#external-applications) for details. + navigations and launch apps yourself. See + [External Applications](#external-applications) for details. * On Android, `@JavascriptInterface` methods only take primitive arguments. You will need to `JSON.stringify` any complex arguments. * Some 3D-Secure pages will not work if you open them in a Web View. This appears to be related to them launching an external application, which, in - turn, opens a url in the browser app. See [Dealing with Picky Web - Pages](#dealing-with-picky-web-pages) for strategies. + turn, opens a url in the browser app. See + [Dealing with Picky Web Pages](#dealing-with-picky-web-pages) for strategies. * Some pages make use of Javascript dialogs. Web Views do not display these on their own; you must add support by your `WebCromeClient` or `WKUIDelegate`. * On Android, remember to call `webView.onResume()` and `webView.onPause()`. @@ -460,11 +460,13 @@ there is little your app can do beyond notifying the user about the missing app. When the `WebView` navigates to an http(s) url, your app should not simply start an Activity with the url, as that would usually mean opening the url in the browser. Instead, the Activity should only be started if it is not a browser. -Since Android 11 there is an `Intent` [flag][android-flag-non-browser] that does -exactly that. On earlier versions, your app must first query the system about -which app would be launched. Because of [privacy -enhancements][android-package-visibility] in Android 11, it is not possible to -use this method on Android 11; you must use the non-browser flag instead. +Since Android 11 there is an `Intent` +[flag][android-flag-non-browser]{:target="_blank"} that does exactly that. On +earlier versions, your app must first query the system about which app would be +launched. Because of +[privacy enhancements][android-package-visibility]{:target="_blank"} in Android +11, it is not possible to use this method on Android 11; you must use the +non-browser flag instead. {:.code-view-header} **Android** @@ -570,14 +572,14 @@ It is somewhat of a Quick and Dirty solution. We do not recommend this approach. ## iOS: Make paymentUrl A Universal Link -On iOS, the recommended way of assigning urls to apps is to use [Universal -Links][ios-universal-links]. This fits our use-case quite well, and indeed it is -what the SDK is designed to do too. When an external app executes the -`UIApplication.shared.open("https://example.com/perform-payment")`, then, -assuming Universal Links are configured correctly, that url will not be opened -in Safari, but will instead be opened in the application. You must then examine -the url, determine that it is a `paymentUrl` from your app, and reload the -`paymentUrl` in your web view. The payment process should then continue +On iOS, the recommended way of assigning urls to apps is to use +[Universal Links][ios-universal-links]{:target="_blank"}. This fits our use-case +quite well, and indeed it is what the SDK is designed to do too. When an +external app executes the `UIApplication.shared.open("https://example.com/perform-payment")`, +then, assuming Universal Links are configured correctly, that url will not be +opened in Safari, but will instead be opened in the application. You must then +examine the url, determine that it is a `paymentUrl` from your app, and reload +the `paymentUrl` in your web view. The payment process should then continue normally. Make sure that any navigation listeners and JavaScript hooks are in place before loading the `paymentUrl`. @@ -633,11 +635,12 @@ here, and it is anyway a bad user experience. ## Autoverify To The Rescue? -Since Android 6.0 it has been possible to use a [mechanism][android-autoverify] -very similar to Apple's Universal Links to "strongly" assing http(s) urls to -applications. This works by adding an `android:autoVerify="true"` attribute to -the intent filter, plus a `.well-known/assetlinks.json` file to the server. This -could solve the problems above, but it has its own issues, namely: +Since Android 6.0 it has been possible to use a +[mechanism][android-autoverify]{:target="_blank"} very similar to Apple's +Universal Links to "strongly" assing http(s) urls to applications. This works by +adding an `android:autoVerify="true"` attribute to the intent filter, plus a +`.well-known/assetlinks.json` file to the server. This could solve the problems +above, but it has its own issues, namely: * Requires Android 6.0 * Is really quite cumbersome to setup @@ -647,11 +650,12 @@ The SDK does not use this method. ## Android: Have PaymentUrl Redirect To An Intent Url Another option on Android is to allow the https `paymentUrl` to be opened in -Chrome normally, but have that url redirect to an [intent -url][android-intent-scheme]. That intent url can be made specific to your -application, making it so that unless the user has installed an application with -the same package id (from a non-Google-Play source, presumably), it will always -be opened in your app. This is what the SDK does. +Chrome normally, but have that url redirect to an +[intent url][android-intent-scheme]{:target="_blank"}. That intent url can be +made specific to your application, making it so that unless the user has +installed an application with the same package id (from a non-Google-Play +source, presumably), it will always be opened in your app. This is what the SDK +does. The SDK does this by having `paymentUrl` return an html page that immediately redirects. In some cases the redirect will be blocked, so the page also contains diff --git a/checkout-v3/modules-sdks/mobile-sdk/process-diagrams.md b/checkout-v3/modules-sdks/mobile-sdk/process-diagrams.md index ffc71897af..a2d5e6c8c6 100644 --- a/checkout-v3/modules-sdks/mobile-sdk/process-diagrams.md +++ b/checkout-v3/modules-sdks/mobile-sdk/process-diagrams.md @@ -234,9 +234,9 @@ When an external application is launched, the flow signals the return to the payment menu by again opening `paymentUrl`. This time, however, we cannot intercept it. The system then handles opening that url the usual way. For maximum compatibility, `paymentUrl` is a regular https url. On iOS, `paymentUrl` -is designed to be in format that is registered as a [Universal -Link][ios-universal-links] to the app, which causes the system to open -`paymentUrl` in the app. The example backend serves a +is designed to be in format that is registered as a +[Universal Link][ios-universal-links]{:target="_blank"} to the app, which causes +the system to open `paymentUrl` in the app. The example backend serves a `/.well-known/apple-app-site-association` file that assigns the paths under `/sdk-callback/` to be Universal Links to the application set in the configuration. The SDK defaults to building `paymentUrl` under this path. @@ -308,11 +308,11 @@ sequenceDiagram If the external flow ended with `paymentUrl` opened in the browser, we need a way to get back to the app. On Android, this is simple to accomplish by -redirecting to an [Android Intent Uri][android-intent-scheme]; the SDK and -backend work together to construct the Intent Uri to point to the correct app. -This Intent will cause the app to be brought back into focus, and the -PaymentFragment will recognize the `paymentUrl` and reload the payment menu. We -still need to have an actual html page served at `paymentUrl`, though, as the +redirecting to an [Android Intent Uri][android-intent-scheme]{:target="_blank"}; +the SDK and backend work together to construct the Intent Uri to point to the +correct app. This Intent will cause the app to be brought back into focus, and +the PaymentFragment will recognize the `paymentUrl` and reload the payment menu. +We still need to have an actual html page served at `paymentUrl`, though, as the redirect may be blocked in some scenarios. If that happens, the page will also contain a link the user can tap on, which opens the same Intent Uri. diff --git a/checkout-v3/payment-presentations.md b/checkout-v3/payment-presentations.md index 082e488295..71deb2a034 100644 --- a/checkout-v3/payment-presentations.md +++ b/checkout-v3/payment-presentations.md @@ -22,7 +22,8 @@ to take. If you're using a Redirect integration, you are all set and can skip this step. If you're using a Seamless View integration, you need to do the following: -1. Download the [domain file][payex-domain-file] (right click and "Save as"). +1. Download the [domain file][payex-domain-file]{:target="_blank"} + (right click and "Save as"). - Make sure you do not change, edit or manipulate the file in any way, shape or form. - The file should have **NO EXTENSION**, meaning there should not be any @@ -40,7 +41,7 @@ following: 3. Verify that the file has been uploaded correctly by opening the site. You should see a series of letters and numbers. - You can compare it to our own verification file, found on - [this site][swp-file-site]. + [this site][swp-file-site]{:target="_blank"}. - If done correctly, they should look identical. If you're using our **iOS SDK**, make sure that the `webViewBaseURL` is set to @@ -65,7 +66,7 @@ further instructions and assistance. Apple Pay provides nonprofit organizations a simple and secure way to accept donations. To register your nonprofit organization for Apple Pay, please visit -[Benevity][benevity-donation-setup]. +[Benevity][benevity-donation-setup]{:target="_blank"}. You’ll be asked to provide basic information about your organization. Note that the **Apple Developer Team ID** is an **optional** field, so this is not needed. @@ -88,7 +89,8 @@ Guidelines. Unless you have already accepted as part of signing your agreement with Swedbank Pay, we can provide the following links for digital signature in -[Sweden][apple-pay-tc-sign-sweden] and [Norway][apple-pay-tc-sign-norway]. +[Sweden][apple-pay-tc-sign-sweden]{:target="_blank"} and +[Norway][apple-pay-tc-sign-norway]{:target="_blank"}. If you are unable to sign the Apple Pay Web Terms and Conditions in Swedish or Norwegian digitally, please use the @@ -134,7 +136,7 @@ Account and check out almost instantly across apps and sites. ### Merchant ID You need to sign up for a **Google Developer Account** and -[create a **business profile** and **payment profile**][google-pay-profile]. +[create a **business profile** and **payment profile**][google-pay-profile]{:target="_blank"}. After creating the business profile, you will be able to see your Merchant ID on the top right corner of the page. We need that ID in order to activate Google @@ -142,8 +144,8 @@ Pay for you. However, be sure to register your domain/package and submit screenshots of your integration for approval. Login to -[Google Pay™ & Wallet Console][google-pay-profile], go to the -**Google Pay™ API tab** and upload the screenshots and submit your +[Google Pay™ & Wallet Console][google-pay-profile]{:target="_blank"}, go +to the **Google Pay™ API tab** and upload the screenshots and submit your integration for approval. The screenshots should be of the entire buyflow process (ex: add to cart, checkout, payment, confirmation - if available). Your **Merchant ID** will only work in production environment once Google complete @@ -158,15 +160,17 @@ agreement with Swedbank Pay, you can e-mail us it at **Which Google Pay™ documentation and guidelines should you use if you** **are an android merchant?** -[Google Pay Android Developer Documentation][android-googlepay-devdoc], -[Google Pay Android Integration Checklist][android-googlepay-checklist] and the +[Google Pay Android Developer Documentation][android-googlepay-devdoc]{:target="_blank"}, +[Google Pay Android Integration Checklist][android-googlepay-checklist]{:target="_blank"} +and the [Google Pay Android Brand Guidelines][android-googlepay-brand-guidelines]. **Which Google Pay™ documentation and guidelines should you use if you** **are a web merchant?** -[Google Pay Web Developer Documentation][web-googlepay-devdoc], -[Google Pay Web Integration Checklist][web-googlepay-checklist] and the -[Google Pay Web Brand Guidelines][web-googlepay-brand-guidelines]. +[Google Pay Web Developer Documentation][web-googlepay-devdoc]{:target="_blank"}, +[Google Pay Web Integration Checklist][web-googlepay-checklist]{:target="_blank"} +and the +[Google Pay Web Brand Guidelines][web-googlepay-brand-guidelines].{:target="_blank"} **Do you as a merchant need to take additional steps with regards to the** **Google Pay™ payment button or other hosted components to your website?** @@ -177,8 +181,9 @@ option to pay with Google Pay™ should appear in your implementation, as long as your payer's device supports Google Pay™. Please remember that you do must adhere to Google Pay™ API's -[Acceptable Use Policy][acceptable-use-policy] and accept the terms defined in -the Google Pay™ API's [Terms of Service][google-pay-tos]. +[Acceptable Use Policy][acceptable-use-policy]{:target="_blank"} and accept the +terms defined in the Google Pay™ API's +[Terms of Service][google-pay-tos]{:target="_blank"}. **If our SDK generates an [IsReadyToPayRequest][irtp-request] or a** **[PaymentDataRequest][pd-request] on behalf of you as a merchant, do you need** @@ -191,8 +196,9 @@ option to pay with Google Pay™ should appear in your implementation, as long as your payer's device supports Google Pay™. Please remember that you do must adhere to Google Pay™ API's -[Acceptable Use Policy][acceptable-use-policy] and accept the terms defined in -the Google Pay™ API's [Terms of Service][google-pay-tos]. +[Acceptable Use Policy][acceptable-use-policy]{:target="_blank"} and accept the +terms defined in the Google Pay™ API's +[Terms of Service][google-pay-tos]{:target="_blank"}. ### Implementation Details diff --git a/checkout-v3/test-data.md b/checkout-v3/test-data.md index 2595d877ce..9bae8ca8f7 100644 --- a/checkout-v3/test-data.md +++ b/checkout-v3/test-data.md @@ -12,7 +12,7 @@ menu_order: 6 When implementing Digital Payments, you can use the test data related to the different payment methods listed below. To see Digital Payments in live action, -please visit the [Playground][playground]. +please visit the [Playground][playground]{:target="_blank"}. To test a checked-in user in the Playground, please use the following test data: