Payment Menu

Payer Aware Payment Menu

schedule 4 min read

A payment menu tailored to the payer.

Edit "Payer Aware Payment Menu" on GitHub

Payer Aware Payment Menu

To maximize the experience of your payers, you should implement the Payer Aware Payment Menu by identifying each payer with a unique identifier. It is important that you enforce a good SCA (Strong Consumer Authentication) strategy when authenticating the payer. The payer identifier must then be sent with the creation of the payment order to Swedbank Pay. This will enable Swedbank Pay to render a unique payment menu experience for each payer. It will also increase the chance for a frictionless payment.

By identifying your payers, they are able to store payment information for future payments by setting the generatePaymentToken value to true. This will enable the Swedbank Pay Payment Menu to show stored payment instrument details for future purchases. The payer is, by default, asked if they want to store their payment details, so even with generatePaymentToken set to true, it is still up to the payer if they want the details stored or not.

info

Please note that not all payment instruments provided by Swedbank Pay support Payer Awareness today.

BYO Payment Menu

Payment Menu is versatile and can be configured in such a way that it functions like a single payment instrument. In such configuration, it is easy to Bring Your Own Payment Menu, i.e. building a customized payment menu in our own user interface.

Add Stored Payment Instrument Details

When building a custom payment menu, features like adding new stored payment instrument details (i.e. “Add new card”) is something that needs to be provided in your UI.

This can be achieved by forcing the creation of a paymentToken by setting disableStoredPaymentDetails to true in a Purchase payment (if you want to withdraw money and create the token in the same operation), or by performing a verification (without withdrawing any money).

Setting disableStoredPaymentDetails to true will turn off all stored payment details for the current purchase. The payer will also not be asked if they want to store the payment detail that will be part of the purchase. When you use this feature it is important that you have asked the payer in advance if it is ok to store their payment details for later use.

Most often you will use the disableStoredPaymentDetails feature in combination with the Instrument Mode capability. If you build your own menu and want to show stored payment details, you will need to set the disableStoredPaymentDetails to true. It is important that you then store the paymentToken in your system or call Swedbank Pay with the payerReference to get all active payment tokens registered on that payer when building your menu. See the abbreviated Purchase example below.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE", 
        "instrument": null
        "generateRecurrenceToken": true,
        "generatePaymentToken": true,
        "disableStoredPaymentDetails": true,
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "paymentUrl": "https://example.com/perform-payment",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditoons.pdf",
            "logoUrl": "https://example.com/logo.png"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite"
        }
   }
}
Required Field Type Description  
check paymentorder object The payment order object.  
check └➔ operation string The operation that the payment order is supposed to perform.  
check └➔ currency string The currency of the payment.  
check └➔ amount integer The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK.  
check └➔ vatAmount integer The payment’s VAT (Value Added Tax) amount, entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount. This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged.  
check └➔ description string The description of the payment order.  
check └➔ generateRecurrenceToken bool Determines whether a recurrence token should be generated. A recurrence token is primarily used to enable future recurring payments – with the same token – through server-to-server calls. Default value is false.  
  └➔ disableStoredPaymentDetails bool Setting to true will turn off all stored payment details for the current purchase. When you use this feature it is important that you have asked the payer in advance if it is ok to store their payment details for later use.  
check └➔ userAgent string The user agent of the payer.  
check └➔ language string The language of the payer.  
check └➔ urls object The urls object, containing the URLs relevant for the payment order.  
check └─➔ hostUrls array The array of URIs valid for embedding of Swedbank Pay Seamless 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.  
  └─➔ cancelUrl string The URI to redirect the payer to if the payment is canceled, either by the payer or by the merchant trough an abort request of the payment or paymentorder.  
  └─➔ paymentUrl string The URI 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.  
check └─➔ callbackUrl string The URI to the API endpoint receiving POST requests on transaction activity related to the payment order.  
check └─➔ termsOfServiceUrl string The URI to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.  
check └─➔ 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.  
check └➔ payeeInfo string The payeeInfo object, containing information about the payee.  
check └─➔ payeeId string The ID of the payee, usually the merchant ID.  
check └─➔ payeeReference string(30) A unique reference from the merchant system. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
  └─➔ payeeName string The name of the payee, usually the name of the merchant.  
  └─➔ productCategory string A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process.  
  └─➔ orderReference string(50) The order reference should reflect the order reference found in the merchant’s systems.  
  └─➔ subsite String(40) The subsite field can be used to perform split settlement on the payment. The subsites must be resolved with Swedbank Pay reconciliation before being used.  

GDPR

Remember that you will have the responsibility to enforce GDPR requirements and let the payer remove active payment tokens when they want. It is up to you how to implement this functionality on your side but Swedbank Pay has the API you need to ensure that cleaning up old data is easy. It is possible to query for all active payment tokens registered on a specific payerReference. Then you can either remove all tokens for that payer or only a subset of all tokens.