Payment Menu

After Payment

schedule 11 min read

When the payer is done interacting with the 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.”

Edit "After Payment" on GitHub

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.

GET Request

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

Request

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

GET Response

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

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
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"
        }
    ]
}
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.
operations array The array of possible operations to perform, given the state of the payment order.

Cancel

Cancel

The cancellations resource lists the cancellation transactions on a specific payment.

Create Cancel Transaction

To cancel a previously created payment, you must perform the create-paymentorder-cancel operation against the accompanying href returned in the operations list. You can only cancel a payment - or part of a payment - which has not been captured yet.

Cancel Request

Request

1
2
3
4
5
6
7
8
9
10
11
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": {
        "description": "Test Cancellation",
        "payeeReference": "ABC123"
    }
}
Required Field Type Description
check transaction object The transaction object.
check └➔ description string A textual description of why the transaction is cancelled.
check └➔ 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 (including -) 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.

Cancel Response

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellation": {
        "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/paymentorders/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2022-01-31T09:49:13.7567756Z",
            "updated": "2022-01-31T09:49:14.7374165Z",
            "type": "Cancellation",
            "state": "Completed",
            "number": 71100732065,
            "amount": 1500,
            "vatAmount": 375,
            "description": "Test Cancellation",
            "payeeReference": "AB123"
        }
    }
}
Property Type Description
payment string The relative URL of the payment this cancellation transaction belongs to.
cancellation object The cancellation object, containing information about the cancellation transaction.
└➔ id string The relative URL of the cancellation transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URL 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 updated.
└─➔ 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 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 A human readable description of maximum 40 characters of the transaction.
└─➔ 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 (including -) 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.

Cancel Sequence Diagram

Cancel can only be done on a authorized transaction. If you perform a cancel after doing a partial capture, you will cancel the remaining authorized amount.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

    Merchant->>SwedbankPay: POST <  cancellation>
    activate Merchant
    activate SwedbankPay
    SwedbankPay-->>Merchant: transaction resource
    deactivate SwedbankPay
    deactivate Merchant

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.

Reversal 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
44
45
46
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",
        "receiptReference": "ABC122",
        "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 Field Type Description
check transaction object The transaction object.
check └➔ 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.
check └➔ 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.
check └➔ 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 (including -) 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.
  └➔ receiptReference string(30) A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number.
check └➔ description string Textual description of why the transaction is reversed.
check └➔ 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 Admin system 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.
check └─➔ reference string A reference that identifies the order item.
check └─➔ name string The name of the order item.
check └─➔ type enum PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE, DISCOUNT, VALUE_CODE or OTHER. The type of the order item.
check └─➔ 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.
check └─➔ quantity integer The 4 decimal precision quantity of order items being purchased.
check └─➔ quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check └─➔ 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.
check └─➔ vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
check └─➔ 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.
check └─➔ 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.

Reversal Response

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

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
HTTP/1.1 200 OK
Content-Type: application/json

{
    "payment": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce",
    "reversal": {
        "id": "/psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/pcreditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "created": "2022-01-26T14:00:03.4725904Z",
            "updated": "2022-01-26T14:00:04.3851302Z",
            "type": "Reversal",
            "state": "Completed",
            "number": 71100730898,
            "amount": 1500,
            "vatAmount": 375,
            "description": "Reversing the capture amount",
            "payeeReference": "ABC123",
            "receiptReference": "ABC122"
            "isOperational": false,
            "reconciliationNumber": 738180,
            "operations": []
        }
    }
}
Property Type Description
payment string The relative URL of the payment this reversal transaction belongs to.
reversals object The reversal object, containing information about the reversal transaction.
└➔ id string The relative URL of the reversal transaction.
└➔ transaction object The transaction object, containing information about the current transaction.
└─➔ id string The relative URL 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 updated.
└─➔ type string Indicates the transaction type.
└─➔ state string Indicates the state of the transaction, usually initialized, completed orfailed. If a partial has been done and further transactionsare possible, the state will be awaitingActivity.
└─➔ 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, where id should be used instead.
└─➔ 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 A human readable description of maximum 40 characters of the transaction.
└─➔ 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 (including -) 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.
└➔ receiptReference string(30) A unique reference from the merchant system. It is used to supplement payeeReference as an additional receipt number.
└─➔ isOperational boolean true if the transaction is operational; otherwise false .
└─➔ reconciliationNumber string The number of the reconciliation batch file where the transaction can be found.
└─➔ operations array The array of operations that are possible to perform on the transaction in its current state.
info

Note that all of the operations Cancel, Capture and Reversal must be implemented.