Digital Payments – Update Payment Order

Update Payment Order

If a payment is attempted, failed or currently being processed, you will not be able to update the orderItems for the payment order. Should you need to update the orderItems, you will have to abort the payment order and create a new order with the updated orderItems.

The UpdateOrder operation is used when there is a change in the amount, vat amount or there are added or removed order items in the payment order.

If you implement UpdateOrder you need to refresh() the Payment Menu frontend after you have called the UpdateOrder API from the backend.

In case the shopping cart is changed in another browser tab, that should also lead to an UpdateOrder. On window.onfocus in the tab that had Payment Menu initialized, refresh() should be invoked so the correct amount is authorized.

If the page is refreshed by a full page reload, refresh() is not necessary.

The response given when changing a payment order is equivalent to a GET request towards the paymentorders resource. Even though the fields are the same, the UpdateOrder request will overwrite the fields that were sent in the initial Purchase 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
39
40
41
42
43

PATCH /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

{
    "paymentorder": {
        "operation": "UpdateOrder",
        "amount": 1500,
        "vatAmount": 375,
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/shop/products/1234",
                "imageUrl": "https://example.com/products/product1.jpg",
                "description": "Product description",
                "discountDescription": "Volume discount",
                "quantity": 351.3514,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product description",
                "quantity": 9876.1531,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}

Show fields

Field	Type	Description
`paymentOrder`	`object`	The payment order object.
`operation`	`string`	Determines the initial operation, defining the type of payment order created.
`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 instrument 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.
`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`	`enum`	`PRODUCT`, `SERVICE`, `SHIPPING_FEE`, `PAYMENT_FEE`, `DISCOUNT`, `VALUE_CODE` or `OTHER`. The type of the order item.
`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`	The human readable description of the order item.
`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 total amount including VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 NOK` and `500`0 equals `50.00 NOK`.
`vatAmount`	`integer`	The total amount of VAT to be paid for the specified quantity of this order item, in the lowest monetary unit of the currency. E.g. `10000` equals `100.00 NOK` and `500`0 equals `50.00 NOK`.

Response

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

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
        "created": "2018-09-14T13:21:29.3182115Z",
        "updated": "2018-09-14T13:21:57.6627579Z",
        "operation": "Purchase",
        "state": "Ready",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 0,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls" },
        "payeeInfo" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeinfo" },
        "payers": { "id": "/psp//payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        "orderItems" : { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderItems" },
        "metadata": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/metadata" },
        "payments": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments" },
        "currentPayment": { "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment" }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.stage.payex.com/psp/paymentorders/7f27f445-cefe-4a48-d405-08d8143ed22b",
            "rel": "update-paymentorder-updateorder",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-abort",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-expandinstrument",
            "contentType": "application/json"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/paymentmenu/5a17c24e-d459-4567-bbad-aa0f17a76119?_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "redirect-paymentorder",
            "contentType": "text/html"
        },
        {
            "method": "GET",
            "href": "https://ecom.externalintegration.payex.com/paymentmenu/core/scripts/client/px.paymentmenu.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119&culture=nb-NO&_tc_tid=30f2168171e142d38bcd4af2c3721959",
            "rel": "view-paymentorder",
            "contentType": "application/javascript"
        }
    ]
}

Show fields

Field	Type	Description
`payment`	`object`	The `payment` object contains information about the specific payment.
`id`	`string`	The relative URL and unique identifier of the `payment` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`number`	`integer`	The payment `number`, useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, where `id` should be used instead.
`created`	`string`	The ISO-8601 date of when the payment was created.
`updated`	`string`	The ISO-8601 date of when the payment was updated.
`state`	`string`	`Ready`, `Pending`, `Failed` or `Aborted`. Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the `transactions` resource or the different specialized type-specific resources such as `authorizations` or `sales`.
`prices`	`object`	The `prices` resource lists the prices related to a specific payment.
`id`	`string`	The relative URL and unique identifier of the `prices` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`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 instrument specific discounts or fees.
`remainingCaptureAmount`	`integer`	The available amount to capture.
`remainingCancelAmount`	`integer`	The available amount to cancel.
`remainingReversalAmount`	`integer`	The available amount to reverse.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`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`, `da-DK`, `en-US` or `fi-FI`.
`urls`	`string`	The URL to the urls resource where all URLs related to the payment can be retrieved.
`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
`payers`	`string`	The URL to the `payer` resource where the information about the payer can be retrieved.
`operations`	`array`	The array of operations that are possible to perform on the payment in its current state.
`method`	`string`	The HTTP method to use when performing the operation.
`href`	`string`	The target URL to perform the operation against.
`rel`	`string`	The name of the relation the operation has to the current resource.