Digital Payments

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 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. If you cancel before any capture has been done, no captures can be performed later.

Cancel Request (All Versions)

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;version=3.1/3.0/2.0      // Version optional for 3.0 and 2.0

{
    "transaction": {
        "description": "Test Cancellation",
        "payeeReference": "ABC123"
    }
}

Field	Type	Description
`transaction`	`object`	The transaction object.
`description`	`string`	A textual description of why the transaction is cancelled.
`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.

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
22

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

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

Show fields

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 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`	`Initialized`, `Completed` or `Failed`. Indicates the state of the transaction.
`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 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`	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.

Cancel Response v3.1

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

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

{
  "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": "Cancelled",
    "currency": "SEK",
    "amount": 1500,
    "vatAmount": 375,
    "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 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.
`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 instruments 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 instrument 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. See Operations for details.

Cancel Sequence Diagram

Cancel can only be done on an authorized transaction. As a cancellation does not have an amount associated with it, it will release the entire reserved amount. If your intention is to make detailed handling, such as only capturing a partial amount of the transaction, you must start with the capture on the desired amount before performing a cancel for the remaining reserved funds.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

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