Swedbank Pay Checkout – After Payment

When the consumer has completed the entire Checkin and Payment Menu, you need to implement the relevant after-payment operations in your order system. Which these operations are and how they are executed is described below.

Introduction

Below is the final part of the sequence diagram illustrating how a capture operation is performed.

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:create-paymentorder-capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>PaymentInstruments that support <br>Authorizations.
        end

Operations

Most payment instruments are two-phase payments – in which a successful payment order will result in an authorized transaction – that must be followed up by a capture or cancellation transaction in a later stage. One-phase payments like Swish are settled directly without the option to capture or cancel. For a full list of the available operations, see the techincal reference.

Operation Description
create-paymentorder-capture The second part of a two-phase transaction where the authorized amount is sent from the payer to the payee. It is possible to do a part-capture on a subset of the authorized amount. Several captures on the same payment are possible, up to the total authorization amount.
create-paymentorder-cancel Used to cancel authorized and not yet captured transactions. If a cancellation is performed after doing a part-capture, it will only affect the not yet captured authorization amount.
create-paymentorder-reversal Used to reverse a payment. It is only possible to reverse a payment that has been captured and not yet reversed.

To identify the operations that are available we need to do a GET request against the URI of paymentorder.id:

Request

GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce HTTP/1.1
Authorization: Bearer <AccessToken>

The (abbreviated) response containing an updateorder, capture, cancellation, and reversal operation should look similar to the response below:

Response

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

{
    "paymentOrder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce"
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-updateorder",
            "contentType": "application/json"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures",
            "rel": "create-paymentorder-capture",
            "contentType": "application/json"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations",
            "rel": "create-paymentorder-cancel",
            "contentType": "application/json"
        },
        {
            "method": "POST",
            "href": "https://api.externalintegration.payex.com/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals",
            "rel": "create-paymentorder-reversal",
            "contentType": "application/json"
        }
    ]
}
Property Type Description
paymentorder object The payment order object.
└➔ id string The relative URI to the payment order.
operations array The array of possible operations to perform, given the state of the payment order.

Capture

Capture can only be done on a payment with a successful authorized transaction, and if the authorization was not done on a one-phase payment instrument. Examples of one-phase payment instruments are Swish and Vipps, while payment instruments such as Credit Card are two-phase payments, requiring a Capture to be performed.

It is possible to do a part-capture where you only capture a smaller amount than the authorized amount. You can later do more captures on the same payment up to the total authorization amount.

This is done by requesting the order information from the server, to get the request link to perform the capture. With this, you can request the capture with the sum to capture, and get back the status.

sequenceDiagram
    participant Merchant
    participant SwedbankPay as Swedbank Pay

    rect rgba(81,43,43,0.1)
        activate Merchant
        note left of Payer: Capture
        Merchant ->>+ SwedbankPay: rel:create-paymentorder-capture
        deactivate Merchant
        SwedbankPay -->>- Merchant: Capture status
        note right of Merchant: Capture here only if the purchased<br/>goods don't require shipping.<br/>If shipping is required, perform capture<br/>after the goods have shipped.<br>Should only be used for <br>PaymentInstruments that support <br>Authorizations.
        end
info

Note that the orderItems property object is optional. If the POST request has orderItems in the paymentorder, remember to include orderItems in the capture operation. If the paymentorder is without orderItems, remember to leave this out in the capture operation.

To capture the authorized payment, we need to perform create-paymentorder-capture against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request

POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/captures HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "description": "Capturing the authorized payment",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "AB832",
        "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": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}
Required Property Type Description
✔︎︎︎︎︎ transaction object The transaction object.
✔︎︎︎︎︎ └➔ description string The description of the capture transaction.
✔︎︎︎︎︎ └➔ amount integer The amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
✔︎︎︎︎︎ └➔ vatAmount integer The amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
✔︎︎︎︎︎ └➔ 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.
✔︎︎︎︎︎ └➔ orderItems array The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. Required in capture requests if already sent with the initial creation of the Payment Order. Note that this should only contain the items 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.
✔︎︎︎︎︎ └─➔ 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. 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 integer 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 a free-text field and 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 property 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 SEK and 5000 equals 50.00 SEK.
✔︎︎︎︎︎ └─➔ 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 SEK and 5000 equals 50.00 SEK.
✔︎︎︎︎︎ └─➔ 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.
✔︎︎︎︎︎ └─➔ 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. Swedbank Pay may use this field for statistics.
︎︎︎ └─➔ itemUrl string The URL to a page that can display the purchased item, such as a product page
︎︎︎ └─➔ 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 decimal 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 property 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 5000 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 5000 equals 50.00 NOK.

If the capture succeeds, it should respond with something like the following:

