Enterprise – Urls

URLs

When creating a Payment Order, the urls field of the paymentOrder contains the related URLs, including where the payer is redirected when going forward with or canceling a payment session, as well as the callback URL that is used to inform the payee (merchant) of changes or updates made to underlying payments or transaction.

Show fields

Required	Field	Type	Description
︎︎︎︎︎	`hostUrls`	`array`	The array of valid host URLs.
	`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
	`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an `abort` request of the `payment` or `paymentorder`.
	`paymentUrl`	`string`	The `paymentUrl` represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used.
	`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment order. See callback for details.
	`logoUrl`	`string`	The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
	`termsOfServiceUrl`	`string`	The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.

Payment Url

For our Seamless Views, the field called paymentUrl will be used when the payer is redirected out of the Seamless View (the iframe). The payer is redirected out of frame when selecting payment methods which trigger SCA. This includes 3-D Secure card payments, installment account, invoice, MobilePay, monthly invoice payments, Trustly and Vipps.

The URL should represent the page of where the Payment Order Seamless View was hosted originally, such as the checkout page, shopping cart page, or similar. Basically, paymentUrl should be set to the same URL as that of the page where the JavaScript for the Seamless View was added to in order to initiate the payment process.

Please note that the paymentUrl must be able to invoke the same JavaScript URL from the same Payment Order as the one that initiated the payment process originally, so it should include some sort of state identifier in the URL. The state identifier is the ID of the order, shopping cart or similar that has the URL of the Payment stored.

With paymentUrl in place, the retry process becomes much more convenient for both the integration and the payer.

paymentUrl is used by the Seamless View flow and must be used for WebView-based app implementations. Some payment methods only work when owning the full browser page (no use of <iframe>), this will be solved by doing a full browser (top frame) redirect out of the Seamless View. 3-D Secure requires this, for example.

For mobile flows, some payment methods work best when app-to-app switching is enabled and handled automatically (Swish, Vipps etc). To solve this, it is important that the third party app or site understand where to redirect the payer back to after the flow on their end is completed.

Refresh your payment menu after the payer’s return!: The paymentUrl is the URL Swedbank Pay will provide to the third party for handling the redirect back to your site or app. When the payer returns from the paymentUrl either in an app or a web page, it is vital that you refresh the Seamless View payment menu so the payment flow can be completed. Failing to do so could lead to issues.

For in-app it is important that you either implement the onPaymentCompleted event or let the Seamless View redirect to the completeUrl before intercepting the WebView. If you intercept the WebView when the payer’s device is redirected to the paymentUrl it can lead to issues. If you want to handle payment errors in your own code, you should also subscribe to other events provided by the Seamless View JavaScript and shut down the Seamless View if any of these events occur.

Events to subscribe to for full control over the payment flow are can be found in Seamless View Events.

When implementing the Seamless View flow into a WebView in your mobile app, you should use a custom scheme or Universal Link in the paymentUrl for handling automatic switching between your app and the payment app on the mobile device.

URLs Resource

It is possible to perform a GET request on the urls resource to retrieve its contents.

Request

1
2
3
4

GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls/ HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0     // Version optional for 3.0 and 2.0

Response

1
2
3

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/2.0

1
2
3
4
5
6
7
8
9
10
11
12
13

{
    "paymentorder": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
    "urls": {
        "id": "/psp/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/urls",
        "hostUrls": [ "https://example.com", "https://example.net" ],
        "completeUrl": "https://example.com/payment-complete",
        "cancelUrl": "https://example.com/payment-cancelled",
        "paymentUrl": "https://example.com/perform-payment",
        "callbackUrl": "http://api.example.com/payment-callback",
        "logoUrl": "http://merchant.com/path/to/logo.png",
        "termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
    }
}

Field	Type	Description
`paymentOrder`	`string`	The relative URL and unique identifier of the `payment` resource this `urls` belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
`urls`	`object`	The URLs object.
`id`	`string`	The relative URL and unique identifier of the `urls` resource this `urls` belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.
`hostsUrl`	`string`	An array of the whitelisted URLs that are allowed as parents to a Hosted View, typically the URL of the web shop or similar that will embed a Hosted View within it.
`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an `abort` request of the `payment` or `paymentorder`.
`paymentUrl`	`string`	The `paymentUrl` represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used.
`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment. See callback for details.
`logoUrl`	`string`	The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
`termsOfServiceUrl`	`string`	The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.