Online Payments – 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

{
    "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"
        },   
        "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@swedbankpay.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"
            }
        }
    }
}

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. Possible options are Purchase, [Abort](/checkout-v3/features/payment-operations/abort/) [Verify](/checkout-v3/features/optional/verify), [UnscheduledPurchase](/checkout-v3/features/optional/unscheduled), [Recur](/checkout-v3/features/optional/recur) and [Payout](/checkout-v3/features/optional/payout).

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. The amount displayed is the final amount the payer paid for their order, including any payment method specific discounts or fees.

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](/checkout-v3/technical-reference/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 Online Payments v3.0. Mandatory for Online 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`](/checkout-v3/technical-reference/complete-url) 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](/checkout-v3/features/payment-operations/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`](/checkout-v3/technical-reference/payee-info) for details.

payeeId string

The ID of the payee, usually the merchant ID.

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

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.

class string

Classification of the order item. No spaces; must match [\w-]*.

itemUrl string

URL to a page that can display the purchased item, product or similar.

imageUrl string

URL to an image of the order item.

description string

A textual [description](/checkout-v3/technical-reference/description) of the purchase. Maximum length is 40 characters.

discountDescription string

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.

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

vatAmount integer

restrictedToInstruments array

Restrict this order line to certain instruments. Requires agreement with Swedbank Pay.

riskIndicator array

Optional info to help verify the payer; reduces likelihood of 3-D Secure 2.0 step-up.

deliveryEmailAdress string

Email address used for electronic delivery.

deliveryTimeFrameIndicator string

Delivery timeframe: 01 Electronic, 02 Same day, 03 Overnight, 04 Two-day or more.

preOrderDate string

Expected availability date for pre-order. YYYYMMDD.

preOrderPurchaseIndicator string

Pre-order status: 01 Merchandise available, 02 Future availability.

shipIndicator string

Shipping method selected (01–07), incl. Digital goods and Travel/Event.

giftCardPurchase bool

true if this purchase is a gift card.

reOrderPurchaseIndicator string

Reorder status: 01 First time ordered, 02 Reordered.

pickUpAddress object

Required when shipIndicator is 04 (store pickup).

name string

Pickup name.

streetAddress string

Pickup street address. Max 50 chars.

coAddress string

Pickup c/o address.

city string

Pickup city.

zipCode string

Pickup ZIP code.

countryCode string

Pickup country code.

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

{
    "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", 
        "status": "Initialized", 
        "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"
        },
        "history": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/history"
        },
        "failed": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failed"
        },
        "aborted": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/aborted"
        },
        "paid": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/paid"
        },
        "cancelled": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/cancelled"
        },
        "financialTransactions": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/financialtransactions"
        },
        "failedAttempts": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failedattempts"
        },
        "metadata": {
        "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
        } 
      },
    "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"
        },
        {
          "href": "https://api.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
          "rel": "abort-paymentattempt",
          "method": "PATCH",
          "contentType": "application/json"
        }
    ]
}

paymentOrder object

The payment order object.

id string

The relative URL and unique identifier of the `paymentorder` resource . Please read about [URL Usage](/checkout-v3/get-started/fundamental-principles#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

status string

Indicates the payment order's current status. Initialized is returned when the payment is created and still ongoing. The request example above has this status. Paid is returned when the payer has completed the payment successfully. See the Paid section for further information. Failed is returned when a payment has failed. You will find an error message in the failed section. Further information here. Cancelled is returned when an authorized amount has been fully cancelled. See the Cancel feature section for further information. It will contain fields from both the cancelled description and paid section. Aborted is returned when the merchant has aborted the payment or if the payer cancelled the payment in the redirect integration (on the redirect page). See the Abort feature section for further information.

currency string

The currency of the payment order.

amount integer

vatAmount integer

description string(40)

A textual [description](/checkout-v3/technical-reference/description) of the purchase. Maximum length is 40 characters.

initiatingSystemUserAgent string

The [user agent](/checkout-v3/technical-reference/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 Order.

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 Online Payments implementation type. Enterprise or PaymentsOnly. Informational only.

integration string

Integration type: HostedView (Seamless View) or Redirect. Populated after UI is opened.

instrumentMode bool

Indicates if only one payment method is available.

guestMode bool

Indicates if the payer chose to pay as a guest. With Enterprise, this is triggered by not including payerReference or nationalIdentifier in the original payment order request.

payer id

The URL to the payer resource.

orderItems id

The URL to the orderItems resource.

history id

URL to the history resource.

failed id

URL to the failed resource.

aborted id

URL to the aborted resource.

paid id

URL to the paid resource.

cancelled id

URL to the cancelled resource.

financialTransactions id

URL to the financialTransactions resource.

failedAttempts id

URL to the failedAttempts resource.

metadata id

URL to the metadata resource.

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.