Operations
Most payment methods are two-phase payments – in which a successful payment order will result in an authorized transaction – that must be followed by a capture or cancellation transaction later on. 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 technical 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
3
4
GET /psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.x/2.0 // Version optional for 3.0 and 2.0
GET Response
The (abbreviated) response containing an updateorder
, capture
,
cancellation
, and reversal
operation should look similar to the response
below:
Response
1
2
3
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.x/2.0
api-supported-versions: 3.x/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
{
"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 operations that are possible to perform on the payment order in its current state. |
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. If you cancel before any capture has been done,
no captures can be performed later.
Cancel Request
Request
1
2
3
4
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.0/2.0 // Version optional
1
2
3
4
5
6
{
"transaction": {
"description": "Test Cancellation",
"payeeReference": "ABC123"
}
}
transaction
object
check
description
string
check
payeeReference
string(30)
check
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 to the acquirer 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
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
{
"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"
}
}
}
payment
string
cancellation
object
id
string
transaction
object
The object representation of the generic transaction
resource, containing information about the current transaction.
id
string
transaction
resource.
created
string
updated
string
type
string
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.
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
payeeReference
string(30)
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 to the acquirer 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 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 of 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
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
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
}
]
}
}
transaction
object
check
amount
integer
check
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
check
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(30)
check
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 to the acquirer 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
check
orderItems
array
check
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
check
name
string
check
type
enum
check
PRODUCT
, SERVICE
, SHIPPING_FEE
, PAYMENT_FEE
, DISCOUNT
, VALUE_CODE
or OTHER
. The type of the order item.
class
string
check
MobilePhone
. Note that class
cannot contain spaces and must follow the regex pattern [\w-]*
. Swedbank Pay may use this field for statistics.
itemUrl
string
imageUrl
string
description
string
discountDescription
string
quantity
number
check
quantityUnit
string
check
pcs
, grams
, or similar. This is used for your own book keeping.
unitPrice
integer
check
discountPrice
integer
vatPercent
integer
check
25%
becomes 2500
.
amount
integer
check
10000
equals 100.00 SEK
and 5000
equals 50.00 SEK
.
vatAmount
integer
check
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": []
}
}
}
payment
string
reversals
object
id
string
transaction
object
The object representation of the generic transaction
resource, containing information about the current transaction.
id
string
transaction
resource.
created
string
updated
string
type
string
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.
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
payeeReference
string(30)
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 to the acquirer 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
operations
array
The array of operations that are possible to perform on the payment order in its current state.
Note that all of the
operations Cancel
, Capture
and Reversal
must be implemented.