Options After Posting A Payment
When you detect that the payer reach your completeUrl
, you need to do a GET
request on the payment resource, containing the paymentID
generated in the
first step, to receive the state of the transaction. You will also be able to
see the available operations after posting a payment.
- Abort: It is possible to abort the process if the payment has no successful transactions. See the Abort description here.
- If the payment shown above is done as a two phase (
Authorization
), you will need to implement theCapture
andCancel
requests. - For
reversals
, you will need to implement the Reversal request. - If
CallbackURL
is set: Whenever changes to the payment occur a Callback request will be posted to thecallbackUrl
, which was generated when the payment was created.
Cancellations
Cancel
can only be done on a authorized transaction. If you do cancel after
doing a part-capture you will cancel the difference between the capture amount
and the authorization amount.
Cancel Request
Request
1
2
3
4
5
6
7
8
9
10
11
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/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 object representation of the generic transaction resource. |
check | description |
string |
A textual description of the reason for the cancellation . |
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 and string(50) . 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
The cancel
resource contains information about a cancellation transaction
made against a payment.
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
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",
"created": "2016-09-14T01:01:01.01Z",
"updated": "2016-09-14T01:01:01.03Z",
"type": "Cancellation",
"state": "Initialized",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test Cancellation",
"payeeReference": "ABC123",
"failedReason": "",
"isOperational": false,
"operations": []
}
}
}
Property | Type | Description |
---|---|---|
payment |
string |
The relative URL of the payment this cancellation transaction belongs to. |
cancellation |
object |
The cancellation resource contains information about the cancellation transaction made against a card payment. |
id |
string |
The relative URL of the created 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. |
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 40 character length textual description of the purchase. |
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(50) . 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. |
isOperational |
boolean |
true if the transaction is operational; otherwise false . |
operations |
array |
The array of operations that are possible to perform on the payment order in its current state. |
List Cancel Transactions
The cancellations
resource lists the cancellation transactions on a specific
payment.
Request
1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
The cancellation
resource contains information about the
cancellation
transaction made against a creditcard payment. You can
return a specific cancellation
transaction by performing a GET
request
towards the specific transaction’s id
.
Transaction List Response
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"cancellations": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
"cancellationList": [{
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"created": "2016-09-14T01:01:01.01Z",
"updated": "2016-09-14T01:01:01.03Z",
"type": "Cancellation",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"operations": []
}
}]
}
}
Field | Type | Required |
---|---|---|
paymentOrder |
string |
The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
id |
string |
The relative URL and unique identifier of the cancellations resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
{{ transaction }}List |
array |
The array of cancellation transaction objects. |
{{ transaction }}List[] |
object |
The cancellation transaction object described in the cancellation resource below. |
id |
string |
The relative URL and unique identifier of the transaction resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
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 cancellation 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 |
A 40 character length textual description of the purchase. |
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(50) . 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. |
isOperational |
bool |
true if the transaction is operational; otherwise false . |
operations |
array |
The array of operations that are possible to perform on the transaction in its current state. |
Cancel Sequence Diagram
sequenceDiagram
activate Merchant
Merchant->>-SwedbankPay: POST [creditcard cancellactions]
activate SwedbankPay
SwedbankPay-->>-Merchant: transaction resource
Reversals
This transaction is used when a captured payment needs to be reversed.
Reversal Request
Request
1
2
3
4
5
6
7
8
9
10
11
12
13
POST /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"transaction": {
"amount": 1500,
"vatAmount": 0,
"description": "Test Reversal",
"payeeReference": "ABC123"
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The object representation of the generic transaction resource. |
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 | description |
string |
A textual description of the reversal . |
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 and string(50) . 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. |
Reversal Response
The reversal
resource contains information about the newly created reversal
transaction.
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"reversal": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversal/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"created": "2016-09-14T01:01:01.01Z",
"updated": "2016-09-14T01:01:01.03Z",
"type": "Reversal",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"failedReason": "",
"isOperational": false,
"operations": []
}
}
}
Property | Type | Description |
---|---|---|
payment |
string |
The relative URL of the payment this reversal transaction belongs to. |
reversal |
object |
The reversal resource contains information about the reversal transaction made against a card payment. |
id |
string |
The relative URL of the created 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 cancellation has been done and further transactions are 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 40 character length textual description of the purchase. |
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(50) . 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. |
failedReason |
string |
The human readable explanation of why the payment failed. |
isOperational |
boolean |
true if the transaction is operational; otherwise false . |
operations |
array |
The array of operations that are possible to perform on the payment order in its current state. |
List Reversal Transactions
The reversals
resource lists the reversal transactions (one or more) on a
specific payment.
Request
1
2
3
4
GET /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
The reversal
resource contains information about the
reversal
transaction made against a creditcard payment. You can
return a specific reversal
transaction by performing a GET
request
towards the specific transaction’s id
.
Transaction List Response
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"reversals": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
"reversalList": [{
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"transaction": {
"id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"created": "2016-09-14T01:01:01.01Z",
"updated": "2016-09-14T01:01:01.03Z",
"type": "Reversal",
"state": "Completed",
"number": 1234567890,
"amount": 1000,
"vatAmount": 250,
"description": "Test transaction",
"payeeReference": "AH123456",
"isOperational": false,
"operations": []
}
}]
}
}
Field | Type | Required |
---|---|---|
paymentOrder |
string |
The relative URL and unique identifier of the payment resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
id |
string |
The relative URL and unique identifier of the reversals resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
{{ transaction }}List |
array |
The array of reversal transaction objects. |
{{ transaction }}List[] |
object |
The reversal transaction object described in the reversal resource below. |
id |
string |
The relative URL and unique identifier of the transaction resource . Please read about URL Usage to understand how this and other URLs should be used in your solution. |
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 reversal 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 |
A 40 character length textual description of the purchase. |
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(50) . 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. |
isOperational |
bool |
true if the transaction is operational; otherwise false . |
operations |
array |
The array of operations that are possible to perform on the transaction in its current state. |
Reversal Sequence Diagram
sequenceDiagram
activate Merchant
Merchant->>-SwedbankPay: POST [creditcard reversals]
activate SwedbankPay
SwedbankPay-->>-Merchant: transaction resource
Abort
To abort a payment, perform the update-payment-abort
operation that is
returned in the payment request.
Abort Request
Request
1
2
3
4
5
6
7
8
9
10
11
PATCH /psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"payment": {
"operation": "Abort",
"abortReason": "CancelledByConsumer"
}
}
Abort Response
The response will be the payment
resource with its state
set to Aborted
.
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"number": 70100130293,
"created": "2019-01-09T13:11:28.371179Z",
"updated": "2019-01-09T13:11:46.5949967Z",
"instrument": "Creditcard",
"operation": "Purchase",
"intent": "Authorization",
"state": "Aborted",
"currency": "SEK",
"prices": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
},
"amount": 0,
"description": "creditcard Test",
"initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
"userAgent": "Mozilla/5.0",
"language": "sv-SE",
"urls": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
},
"payeeInfo": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
},
"payers": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
},
"metadata": {
"id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
}
},
"operations": []
}
Remove Payment Token
If you, for any reason, need to delete a paymentToken you use the
Delete payment token
request.
Please note that this call does not erase the card number stored at Swedbank
Pay. A card number is automatically deleted six months after a successful
Delete payment token
request. If you want to remove card information
beforehand, you need to contact
ehandelsetup@swedbankpay.dk,
verkkokauppa.setup@swedbankpay.fi,
ehandelsetup@swedbankpay.no or
ehandelsetup@swedbankpay.se; and supply
them with the relevant transaction reference or payment token.
Delete Token Request
Request
1
2
3
4
5
6
7
8
9
10
PATCH /psp/creditcard/payments/instrumentData/5a17c24e-d459-4567-bbad-aa0f17a76119 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json
{
"state": "Deleted",
"tokenType" : "PaymentToken",
"comment": "Comment on why the deletion is happening"
}
Delete Token Response
Response
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
HTTP/1.1 200 OK
Content-Type: application/json
{
"instrumentData": {
"id": "/psp/creditcard/payments/instrumentdata/5a17c24e-d459-4567-bbad-aa0f17a76119",
"paymentToken": "5a17c24e-d459-4567-bbad-aa0f17a76119",
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"isDeleted": true,
"isPayeeToken": false,
"cardBrand": "MasterCard",
"maskedPan": "123456xxxxxx1111",
"expiryDate": "MM/YYYY"
}
}