Response

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

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "type": "Capture",
            "state": "Completed",
            "amount": 15610,
            "vatAmount": 3122,
            "description": "Capturing the authorized payment",
            "payeeReference": "AB832"
        }
    }
}
Property Type Description
payment string The relative URI of the payment this capture transaction belongs to.
capture object The capture object, containing the information about the capture transaction.
└➔ id string The relative URI of the created capture transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URI of the current transaction resource.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was created.
└─➔ type string Indicates the transaction type.
└─➔ state string Initialized, Completed or Failed. Indicates the state of the transaction.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
└─➔ amount integer Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
└─➔ vatAmount integer If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
└─➔ description string A human readable description of maximum 40 characters of the transaction.
└─➔ payeeReference string A unique reference for the transaction. See payeeReference for details.

Et voilà! Checkout should now be complete, the payment should be secure and everyone should be happy. But, sometimes you also need to implement the cancellation and reversal operations described below.

Cancel

If we want to cancel up to the total authorized (not captured) amount, we need to perform create-paymentorder-cancel against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request

POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "payeeReference": "ABC123",
        "description": "Cancelling parts of the total amount"
    }
}
Required Property Type Description
✔︎︎︎︎︎ transaction object The transaction object.
✔︎︎︎︎︎ └➔ 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.
✔︎︎︎︎︎ └➔ description string A textual description of why the transaction is cancelled.

If the cancellation request succeeds, the response should be similar to the example below:

Response

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

{
    "payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellation": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "type": "Cancel",
            "state": "Completed",
            "amount": 5610,
            "vatAmount": 1122,
            "description": "Cancelling parts of the authorized payment",
            "payeeReference": "AB832"
        }
    }
}
Property Type Description
payment string The relative URI of the payment this cancellation transaction belongs to.
cancellation object The cancellation object, containing information about the cancellation transaction.
└➔ id string The relative URI of the cancellation transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URI of the current transaction resource.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was created.
└─➔ type string Indicates the transaction type.
└─➔ state string Initialized, Completed or Failed. Indicates the state of the transaction.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
└─➔ amount integer Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
└─➔ vatAmount integer If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
└─➔ description string A human readable description of maximum 40 characters of the transaction.
└─➔ payeeReference string A unique reference for the transaction. See payeeReference for details.

Reversal

If we want to reverse a previously captured amount, we need to perform create-paymentorder-reversal against the accompanying href returned in the operations list. See the abbreviated request and response below:

Request

POST /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "transaction": {
        "description": "Reversal of captured transaction",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "ABC123",
        "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": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "P2",
                "name": "Product2",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "description": "Product 2 description",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 500,
                "vatPercent": 2500,
                "amount": 500,
                "vatAmount": 125
            }
        ]
    }
}
Required Property Type Description
✔︎︎︎︎︎ transaction object The transaction object.
✔︎︎︎︎︎ └➔ amount integer The amount including VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
✔︎︎︎︎︎ └➔ vatAmount integer The amount of VAT in the lowest monetary unit of the currency. E.g. 10000 equals 100.00 NOK and 5000 equals 50.00 NOK.
✔︎︎︎︎︎ └➔ 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.
✔︎︎︎︎︎ └➔ description string Textual description of why the transaction is reversed.
✔︎︎︎︎︎ └➔ orderItems array The array of items being purchased with the order. Used to print on invoices if the payer chooses to pay with invoice, among other things. Required in capture requests if already sent with the initial creation of the Payment Order. Note that this should only contain the items 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.
✔︎︎︎︎︎ └─➔ 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. 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 integer 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 a free-text field and 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 property 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 SEK and 5000 equals 50.00 SEK.
✔︎︎︎︎︎ └─➔ 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 SEK and 5000 equals 50.00 SEK.

If the reversal request succeeds, the response should be similar to the example below:

Response

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

{
    "payment": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce",
    "reversals": {
        "id": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "type": "Reversal",
            "state": "Completed",
            "amount": 15610,
            "vatAmount": 3122,
            "description": "Reversing the capture amount",
            "payeeReference": "ABC987"
        }
    }
}
Property Type Description
payment string The relative URI of the payment this reversal transaction belongs to.
reversals object The reversal object, containing information about the reversal transaction.
└➔ id string The relative URI of the reversal transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URI of the current transaction resource.
└─➔ created string The ISO-8601 date and time of when the transaction was created.
└─➔ updated string The ISO-8601 date and time of when the transaction was created.
└─➔ type string Indicates the transaction type.
└─➔ state string Initialized, Completed or Failed. Indicates the state of the transaction.
└─➔ number string The transaction number, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, for that id should be used instead.
└─➔ amount integer Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
└─➔ vatAmount integer If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
└─➔ description string A human readable description of maximum 40 characters of the transaction.
└─➔ payeeReference string A unique reference for the transaction. See payeeReference for details.