Invoice

After Payment

Options After Posting A Payment

When you detect that the payer has reached your completeUrl, you need to do a GET request on the payment resource, which contains 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.
  • An invoice authorization must be followed by a capture or cancel request.
  • 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 the callbackUrl, which was generated when the payment was created.

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



PATCH /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1 HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json





1
2
3
4
5
6



{
  "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/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 70100130293,
        "created": "2019-01-09T13:11:28.371179Z",
        "updated": "2019-01-09T13:11:46.5949967Z",
        "instrument": "Invoice",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Aborted",
        "currency": "SEK",
        "prices": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "amount": 0,
        "description": "invoice Test",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "urls": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "metadata": {
            "id": "/psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata"
        }
    },
    "operations": []
}

Cancellations

Perform the create-cancellation operation to cancel a previously authorized or partially captured invoice payment.

Cancel Request

Request 



1
2
3
4



POST /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json





1
2
3
4
5
6
7



{
    "transaction": {
        "activity": "FinancingConsumer",
        "payeeReference": "customer order reference-unique",
        "description": "description for transaction"
    }
}
Required Parameter name Datatype Value (with description)
check︎ transaction.activity string FinancingConsumer.
check︎ transaction.payeeReference string The payeeReference is the receipt/invoice number, which is a unique reference with max 50 characters set by the merchant system. This must be unique for each operation and must follow the regex pattern [\w-]*.
check︎ transaction.description string(50) A textual description for the cancellation.

Cancel Response

The cancel resource will be returned, containing information about the newly created cancel transaction.

The created cancel resource contains information about the cancel transaction made against a invoice payment.

Capture Response

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
32
33
34
35
36
37



{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancel": {
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "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": "Cancel",
            "state": "Completed",
            "number": 1234567890,
            "amount": 1000,
            "vatAmount": 250,
            "description": "Test transaction",
            "payeeReference": "ABC123", 
            "receiptReference": "ABC123", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/invoice/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-cancel",
                    "method": "PATCH"
                }
            ]
        }
    }
}
Field
Type
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.

authorization object
The authorization object.
id string

The relative URL and unique identifier of the authorization resource this cancellations belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

itemDescriptions object
The object representation of the itemDescriptions resource.
id string

The relative URL and unique identifier of the itemDescriptions resource this cancellations belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

transaction object

The object representation of the generic transaction resource, containing information about the current transaction.

id string

The relative URL and unique identifier of the transaction resource this cancellations belongs to. 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 cancel 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 textual description of the purchase. Maximum length is 40 characters.

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

A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.

failedReason string
The human readable explanation of why the payment failed.
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.

List Cancel Transactions

The cancellations resource lists the cancellation transaction made on a specific payment.

Request 



1
2
3
4



GET /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

The cancel resource contains information about the cancel transaction made against a invoice payment. You can return a specific cancel transaction by performing a GET request towards the specific transaction’s id.

Transaction List Response

Response 



1
2



HTTP/1.1 200 OK
Content-Type: application/json





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



{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellations": { 
        "receiptReference": "AH12355", 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "cancelList": [{
            "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": "Cancel",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}
Field
Type
paymentOrder string

The relative URL and unique identifier of the payment resource this cancellations belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

cancellations object
The current cancellations resource.
id string

The relative URL and unique identifier of the cancellations resource this cancellations belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

cancellationList array
The cancel transaction object described in the cancel resource below.
id string

The relative URL and unique identifier of the transaction resource this cancellations belongs to. 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 cancel 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 textual description of the purchase. Maximum length is 40 characters.

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

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

A cancel can only be performed on a successfully authorized transaction which has not been captured yet. If you perform a cancellation after doing a partial capture, you will only cancel the remaining authorized amount.

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

  Merchant->>SwedbankPay: Post <Invoice cancellations>
  activate Merchant
  activate SwedbankPay
  SwedbankPay-->>Merchant: transaction resource
  deactivate Merchant
  deactivate SwedbankPay

Reversals

The create-reversal operation will reverse a previously captured payment and refund the amount to the payer. To reverse a payment, perform the create-reversal operation.

Reversal Request

Request 



1
2
3
4



POST /psp/invoice/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json





1
2
3
4
5
6
7
8
9
10



{
    "transaction": {
        "activity": "FinancingConsumer",
        "amount": 1500,
        "vatAmount": 0,
        "payeeReference": "ABC856",
        "receiptReference": "ABC855",
        "description": "description for transaction"
    }
}
Required Field Type Description
check︎ transaction object The transaction object containing details about the reversal transaction.
check︎ activity string FinancingConsumer.
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(30) The payeeReference is the receipt/invoice number if receiptReference is not defined, which is a unique reference with max 50 characters set by the merchant system. This must be unique for each operation and must follow the regex pattern [\w-]*.
  receiptReference string(50) A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.
check︎ description string A textual description of the reversal.

Reversal Response

The reversal resource will be returned, containing information about the newly created reversal transaction.

The created reversal resource contains information about the reversal transaction made against a invoice payment.

Capture Response

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
32
33
34
35
36
37



{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversal": {
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "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": "ABC123", 
            "receiptReference": "ABC123", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/invoice/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-reversal",
                    "method": "PATCH"
                }
            ]
        }
    }
}
Field
Type
paymentOrder string

The relative URL and unique identifier of the payment resource this cancellations belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

authorization object
The authorization object.
id string

The relative URL and unique identifier of the authorization resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

itemDescriptions object
The object representation of the itemDescriptions resource.
id string

The relative URL and unique identifier of the itemDescriptions resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

transaction object

The object representation of the generic transaction resource, containing information about the current transaction.

id string

The relative URL and unique identifier of the transaction resource this reversals belongs to. 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 textual description of the purchase. Maximum length is 40 characters.

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

A unique reference to the transaction, provided by the merchant. Can be used as an invoice or receipt number as a supplement to payeeReference.

failedReason string
The human readable explanation of why the payment failed.
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.

List Reversal Transactions

The reversals resource will list the reversal transactions (one or more) on a specific payment.

Request 



1
2
3
4



GET /psp/invoice/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 invoice 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



HTTP/1.1 200 OK
Content-Type: application/json





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



{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversals": { 
        "receiptReference": "AH12355", 
        "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
paymentOrder string

The relative URL and unique identifier of the payment resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

reversals object
The current reversals resource.
id string

The relative URL and unique identifier of the reversals resource this reversals belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.

reversalList array
The reversal transaction object described in the reversal resource below.
id string

The relative URL and unique identifier of the transaction resource this reversals belongs to. 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 textual description of the purchase. Maximum length is 40 characters.

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

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

Reversal can only be done on an captured transaction where there are some captured amount not yet reversed.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

    Merchant->>SwedbankPay: Post <Invoice reversals>
    activate Merchant
    activate SwedbankPay
    SwedbankPay-->>Merchant: transaction resource
    deactivate Merchant
    deactivate SwedbankPay