Checkout v2

Callback

schedule 7 min read

Receive asynchronous, server-to-server updates from Swedbank Pay when transactions are performed on a payment.

Edit "Callback" on GitHub
warning

While the callback feature is mandatory, we would like to emphasize that it is mainly a fail-safe feature. We strongly advice that it is not your primary mean of checking for payment updates.

When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform a callback to inform the payee (merchant) about this update.

Providing a callbackUrl in POST requests is mandatory. Below we provide three example scenarios of why this is important:

  1. If the payer closes the payment window, the merchant will never know what happened to the payment if callbackUrl is not implemented.
  2. If the payer stops up in a payment app such as Vipps or Swish, the payer will never come back to the merchant. This means that the merchant won’t know what happened to the payment unless callbackUrl is implemented.
  3. If a payer experiences a network error or something else happens that prevents the payer from being redirected from Swedbank Pay back to the merchant website, the callbackUrl is what ensures that you receive the information about what happened with the payment.
  • When a change or update from the back-end system are made on a payment or transaction, Swedbank Pay will perform an asynchronous server-to-server callback to inform the payee (merchant) about this update.
  • It is important to know that the callback is asynchronous, and not real-time. As we can’t guarantee when you get the callback, there could be a delay between when the payer is returned back to the merchant and when the callback arrives. If the merchant chooses to wait for the callback, the payer might be left at the merchant’s page until the response comes.
  • Swedbank Pay will make an HTTP POST to the callbackUrl that was specified when the payee (merchant) created the payment.
  • When the callbackUrl receives such a callback, an HTTP GET request must be made on the payment or on the transaction. The retrieved payment or transaction resource will give you the necessary information about the recent change/update.
  • As it isn’t scaled to be a primary source of updates, no given response time can be guaranteed, and a callback might fail. It will be retried if that should happen. Below are the retry timings, in seconds from the initial transaction time:
    • 30 seconds
    • 60 seconds
    • 360 seconds
    • 432 seconds
    • 864 seconds
    • 1265 seconds
  • A callback should return a 200 OK response.

The callback is sent from 91.132.170.1 in both the test and production environment.

To understand the nature of the callback, the type of transaction, its status, etc., you need to perform a GET request on the received URL and inspect the response. The transaction type or any other information can not and should not be inferred from the URL. See URL usage for more information.

Payment Instrument Callback

1
2
3
4
5
6
7
8
9
10
{
    "payment": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 222222222
    },
    "transaction": {
        "id": "/psp/checkout/v2/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "number": 333333333
    }
}

When performing an HTTP GET request towards the URL found in the transaction.id field of the callback, the response is going to look something like the abbreviated example provided below.

The created authorization resource contains information about the authorization transaction made against a checkout/v2 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
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
HTTP/1.1 200 OK
Content-Type: application/json

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

Field Type Description  
payment string The relative URL and unique identifier of the payment resource this authorization belongs to. Please read about URL Usage to understand how this and other URLs should be used in your solution.  
authorization string The current authorization transaction resource.  
└➔ id string The relative URL and unique identifier of the authorization resource this authorization 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 authorization 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.  
└─➔ id string The relative URL and unique identifier of the transaction resource this authorization 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 orfailed. If a partial authorization has been done and further transactionsare 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. It is set per operation to ensure an exactly-once delivery of a transactional operation. See payeeReference for details. In Invoice Payments payeeReference is used as an invoice/receipt number, if the receiptReference is not defined.  
└─➔ receiptReference string A unique reference for the transaction. This reference is used as an invoice/receipt number.  
└─➔ 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.  

The sequence diagram below shows the HTTP POST you will receive from Swedbank Pay, and the two GET requests that you make to get the updated status.

sequenceDiagram
    Participant Merchant
    Participant SwedbankPay as Swedbank Pay

    activate SwedbankPay
    SwedbankPay->>+Merchant: POST <callbackUrl>
    deactivate SwedbankPay
    note left of Merchant: Callback by Swedbank Pay
    Merchant-->>+SwedbankPay: HTTP response
    Merchant->>+SwedbankPay: GET checkout/v2 payment
    deactivate Merchant
    note left of Merchant: First API request
    SwedbankPay-->>+Merchant: payment resource
    deactivate SwedbankPay