Enterprise – Request Delivery Information

Request Delivery Information

Swedbank Pay provides the possibility to return delivery information from payment methods which support this. You do this by adding the field requestDeliveryInfo in your payment order request and setting it to true. The returned delivery information will appear in the payer field after the payment has been paid, and not the initial response. You have to perform a GET to see it.

Only payment methods which support this will return delivery information. If you only want to show payment methods which support this in you menu, you can also add the field restrictedToDeliveryInfoInstruments and setting it to true. This will leave out all payment methods which can’t return delivery information.

You are currently only able to request delivery information from Apple Pay, Click to Pay and Google Pay™, but we will add support for more payment methods going forward. No changes are required at your (the merchant’s) end to be able to offer more payment methods at a later time.

Request Delivery Info Request

The fields themselves are bools which must be added in the paymentorder field of the request, like the example below.

Request

1
2
3
4

POST /psp/paymentorders 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

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
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123

{
    "paymentorder": {
        "requestDeliveryInfo": true,
        "restrictedToDeliveryInfoInstruments": true,
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "productName": "Checkout3", // Removed in 3.1, can be excluded in 3.0 if version is added in header
        "urls": {
            "hostUrls": [ "https://example.com", "https://example.net" ], 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://api.example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite",
            "siteId": "MySiteId"
        },  
        "payer": {
            "digitalProducts": false,
            "nationalIdentifier": {
                "socialSecurityNumber": "199710202392",
                "countryCode": "SE"
            }
            "firstName": "Leia",
            "lastName": "Ahlström",
            "email": "leia@payex.com",
            "msisdn": "+46787654321",
            "payerReference": "AB1234",
            "shippingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "Helgestavägen 9",
                "coAddress": "",
                "city": "Solna",
                "zipCode": "17674",
                "countryCode": "SE"
            },
            "billingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "Helgestavägen 9",
                "coAddress": "",
                "city": "Solna",
                "zipCode": "17674",
                "countryCode": "SE"
            },
            "accountInfo": {
                "accountAgeIndicator": "04",
                "accountChangeIndicator": "04",
                "accountPwdChangeIndicator": "01",
                "shippingAddressUsageIndicator": "01",
                "shippingNameIndicator": "01",
                "suspiciousAccountActivity": "01"
            }
        },  
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 5,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 0,
                "vatPercent": 2500,
                "amount": 1500,
                "vatAmount": 375
            },
            {
                "reference": "I1",
                "name": "InvoiceFee",
                "type": "PAYMENT_FEE",
                "class": "Fees",
                "description": "Fee for paying with Invoice",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 1900,
                "vatPercent": 0,
                "amount": 1900,
                "vatAmount": 0,
                "restrictedToInstruments": [
                    "Invoice-PayExFinancingSe"
                ]
            }
        ],
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}

Show fields

