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.
Required | Field | Type | Description |
---|---|---|---|
check ︎︎︎︎︎ | hostUrls |
array |
The array of URLs valid for embedding of Swedbank Pay Hosted Views. |
check | completeUrl |
string |
The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 order to inspect it further. See completeUrl for details. |
check | 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. |
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 URL that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
|
callbackUrl |
string |
The URL to the API endpoint receiving POST requests on transaction activity related to the payment order. |
|
logoUrl |
string |
With permission and activation on your contract, sending in a logoUrl will replace the Swedbank Pay logo with the logo sent in. If you do not send in a logoUrl , then no logo and no text is shown. Without permission or activation on your contract, sending in a logoUrl has no effect. Read more about this in Custom Logo. |
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 instruments which trigger SCA.
This includes 3-D Secure card payments, credit 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 instruments 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 instruments 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.
The paymentUrl
is the URL Swedbank Pay will provide to the third party for
handling the redirect back to your site or app. When receiving the payer back
on the paymentUrl
either in an app or web page, it is important to restore the
Seamless View to let the payment finalize the flow. 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
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json
{
"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": "http://merchant.com/path/to/tems"
}
}
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 his or her 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 order 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 URL that Swedbank Pay will redirect back to when the payment menu needs to be loaded, to inspect and act on the current status of the payment. See paymentUrl for details. |
└➔ 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 |
With permission and activation on your contract, sending in a logoUrl will replace the Swedbank Pay logo with the logo sent in. If you do not send in a logoUrl , then no logo and no text is shown. Without permission or activation on your contract, sending in a logoUrl has no effect. Read more about this in Custom Logo. |
└➔ 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. |