Invoice – Redirect

Availability: Note that this invoice integration is no longer available in Sweden. If you are a Swedish merchant and wish to offer invoice as a payment option, this has to be done through our payment order implementation.

Introduction

When properly set up in your merchant/webshop site and the payer starts the purchase process, you need to make a POST request towards Swedbank Pay with your Purchase information. This will generate a payment object with a unique paymentID. You will receive a redirect URL to a Swedbank Pay payment page.
You need to redirect the payer’s browser to that specified URL so that the payer can enter the invoice details in a secure Swedbank Pay environment.
Swedbank Pay will redirect the payer’s browser to - one of two specified URLs, depending on whether the payment session is followed through completely or cancelled beforehand. Please note that both a successful and rejected payment reach completion, in contrast to a cancelled payment.
When you detect that the payer reach your completeUrl , you need to do a GET request to receive the state of the transaction, containing the paymentID generated in the first step, to receive the state of the transaction.

Step 1: Create The Payment

An invoice payment is always two-phased based - you create an Authorize transaction, that is followed by a Capture or Cancel request.

Callback URL: It is mandatory to set a callbackUrl in the POST request creating the payment. When callbackUrl is set, Swedbank Pay will send a POST request to this URL when the payer has fulfilled the payment. Upon receiving this POST request, a subsequent GET request towards the id of the payment generated initially must be made to receive the state of the transaction.

GDPR: GDPR sensitive data such as email, phone numbers and social security numbers must not be used directly in request fields such as payerReference. If it is necessary to use GDPR sensitive data, it must be hashed and then the hash can be used in requests towards Swedbank Pay.

To initiate the payment process, you need to make a POST request to Swedbank Pay. Our payment example below uses the [FinancingConsumer] (/old-implementations/payment-instruments-v1/invoice/technical-reference/financing-consumer) value. All valid options when posting a payment with operation equal to FinancingConsumer, are described in features.

How It Looks

screenshot of the first Invoice redirect page

screenshot of the second Invoice redirect page

Financing Consumer Request

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
38

{
    "payment": {
        "operation": "FinancingConsumer",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [
            {
                "type": "Invoice",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "generatePaymentToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "urls": {
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/logo.png",
            "termsOfServiceUrl": "https://example.com/terms.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "PR123",
            "payeeName": "Merchant1",
            "productCategory": "PC1234",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
    "invoice": {
        "invoiceType": "PayExFinancingSe"
        }
    }
}

payment object

The payment object contains information about the specific payment.

operation string

The operation that the payment is supposed to perform. The FinancingConsumer operation is used in our example.

intent string

Authorization is the only intent option for invoice. Reserves the amount, and is followed by a cancellation or capture of funds.

currency string

NOK, SEK, DKK, USD or EUR.

prices object

The prices resource lists the prices related to a specific payment.

type string

Use the value ``.See the prices resource for more information.

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.

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.

description string(40)

A textual description of the purchase. Maximum length is 40 characters.

userAgent string

The user agent of the payer. Should typically be set to the value of the User-Agent header sent by the payer’s web browser.

language string

sv-SE, nb-NO or en-US.

urls object

The urls resource lists urls that redirects users to relevant sites.

hostUrl array

The array of URLs valid for embedding of Swedbank Pay Seamless Views. If not supplied, view-operation will not be available.

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. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both.

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. It must be a picture with maximum 50px height and 400px width. HTTPS is required.

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.

payeeInfo object

The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.

payeeId string

This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.

payeeReference string(30)

A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the transaction.number or the payeeReference is sent to the acquirer. If Swedbank Pay handles the settlement, the transaction.number is sent to the acquirer and the payeeReference must be in the format of A-Za-z0-9 and string(30). If you handle the settlement, Swedbank Pay will send the payeeReference and it will be limited to the format of string(12). All characters must be digits. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.

payeeName string

The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.

productCategory string(50)

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 a split settlement on the payment. The different subsite values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown subsite value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of A-Za-z0-9.

payer string

The payer object, containing information about the payer.

payerReference string

The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if generateRecurrenceToken, RecurrenceToken, generatePaymentToken or paymentToken is true.

Financing Consumer Response

Response

1
2

HTTP/1.1 200 OK
Content-Type: application/json

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
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73

{
    "payment": {
        "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "instrument": "Invoice",
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "state": "Ready",
        "operation": "FinancingConsumer",
        "intent": "Authorization",
        "currency": "SEK",
        "amount": 0,
        "remainingCaptureAmount": 1000,
        "remainingCancellationAmount": 1000,
        "remainingReversalAmount": 500,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "prices": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "transactions": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions"
        },
        "authorizations": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations"
        },
        "captures": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures"
        },
        "reversals": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals"
        },
        "cancellations": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations"
        },
        "payeeInfo": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo"
        },
        "payers": {
            "id": "/psp/trustly/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "urls": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "settings": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings"
        },
        "approvedLegalAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress"
        },
        "maskedApprovedLegalAddress": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/maskedapprovedlegaladdress"
        }
    },
    "operations": [
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH"
        },
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
            "rel": "create-authorize",
            "method": "POST"
        },
        {
            "href": "https://api.externalintegration.payex.com/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/approvedlegaladdress",
            "rel": "create-approved-legal-address",
            "method": "POST"
        }
    ]
}

Invoice Flow

The sequence diagram below shows the two requests you have to send to Swedbank Pay to make a purchase. The diagram also shows the process of a complete purchase in high level.

sequenceDiagram
    Payer->>Merchant: Start purchase
    activate Merchant
    note left of Merchant: First API request
    Merchant->>-Swedbank Pay: POST <Invoice Payment> (operation=FinancingConsumer)
    activate Swedbank Pay
    Swedbank Pay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: authorization page
    activate Payer
    note left of Payer: redirect to Swedbank Pay
    Payer->>-Swedbank Pay: enter Payer details
    activate Swedbank Pay
    Swedbank Pay-->>-Payer: redirect to merchant
    activate Payer
    note left of Payer: redirect back to Merchant
    Payer->>-Merchant: access merchant page
    activate Merchant
    note left of Merchant: Second API request
    Merchant->>-Swedbank Pay: GET <Invoice payment>
    activate Swedbank Pay
    Swedbank Pay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: display purchase result

Options after posting a payment

Head over to after payment to see what you can do when a payment is completed. Here you will also find info on Cancel, and Reversal.