Required	Field	Type	Description
	`paymentOrder`	`object`	The payment order object.
	`requestDeliveryInfo`	`bool`	Set to `true` if you want Swedbank Pay to return delivery information from the payment methods which support this. It will be visible in a GET response after the payment has been completed.
	`restrictedToDeliveryInfoInstruments`	`bool`	Set to `true` if you want to restrict your payment menu to only include payment methods which return delivery info.
	`operation`	`string`	Determines the initial operation, defining the type of payment order created.
	`currency`	`string`	The currency of the payment.
	`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`	The description of the payment order.
	`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`	The language of the payer.
	`productName`	`string`	Used to tag the payment as Digital Payments v3.0. Mandatory for Digital Payments v3.0, either in this field or the header, as you won’t get the operations in the response without submitting this field.
	`implementation`	`string`	Indicates which implementation to use.
	`urls`	`object`	The `urls` object, containing the URLs relevant for the payment order.
	`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 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`.
	`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.
	`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`	The ID of the payee, usually the merchant ID.
	`payeeReference`	`string`	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 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 name of the payee, usually the name of the merchant.
	`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`.
	`siteId`	`string(15)`	`siteId` is used for split settlement transactions when you, as a merchant, need to specify towards AMEX which sub-merchant the transaction belongs to. Must be in the format of `A-Za-z0-9`.
	`payer`	`object`	The `payer` object containing information about the payer relevant for the payment order.
	`digitalProducts`	`bool`	Set to `true` for merchants who only sell digital goods and only require `email` and/or `msisdn` as shipping details. Set to `false` if the merchant also sells physical goods.
	`nationalIdentifier`	`object`	The national identifier object.
	`socialSecurityNumber`	`string`	The payer’s social security number.
	`countryCode`	`string`	The country code of the payer.
	`firstName`	`string`	The first name of the payer.
	`lastName`	`string`	The last name of the payer.
	`email`	`string`	The e-mail address of the payer. Will be used to prefill the Checkin as well as on the payer’s profile, if not already set. Increases the chance for frictionless 3-D Secure 2 flow .
	`msisdn`	`string`	The mobile phone number of the Payer. Will be prefilled on Checkin page and used on the payer’s profile, if not already set. The mobile number must have a country code prefix and be 8 to 15 digits in length. The field is related to 3-D Secure 2 .
	`payerReference`	`string`	A reference used in Enterprise integrations to recognize the payer in the absence of SSN and/or a secure login. Read more about this in the payerReference feature section.
	`shippingAddress`	`object`	The shipping address object related to the `payer`. The field is related to 3-D Secure 2 .
	`firstName`	`string`	The first name of the addressee – the receiver of the shipped goods.
	`lastName`	`string`	The last name of the addressee – the receiver of the shipped goods.
	`streetAddress`	`string`	Payer’s street address. Maximum 50 characters long.
	`coAddress`	`string`	Payer’ s c/o address, if applicable.
	`zipCode`	`string`	Payer’s zip code
	`city`	`string`	Payer’s city of residence.
	`countryCode`	`string`	Country code for country of residence.
	`billingAddress`	`object`	The billing address object containing information about the payer’s billing address.
	`firstName`	`string`	The first name of the payer.
	`lastName`	`string`	The last name of the payer.
	`streetAddress`	`string`	The street address of the payer. Maximum 50 characters long.
	`coAddress`	`string`	The CO-address (if used)
	`zipCode`	`string`	The postal number (ZIP code) of the payer.
	`city`	`string`	The city of the payer.
	`countryCode`	`string`	`SE`, `NO`, or `FI`.
	`accountInfo`	`object`	Object related to the `payer` containing info about the payer’s account.
	`accountAgeIndicator`	`string`	Indicates the age of the payer’s account. `01` (No account, guest checkout) `02` (Created during this transaction) `03` (Less than 30 days old) `04` (30 to 60 days old) `05` (More than 60 days old)
	`accountChangeIndicator`	`string`	Indicates when the last account changes occurred. `01` (Changed during this transaction) `02` (Less than 30 days ago) `03` (30 to 60 days ago) `04` (More than 60 days ago)
	`accountChangePwdIndicator`	`string`	Indicates when the account’s password was last changed. `01` (No changes) `02` (Changed during this transaction) `03` (Less than 30 days ago) `04` (30 to 60 days ago) `05` (More than 60 days old)
	`shippingAddressUsageIndicator`	`string`	Indicates when the payer’s shipping address was last used. `01`(This transaction) `02` (Less than 30 days ago) `03` (30 to 60 days ago) `04` (More than 60 days ago)
	`shippingNameIndicator`	`string`	Indicates if the account name matches the shipping name. `01` (Account name identical to shipping name) `02` (Account name different from shipping name)
	`suspiciousAccountActivity`	`string`	Indicates if there have been any suspicious activities linked to this account. `01` (No suspicious activity has been observed) `02` (Suspicious activity has been observed)
	`orderItems`	`array`	The array of items being purchased with the order. Note that authorization `orderItems` will not be printed on invoices, so lines meant for print must be added in the Capture request. The authorization `orderItems` will, however, be used in the Merchant Portal when captures or reversals are performed, and might be shown other places later. It is required to use this field to be able to send Capture `orderItems`. `Capture` requests should only contain items meant to be captured from the order.
	`reference`	`string`	A reference that identifies the order item.
	`name`	`string`	The name of the order item.
	`type`	`string`	`PRODUCT`, `SERVICE`, `SHIPPING_FEE`, `PAYMENT_FEE` `DISCOUNT`, `VALUE_CODE` or `OTHER`. The type of the order item. `PAYMENT_FEE` is the amount you are charged with when you are paying with invoice. The amount can be defined in the `amount` field below.
	`class`	`string`	The classification of the order item. Can be used for assigning the order item to a specific product category, such as `MobilePhone`. Note that `class` cannot contain spaces and must follow the regex pattern `[\w-]*`. Swedbank Pay may use this field for statistics.
	`itemUrl`	`string`	The URL to a page that can display the purchased item, product or similar.
︎︎︎	`imageUrl`	`string`	The URL to an image of the order item.
	`description`	`string`	A 40 character length textual description of the purchase.
	`discountDescription`	`string`	The human readable description of the possible discount.
	`quantity`	`number`	The 4 decimal precision quantity of order items being purchased.
	`quantityUnit`	`string`	The unit of the quantity, such as `pcs`, `grams`, or similar. This is used for your own book keeping.
	`unitPrice`	`integer`	The price per unit of order item, including VAT.
	`discountPrice`	`integer`	If the order item is purchased at a discounted price. This field should contain that price, including VAT.
	`vatPercent`	`integer`	The percent value of the VAT multiplied by 100, so `25%` becomes `2500`.
	`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.
	`restrictedToInstruments`	`array`	A list of the payment methods you wish to restrict the payment to. Currently `Invoice` only. `Invoice` supports the subtypes `PayExFinancingNo`, `PayExFinancingSe` and `PayMonthlyInvoiceSe`, separated by a dash, e.g.; `Invoice-PayExFinancingNo`. Default value is all supported payment methods. Use of this field requires an agreement with Swedbank Pay. You can restrict fees and/or discounts to certain payment methods by adding this field to the orderline you want to restrict. Use positive amounts to add fees and negative amounts to add discounts.
	`riskIndicator`	`array`	This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to prompt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase.
	`deliveryEmailAdress`	`string`	For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelihood of a 3-D Secure authentication for the payer.
	`deliveryTimeFrameIndicator`	`string`	Indicates the merchandise delivery timeframe. `01` (Electronic Delivery) `02` (Same day shipping) `03` (Overnight shipping) `04` (Two-day or more shipping)
	`preOrderDate`	`string`	For a pre-ordered purchase. The expected date that the merchandise will be available. Format: `YYYYMMDD`
	`preOrderPurchaseIndicator`	`string`	Indicates whether the payer is placing an order for merchandise with a future availability or release date. `01` (Merchandise available) `02` (Future availability)
	`shipIndicator`	`string`	Indicates shipping method chosen for the transaction. `01` (Ship to cardholder’s billing address) `02` (Ship to another verified address on file with merchant) `03` (Ship to address that is different than cardholder’s billing address) `04` (Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields) `05` (Digital goods, includes online services, electronic giftcards and redemption codes) `06` (Travel and Event tickets, not shipped) `07` (Other, e.g. gaming, digital service)
	`giftCardPurchase`	`bool`	`true` if this is a purchase of a gift card.
	`reOrderPurchaseIndicator`	`string`	Indicates whether the cardholder is reordering previously purchased merchandise. `01` (First time ordered) `02` (Reordered).
	`pickUpAddress`	`object`	If `shipIndicator` set to `04`, then prefill this with the payers `pickUpAddress` of the purchase to decrease the risk factor of the purchase.
	`name`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `name` of the purchase to decrease the risk factor of the purchase.
	`streetAddress`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `streetAddress` of the purchase to decrease the risk factor of the purchase. Maximum 50 characters long.
	`coAddress`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `coAddress` of the purchase to decrease the risk factor of the purchase.
	`city`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `city` of the purchase to decrease the risk factor of the purchase.
	`zipCode`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `zipCode` of the purchase to decrease the risk factor of the purchase.
	`countryCode`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `countryCode` of the purchase to decrease the risk factor of the purchase.

