Digital Payments – Reversal

Reversal

This transaction is used when a Capture or Sale payment needs to be reversed.

Please note that you have a maximum of 5 consecutive failed attempts at a reversal. The payment will be locked after this, and you need to contact us for another attempt.

If the full amount of a v3.1 sale transaction or a captured transaction is reversed, The transaction will now have status Reversed instead of Paid (which is used in earlier versions).

Create Reversal Transaction

If we want to reverse a previously captured amount, we need to perform reversal against the accompanying href returned in the operations list.

Reversal Request

Request

1
2
3
4

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

{
    "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
            }
        ]
    }
}

Show fields

Field	Type	Description
`transaction`	`object`	The transaction object.
`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.
`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.
`receiptReference`	`string(30)`	A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to `payeeReference`.
`description`	`string`	Textual description of why the transaction is reversed.
`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 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`.

Reversal Response

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

Response

1
2
3

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

{
    "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": []
        }
    }
}

Show fields

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 object representation of the generic `transaction` resource, 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` or `failed`. If a partial has been done and further transactions are possible, the state will be `awaitingActivity`.
`number`	`integer`	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. 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`	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` 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 to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to `payeeReference`.
`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 payment order in its current state.

Reversal Request v3.1

Request

1
2
3
4

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

1
2
3
4
5
6
7
8

{
    "transaction": {
        "description": "Reversal of captured transaction",
        "amount": 1500,
        "vatAmount": 375,
        "payeeReference": "ABC123"
    }
}

Show fields

Field	Type	Description
`transaction`	`object`	The transaction object.
`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.
`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.
`receiptReference`	`string(30)`	A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to `payeeReference`.
`description`	`string`	Textual description of why the transaction is reversed.
`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 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`.

Reversal Response v3.1

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

Response

1
2
3

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

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

{
  "paymentOrder": {
    "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d",
    "created": "2020-03-03T07:19:27.5636519Z",
    "updated": "2020-03-03T07:21:00.5605905Z",
    "operation": "Purchase",
    "status": "Reversed",
    "currency": "SEK",
    "amount": 1500,
    "vatAmount": 375,
    "remainingCaptureAmount": 0, // Only present after a partial reversal
    "remainingReversalAmount": 0, // Only present after a partial reversal
    "description": "Test Purchase",
    "initiatingSystemUserAgent": "<should be set by the system calling POST:/psp/paymentorders>",
    "language": "sv-SE",
    "availableInstruments": [ "CreditCard", "Invoice-PayExFinancingSe", "Invoice-PayMonthlyInvoiceSe", "Swish", "CreditAccount", "Trustly" ],
    "implementation": "PaymentsOnly",
    "integration": "HostedView|Redirect",
    "instrumentMode": true,
    "guestMode": true,
    "orderItems": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/orderitems"
    },
    "urls": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/urls"
    },
    "payeeInfo": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payeeInfo"
    },
    "payer": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
    },
    "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"
    },
    "postPurchaseFailedAttempts": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/postpurchasefailedattempts"
    },
    "metadata": {
      "id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
    }
  },
  "operations": [
  ]
}

Show fields

Property	Type	Description
`paymentOrder`	`string`	The relative URL of the payment order this capture transaction belongs to.
`id`	`string`	The relative URL of the created capture transaction.
`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.
`operation`	`string`	Determines the initial operation, defining the type of payment order created.
`status`	`string`	`Initialized`, `Paid`, `Failed`, `Reversed` `Cancelled`, or `Aborted`. Indicates the payment order’s current status.
`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. 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.
`remainingCaptureAmount`	`integer`	The remaining authorized amount that is still possible to capture.
`remainingCancellationAmount`	`integer`	The remaining authorized amount that is still possible to cancel.
`remainingReversalAmount`	`integer`	The remaining captured amount that is still available for reversal.
`description`	`string`	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 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 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 methods available.
`guestMode`	`bool`	Set to `true` or `false`. Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a `payerReference` in the original `paymentOrder` request.
`orderItems`	`id`	The URL to the `orderItems` resource where information about the order items can be retrieved.
`urls`	`id`	The URL to the `urls` resource where all URLs related to the payment order can be retrieved.
`payeeInfo`	`id`	The URL to the `payeeInfo` resource where information related to the payee can be retrieved.
`payer`	`id`	The URL to the `payer` resource where information about the payer can be retrieved.
`history`	`id`	The URL to the `history` resource where information about the payment’s history can be retrieved.
`failed`	`id`	The URL to the `failed` resource where information about the failed transactions can be retrieved.
`aborted`	`id`	The URL to the `aborted` resource where information about the aborted transactions can be retrieved.
`paid`	`id`	The URL to the `paid` resource where information about the paid transactions can be retrieved.
`cancelled`	`id`	The URL to the `cancelled` resource where information about the cancelled transactions can be retrieved.
`financialTransactions`	`id`	The URL to the `financialTransactions` resource where information about the financial transactions can be retrieved.
`failedAttempts`	`id`	The URL to the `failedAttempts` resource where information about the failed attempts can be retrieved.
`postPurchaseFailedAttempts`	`id`	The URL to the `postPurchaseFailedAttempts` resource where information about the failed capture, cancel or reversal attempts can be retrieved.
`metadata`	`id`	The URL to the `metadata` resource where information about the metadata can be retrieved.
`operations`	`array`	The array of operations that are possible to perform on the payment order in its current state.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

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