Request Delivery Info Response

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
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

{
    "paymentOrder": {
        "id": "/psp/paymentorders/ca59fa8a-3423-40e5-0f77-08d9d133750b",
        "created": "2022-01-07T07:58:26.1300282Z",
        "updated": "2022-01-07T08:17:44.6839034Z",
        "operation": "Purchase", 
        "state": "Ready", 
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "language": "sv-SE",
        "availableInstruments": [
            "CreditCard",
            "Invoice-PayExFinancingSe",
            "Invoice-PayMonthlyInvoiceSe",
            "Swish",
            "CreditAccount",
            "Trustly"
        ],  
        "instrumentMode": false,
        "guestMode": false,
       "payer": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
        },
        "orderItems": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        }
      },
    "operations": [  
                {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel":"update-order",
          "method":"PATCH",
          "contentType":"application/json"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
          "rel": "abort",
          "method": "PATCH",
          "contentType": "application/json"
        }
    ]
}

Show fields

Field	Type	Description
`paymentOrder`	`object`	The payment order object.
`id`	`string`	The relative URL and unique identifier of the `paymentorder` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`created`	`string`	The ISO-8601 date of when the payment order was created.
`updated`	`string`	The ISO-8601 date of when the payment order was updated.
`operation`	`string`	`Purchase`
`state`	`string`	`Ready`, `Pending`, `Failed` or `Aborted`. Indicates the state of the payment order. Does not reflect the state of any ongoing payments initiated from the payment order. This field is only for status display purposes.
`currency`	`string`	The currency of the payment order.
`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 40 character length textual description of the purchase.
`initiatingSystemUserAgent`	`string`	The user agent of the HTTP client making the request, reflecting the value sent in the `User-Agent` header with the initial `POST` request which created the Payment.
`language`	`string`	`sv-SE`, `nb-NO`, `da-DK`, `en-US` or `fi-FI`.
`availableInstruments`	`string`	A list of payment methods available for this payment.
`implementation`	`string`	The merchant’s Digital Payments implementation type. `Enterprise` or `PaymentsOnly`. We ask that you don’t build logic around this field’s response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table.
`integration`	`string`	The merchant’s Digital Payments integration type. `HostedView` (Seamless View) or `Redirect`. This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don’t build logic around this field’s response. It is mainly for information purposes, as the integration types might be subject to name changes. If this should happen, updated information will be available in this table.
`instrumentMode`	`bool`	Set to `true` or `false`. Indicates if the payment is initialized with only one payment method available.
`guestMode`	`bool`	Set to `true` or `false`. Indicates if the payer chose to pay as a guest or not. When using the Enterprise implementation, this is triggered by not including a `payerReference` or `nationalIdentifier` in the original payment order request.
`payer`	`id`	The URL to the `payer` resource where information about the payer can be retrieved.
`orderItems`	`id`	The URL to the `orderItems` resource where information about the order items can be retrieved.
`operations`	`array`	The array of operations that are possible to perform on the payment order in its current state. As this is an initialized payment, the available operations are `abort`, `update-order` and `redirect-checkout` or `view-checkout`, depending on the integration. See Operations for details.