Other Features

Payment Resource

The payment resource is central to all payment instruments. All operations that target the payment resource directly produce a response similar to the example seen below. The response given contains all operations that are possible to perform in the current state of the payment.

Request

1
2
3
4

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

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

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

{
    "payment": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "state": "Ready",
        "operation": "Purchase",
        "intent": "Authorization", 
        "currency": "DKK",
        "amount": 1500,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "da-DK",
        "prices": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "payeeInfo": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo"
        },
        "payers": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        },
        "urls": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "transactions": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions"
        },
        "authorizations": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations"
        },
        "captures": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures"
        },
        "reversals": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals"
        },
        "cancellations": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations"
        }
    },
    "operations": [,
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/operation=authorize",
            "rel": "view-authorization",
            "contentType": "application/javascript"
        },
        {
            "method": "GET",
            "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "redirect-authorization",
            "contentType": "text/html"
        },
    ]
}

Operations

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

Operation paid-payment

The paid-payment operation confirms that the transaction has been successful and that the payment is completed.

A paid-payment operation looks like the following:

1
2
3
4
5
6

{
   "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
   "rel": "paid-payment",
   "method": "GET",
   "contentType": "application/json"
}

To inspect the paid payment, you need to perform an HTTP GET request towards the operation’s href field. An example of how the request and response look like is given below.

Request

1
2
3
4

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

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

{
  "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "paid": {
    "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/paid",
    "number": 1234567890,
    "transaction": {
      "id": "/pspmobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/",
      "number" : 1234567891
    },
    "payeeReference": "CD123",
    "orderReference": "AB1234",
    "amount": 1500,
  }
}

Operation failed-payment

The failed-payment operation means that something went wrong during the payment process, the transaction was not authorized, and no further transactions can be created if the payment is in this state.

A failed-payment operation looks like the following:

1
2
3
4
5
6

{
   "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/failed",
   "rel": "failed-payment",
   "method": "GET",
   "contentType": "application/problem+json"
}

To inspect why the payment failed, you need to perform an HTTP GET request towards the operation’s href field.

Under details you can see the problem message and under problems you can see which problem and the description of the problem with the corresponding error code.

An example of how the request and response look like is given below.

Request

1
2
3
4

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

Response

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

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

{
   "problem": {
       "type": "https://api.externalintegration.payex.com/psp/errordetail/mobilepay/acquirererror",
       "title": "Operation failed",
       "status": 403,
       "detail":  "Unable to complete Authorization transaction, look at problem node!", 
       "problems": [
        {
          "name": "ExternalResponse",
          "description": "REJECTED_BY_ACQUIRER-unknown error, response-code: 51"
        }
        ]
     }
  }
}

Operation aborted-payment

The aborted-payment operation means that the merchant has aborted the payment before the payer has fulfilled the payment process. You can see this under abortReason in the response.

An aborted-payment operation looks like the following:

1
2
3
4
5
6

{
    "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/<paymentId>/aborted",
    "rel": "aborted-payment",
    "method": "GET",
    "contentType": "application/json"
}

To inspect why the payment was aborted, you need to perform an HTTP GET request towards the operation’s href field. An example of how the request and response looks like is given below.

Request

1
2
3
4

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

Response

1
2
3
4
5
6
7
8
9

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

{
  "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
  "aborted": {
    "abortReason": "Aborted by consumer"
  }
}

Payment State

The state field on the authorization does not indicate whether a given transaction was successful or not, it only tells whether the authorization resource itself is operational or not. To figure out the state of i.e. authorization transactions, you have two options:

Paid or Failed Operations

You can perform a GET request on the authorization. As long as the authorization has been completed, successful or not, you will find the Paid or Failed operation among the operations in the response.

Please note that a authorization where a Failed attempt has been made, but the payer still has attempts left to complete the authorization, you won’t see the Failed operation. It will only appear when all attempts have been made.

Authorization or Sale Transactions

Find the authorization’s list of transactions either by expanding it when retrieving the authorization, or by performing a GET request towards the transactions.id URI.

If you find a transaction with type equal to authorization, with its state equal to Completed, you can be sure that the amount of the authorization has been reserved or withdrawn and that the authorization can be considered successful.

Create Payment

To create a MobilePay Online payment, you perform an HTTP POST against the /psp/mobilepay/payments resource. Please read the general information on how to compose a valid HTTP request before proceeding.

An example of a payment creation request is provided below. Each individual field of the JSON document is described in the following section. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

Request

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

POST /psp/mobilepay/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "DKK",
        "prices": [
            {
                "type": "Visa",
                "amount": 1500,
                "vatAmount": 0,
                "FeeAmount": 5
            },
            {
                "type": "MasterCard",
                "amount": 1500,
                "vatAmount": 0,
                "FeeAmount": 10
            },
            {
                "type": "MobilePay",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "da-DK",
        "urls": {
            "hostUrls": ["https://example.com", "https://example.net"],
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "callbackUrl": "https://example.com/payment-callback"
        },
        "payeeInfo": {
            "payeeId": "12345678-1234-1234-1234-123456789012",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {  
            "payerReference": "AB1234",
        }
    },
    "mobilepay": {
        "shoplogoUrl": "https://example.com/shop-logo.png"
    }
}

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

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

{
    "payment": {
        "prices": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices"
        },
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 75100000121,
        "created": "2018-09-11T10:58:27.4236127Z",
        "updated": "2018-09-11T10:58:30.8254419Z",
        "instrument": "MobilePay",
        "operation": "Purchase",
        "intent": "Authorization",
        "state": "Ready",
        "currency": "DKK",
        "amount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "PostmanRuntime/7.2.0",
        "userAgent": "Mozilla/5.0",
        "language": "da-DK",
        "transactions": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions"
        },
        "urls": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls"
        },
        "payeeInfo": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeinfo"
        },
        "payers": {
           "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers"
        }
    },
    "operations": [
        {
            "method": "PATCH",
            "href": "https://https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort"
        },
        {
            "method": "GET",
            "href": "https://https://ecom.externalintegration.payex.com/mobilepay/payments/authorize/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "rel": "redirect-authorization"
        }
    ]
}

Purchase

Posting a payment (operation Purchase) returns the options of aborting the payment altogether or creating an authorization transaction through the redirect-authorization hyperlink. Use the expand request parameter to get a response that includes one or more expanded sub-resources inlined.

1
2
3
4
5

{
    "payment": {
        "operation": "Purchase"
    }
}

Operations

When a payment resource is created and during its lifetime, it will have a set of operations that can be performed on it. Which operations are available will vary depending on the state of the payment resource, what the access token is authorized to do, etc. A list of possible operations and their explanation is given below.

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

{
    "payment": {},
    "operations": [
        {
            "href": "http://https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "update-payment-abort",
            "method": "PATCH"
        },
        {
            "href": "https://https://ecom.externalintegration.payex.com/mobilepay/payments/authorize/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "rel": "redirect-authorization",
            "method": "GET"
        },
        {
            "href": "https://https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
            "rel": "create-capture",
            "method": "POST"
        },
        {
            "href": "https://https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations",
            "rel": "create-cancellation",
            "method": "POST"
        },
        {
            "href": "https://https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals",
            "rel": "create-reversal",
            "method": "POST"
        },
    ]
}

The operations should be performed as described in each response and not as described here in the documentation. Always use the href and method as specified in the response by finding the appropriate operation based on its rel value. The only thing that should be hard coded in the client is the value of the rel and the request that will be sent in the HTTP body of the request for the given operation.

CompleteUrl

This URL will be used by Swedbank Pay when a payment is Completed or Failed. If your integration subscribes to the onPaymentCompleted and possibly the onPaymentFailed event, no redirect or use of the completeUrl will take place. But if you do not have any event handler for the onPaymentCompleted event, the Swedbank Pay JavaScript will perform an HTTP redirect in the top frame to the completeUrl. You will still need to do a GET request on the payment resource to find the final status (Completed or Failed).

MobilePay Online transactions

All MobilePay Online specific transactions are described below.

Authorizations

Request

1
2
3
4

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

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

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorizations": { 
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
        "authorizationList": [{
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "consumer": {
                    "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/consumer"
                },
                "legalAddress": {
                    "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/legaladdress"
                },
                "billingAddress": {
                    "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/billingaddress"
                },
            "transaction": {
                "id": "/psp/mobilepay/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,
                "operations": [
                       {
                            "method": "POST",
                            "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
                            "rel": "create-authorization",
                            "contentType": "application/json"
                        },
                        {
                            "href": "https://api.externalintegration.payex.com/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
                            "rel": "edit-authorization",
                            "method": "PATCH"
                        }
                ]
            }
        }]
    }
}

Create authorization transaction

The authorization transaction is initiated by redirecting the payer to the hyperlink returned in the redirect-authorization request.

Captures

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": { 
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures",
        "captureList": [{
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/mobilepay/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": "Capture",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Create capture transaction

A capture transaction - to withdraw money from the card connected to the payer’s MobilePay account - can be created after a completed authorization by performing the create-capture operation.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13

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

{
    "transaction": {
        "amount": 1000,
        "vatAmount": 250,
        "payeeReference": 1234,
        "description" : "description for transaction"
    }
}

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

Cancellations

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "cancellations": { 
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations",
        "cancellationList": [{
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/mobilepay/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": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Create cancellation transaction

Perform the create-cancel operation to cancel a previously created payment. You can only cancel a payment - or part of payment - not yet captured.

Request

1
2
3
4
5
6
7
8
9
10
11

POST /psp/mobilepay/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"
    }
}

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

Reversals

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversals": { 
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals",
        "reversalList": [{
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/mobilepay/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",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Create reversal transaction

The create-reversal operation reverses a previously created and captured payment.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13

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

{
    "transaction": {
        "amount": 1000,
        "vatAmount": 0,
        "description" : "Test Reversal",
        "payeeReference": "DEF456"
    }
}

The created reversal resource contains information about the reversal transaction made against a mobilepay 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/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "reversal": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/mobilepay/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", 
            "isOperational": false,
            "problem": {
                "type": "https://api.payex.com/psp/errordetail/mobilepay/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-reversal",
                    "method": "PATCH"
                }
            ]
        }
    }
}

Capture Sequence

Capture can only be perfomed on a payment with a successfully authorized transaction. It is possible to do a part-capture where you only capture a smaller amount than the authorized amount. You can later do more captures on the same payment up to the total authorization amount.

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

  Merchant->>SwedbankPay: POST <mobilepay capture>
  activate Merchant
  activate SwedbankPay
  SwedbankPay-->>Merchant: transaction resource
  deactivate SwedbankPay
  deactivate Merchant

Cancel Sequence

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 captured amount and the authorized amount.

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

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

Reversal Sequence

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

sequenceDiagram
  participant SwedbankPay as Swedbank Pay

  Merchant->>SwedbankPay: POST <mobilepay reversal>
  activate Merchant
  activate SwedbankPay
  SwedbankPay-->>Merchant: transaction resource
  deactivate SwedbankPay
  deactivate Merchant

The response will be the payment resource with its state set to Aborted.

Settlement and Reconciliation

The information needed to reconcile captured funds - the balance report and transactions list - are available for all merchants using Swedbank Pay.

• By default, the settlement files will be sent to you by via e-mail.
• We also have the option to send it via SFTP as well, if this is something you would like then you need to state this to your sales representative, so they can inform the setup team when the time is ready.
• The settlement frequency is defined in the agreement and you will receive it (per default) once a month, or once a week.
• You do not need to subscribe, the files will be delivered by default.

Contact omni.client@swedbankpay.se for further inquiries regarding this.

Settlement

There are two main alternatives for settlement - either we handle the settlement process for you, or you handle the process yourself :

Swedbank Pay handles the settlement process

Swedbank Pay handles the settlement process on your behalf, (called “Redovisningsservice”). Swedbank Pay transfers the net amount to you directly.

Swedbank Pay Checkout

When choosing Swedbank Pay Checkout we always handle the settlement process for you, gathering all your eCommerce payments in one place. Straighforward and time efficient.

You handle the settlement process yourself

If you will handle the settlement yourself, then Swedbank Pay will send you an invoice with the relevant fees, in addition to the report and transactions lists. Your acquirer will transfer settled funds to you.

Balance Report

The Balance Report (a .pdf file) specifies the total sales for a specific period, including fees and VAT. The report contains three parts: a payment summary and specifications for sales and for fees.

Payment Summary

Provides a summary of the Amount sold, Fees and VAT. If Swedbank Pay handles the settlement process, the Transferedamount - shown in the balance report summary is equivalent to the disbursement on the bank statement (the remaining total amount after fees).

Sales specification

Provides a specification over sales for the given period. The sales total is specified per payment area (CreditCard, Invoice) and underlying payment instruments. Each sales row specify Quantity, Sum sales and Amount to pay out, the last one is only eligble if Swedbank Pay handles the Settlement process.

Fees specification

Provides a specification over fees for the given period. The fees total is specified per payment area (CreditCard, Invoice) and underlying payment instruments. Each fees row specify Quantity (sales), Amount (sales), Unit price, Provision and fee Amount. If you handle the settlement process yourselves you will receive a separat invoice for fees.

Transactions List

The Transaction List (provided in .xlsx and .xml formats) specifies all transactions for a specific period, including a summary of transactions grouped by payment instrument. Both formats contain the same information, but the xml file is meant for computer processing while the excel workbook is meant for human interaction.

The first row contains the name of the Swedbank Pay company (e.g. Swedbank Pay Solutions AB) that the merchant has the contract with, and the balance report number. The header fields contain a summary of the transactions displayed in the body.

Header fields

Body fields

Reconciliation

To do the reconciliation, you need to match the information in your system against the information provided by Swedbank Pay in the balance report and transaction list. Below is a sequence diagram detailing the interaction.

sequenceDiagram
    participant SwedbankPay as Swedbank Pay

    activate Merchant
    activate SwedbankPay
    Merchant-->>SwedbankPay: Online payment transactions
    deactivate Merchant

    deactivate SwedbankPay

    activate Merchant

    SwedbankPay->>Merchant: Balance Report (PDF-file)
    note left of Merchant: files are sent by e-mail or file transfer
    SwedbankPay->>Merchant: Transaction list (XLSX-file)
    SwedbankPay->>Merchant: Transaction list (XML-file)
    deactivate Merchant

There are two ways for you to match the information from your system with the information given in the reconciliation files from Swedbank Pay:

1. You can use information generated by your system (you will have to set a unique payeeReference when you make the transaction), or
2. You can use the transaction number generated by Swedbank Pay (this is called transaction number and is returned from Swedbank Pay after you have created the transaction).

A credit card transaction is made when you either make a capture or a reversal. In the input data for making a capture, you will set the payeeReference. The unique value of this field is the same as the field called OrderID in the reconciliation file.

1
2
3
4
5
6
7
8

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Reversal",
        "payeeReference": "ABC123"
    }
}

When you receive the response from Swedbank Pay, the response will include transaction.number. This is the same as the field called TransactionNo in the reconciliation file.

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "capture": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "transaction": {
            "id": "/psp/mobilepay/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": "Capture",
            "state": "Initialized",
            "number": 1234567890,
            "amount": 1500,
            "vatAmount": 250,
            "description": "Test Capture",
            "payeeReference": "ABC123",
            "failedReason": "",
            "isOperational": false,
            "operations": []
        }
    }
}

• payeeReference sent to Swedbank Pay is equal to OrderId in the reconciliation file.
• capture.transaction.number returned from Swedbank Pay is equal to TransactionNo in reconciliation file.

Below you will see the API mapping tables to the fields in the settlement report for Capture and Reversal.

Capture

Reversal

Samples

The content of the files depends on the type of agreement you have made with Swedbank Pay. For some payment instruments, only option A is available, while for other payment instruments, only option B is available. The sample files can be downloaded below.

Option A: Swedbank Pay handles the settlement process

• PDF Balance Report for Swedbank Pay Checkout
• PDF Balance Report
• XLSX Transaction List
• XML Transaction List

Option B: You will handle the settlement process yourself

• PDF Balance Report
• XLSX Transaction List
• XML Transaction List

Split Settlement

The split settlement feature is the easy way of doing settlements for companies with multiple sub merchants. With a few easy steps, the settlement process becomes more efficient with regards to invoicing, payouts and setup for both your sub merchants and yourself.

In short, it is a settlement feature where a company with a website or an app can attach specific subsite numbers to sub merchants selling their goods or services through the company. The subsite number is used to match the transactions with the correct sub merchant, so the settlement is automatically split between them. If you run a site selling tickets to concerts, theatres, sporting events etc., each venue gets its own subsite number. If you run a funeral home, the sub merchants can be everything from flower shops to charities.

What we need from you as a company

• Submit a KYC (Know Your Costumer) form for each sub merchant you want to include. We will also do a KYC check on your sub merchants, providing extra security for you.
• Give every sub merchant who sells goods/services through your website or in your app a unique subsite number. This must be included in the KYC form. We recommend using the same customer number they have in your system.
• Attach the subsite number to all the goods/services the sub merchant sells through your website or app, so the goods/services can be matched to the correct merchant in our back office system.
• A partner agreement is needed for automatic deduction of revenue cuts and fees.

How it works

1. We set up the sub merchant subsite number in our systems.
2. That number is added in the requests subsite field in when you create the payment for the goods or service.
3. The customer selects payment instrument and completes the payment.
4. The payment goes into the client funds account.
5. Swedbank Pay matches the transaction and the merchant using the subsite number.
6. The settlement is split and connected to the correct merchant.
7. Revenue cuts for the super merchant and fees from Swedbank Pay are deducted automatically.
8. Payout to the sub merchant is done.

The upsides

Sub merchants being connected to Swedbank Pay through the super merchant instead of having separate setups has a lot of pros:

• You only need one agreement for each payment instrument (credit card, Vipps, Swish, MobilePay Online, invoice) and payment gateway.
• You only need one acquiring agreement.
• You only one Vipps or Swish certificate.
• You can add more payment instruments easily, as it only has to be done once.
• New sub merchants can be set up quickly, as the only thing needed is a KYC form and a subsite number. This shortens the setup time for both you and us to a matter of hours.
• The automatic settlement split and deduction of fees and revenue cuts minimizes the work for your accounting department, as you do not have to invoice your sub merchants.
• The subsite split is available for all the payment instruments we offer on our eCom platform.

Good to know

With regards to admin functions, we offer a full integration towards our admin system. This way, you do not have to log in to Swedbank Pay Admin to perform these operations.

Captures and cancels

Captures and cancels are done by the super merchant the same way as any other normal flow.

Reversals

In cases where you need to do reversals, this will be performed by the super merchant. The reversal amount will be charged from the sub merchants subsite number. If the sub merchants balance is 0 (zero), the super merchant will be invoiced. The super merchant will in turn have to invoice this amount to the sub merchant.

Introduction

The Payment Link can be implemented for payment instruments listed below, using the Redirect platform and Swedbank Pay hosted payment page.

• Credit card
• MobilePay Online
• Swish
• Vipps

When the payer starts the purchase process in your merchant or webshop site, you need to make a POST request towards Swedbank Pay with your Purchase information. You receive a Payment Link (same as redirect URL) in response.

You have to distribute the Payment Link to the payer through your order system, using channels like e-mail or SMS.

When the payer clicks on the Payment Link, the Swedbank Pay payment page will open, letting him or her enter the payment details (varying depending on payment instrument) in a secure Swedbank Pay hosted environment.

When paying with credit card and if required, Swedbank Pay will handle 3-D Secure authentication.

After completion, Swedbank Pay will redirect the browser back to your merchant/webshop site.

If callbackURL is set the merchant system will receive a callback from Swedbank Pay, enabling you to make a GET request towards Swedbank Pay with the id of the payment received in the first step, which will return the purchase result.

E-mail And SMS Recommendations

When you as a merchant sends an e-mail or SMS to the payer about the Payment Link, it is recommended to include contextual information which helps him or her understand what will happen when clicking the Payment Link. We recommend that you include the following:

• The name of the merchant/shop initiating the payment
• An understandable product description, describing what kind of service the payer will pay for.
• Some order-id (or similar) that exists in the merchant’s order system.
• The price and currency.
• Details about shipping method and expected delivery (if physical goods will be sent to the payer).
• A link to a page with the merchant’s terms and conditions (such as return policy) and information about how the payer can contact the merchant.
• Details informing that the payer accepts the Terms & Conditions when clicking on the Payment Link.

Receipt Recommendations

We recommend that you send an e-mail or SMS confirmation to the payer with a receipt when the payment has been fulfilled.

API Requests

The API requests depend on the payment instrument you are using when implementing the Payment Link scenario, see purchase flow. One-phase payment instruments will not implement capture, cancellation or reversal. The options you can choose from when creating a payment with key operation set to Purchase are listed below.

Screenshots

When clicking the payment link, the payer will be directed to a payment page similar to the examples below, where payment information can be entered.

Options

All valid options when posting a payment with operation Purchase, are described in each payment instrument’s respective API reference. Please see the general sequence diagrams for more information about payments in one-phase (e.g. Swish and credit card with autocapture) and two-phase (e.g. Card, MobilePay Online, Vipps).

Authorization

When using two-phase payment instruments you reserve the amount with an authorization, and you will have to specify that the intent of the purchase is Authorize. The amount will be reserved but not charged. You have to make a Capture or Cancel request later (i.e. when you are ready to ship the purchased products).

Capture

Capture can only be performed on a payment with a successfully authorized transaction. It is possible to do a part-capture where you only capture a smaller amount than the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

If you want the credit card to be charged right away, you will have to specify that the intent of the purchase is AutoCapture. The card will be charged and you don’t need to do any more financial operations to this purchase.

Cancel

Cancel can only be done on an authorized transaction. If you cancel after doing a part-capture you will cancel the difference between the captured amount and the authorized amount.

Reversal

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

General

When implementing the Payment Link scenario, it is optional to set a callbackURL in the POST request. If callbackURL is set Swedbank Pay will send a request to this URL when the payer has completed the payment. See the Callback API description here.

Purchase flow

The sequence diagrams display the high level process of the purchase, from generating a Payment Link to receiving a Callback.

This in a generalized flow as well as a specific 3-D Secure enabled credit card scenario.

When dealing with card payments, 3-D Secure authentication of the cardholder is an essential topic. There are three alternative outcomes of a card payment:

• 3-D Secure enabled - by default, 3-D Secure should be enabled, and Swedbank Pay will check if the card is enrolled with 3-D Secure. This depends on the issuer of the card. If the card is not enrolled with 3-D Secure, no authentication of the cardholder is done.
• Card supports 3-D Secure - if the card is enrolled with 3-D Secure, Swedbank Pay will redirect the cardholder to the authentication mechanism that is decided by the issuing bank. Normally this will be done using BankID or Mobile BankID.

sequenceDiagram
    activate Payer
    Payer->>-MerchantOrderSystem: payer starts purchase
    activate MerchantOrderSystem
    MerchantOrderSystem->>-Merchant: start purchase process
    activate Merchant
    Merchant->>-SwedbankPay: POST [payment] (operation=PURCHASE)
    activate SwedbankPay
    note left of Merchant: First API request
    SwedbankPay-->>-Merchant: payment resource with payment URL
    activate Merchant
    Merchant-->>-MerchantOrderSystem: Payment URL sent to order system
    activate MerchantOrderSystem
    MerchantOrderSystem-->>-Payer: Distribute Payment URL through e-mail/SMS
    activate Payer
    note left of Payer: Payment Link in e-mail/SMS
    Payer->>-SwedbankPay: Open link and enter payment information
    activate SwedbankPay

    
        opt Card supports 3-D Secure
        SwedbankPay-->>-Payer: redirect to IssuingBank
        activate Payer
        Payer->>IssuingBank: 3-D Secure authentication process
        Payer->>-SwedbankPay: access authentication page
        activate SwedbankPay
        end
    

    SwedbankPay-->>-Payer: redirect to merchant site
    activate Payer
    note left of SwedbankPay: redirect back to merchant
    Payer->>-Merchant: access merchant page
    activate Merchant
    Merchant->>-SwedbankPay: GET [payment]
    activate SwedbankPay
    note left of Merchant: Second API request
    SwedbankPay-->>-Merchant: payment resource
    activate Merchant
    Merchant-->>-Payer: display purchase result

Options after posting a payment

• If the payment enable a two-phase flow (Authorize), you will need to implement the Capture and Cancel requests.
• It is possible to “abort” the validity of the Payment Link. See the Abort description here.
• For reversals, you will need to implement the Reversal request.
• When implementing the Payment Link scenario, it is optional to set a callbackURL in the POST request. If callbackURL is set Swedbank Pay will send a postback request to this URL when the payer has completed the payment. See the Callback API description here.

Description

The description field is a 40 character length textual summary of the purchase. It is needed to specify what payer is actually purchasing. Below you will find an abbreviated Card Payments Purchase request.

As you can see the description field is set to be Test Description in the the code example.

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

POST /psp/mobilepay/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "paymentorder": {
        "operation": "Purchase",
        "intent":  "Authorization", 
        "currency": "DKK",
        "description": "Test Description",
        "generateRecurrenceToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "da-DK",
        "urls":
            "hostUrls": ["https://example.com"]
    }
}

Callback

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.

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

Payment Instrument Callback

1
2
3
4
5
6
7
8
9
10

{
    "payment": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 222222222
    },
    "transaction": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "number": 333333333
    }
}

When performing an HTTP GET request towards the URI 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 mobilepay 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/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "authorization": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
        "itemDescriptions": {
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177/itemDescriptions"
        },
        "transaction": {
            "id": "/psp/mobilepay/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/mobilepay/3DSECUREERROR",
                "title": "Error when complete authorization",
                "status": 400,
                "detail": "Unable to complete 3DSecure verification!",
                "problems": [
                ] 
            "operations": [
                {
                    "href": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                    "rel": "edit-authorization",
                    "method": "PATCH"
                }
            ]
        }
    }
}

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 mobilepay payment
    deactivate Merchant
    note left of Merchant: First API request
    SwedbankPay-->>+Merchant: payment resource
    deactivate SwedbankPay

Transactions

A payment contains sub-resources in the form of transactions. Most operations performed on a payment ends up as a transaction resource. The different types of operations that alter the state of the payment by creating a transaction is described below.

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

Request

1
2
3
4

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

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transactions": { 
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions",
        "transactionList": [{
            "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/mobilepay/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": "Transaction",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Transaction

The transaction resource contains the generic details of a transaction on a specific payment.

When a transaction is created it will have one of three states:

• Initialized - if there is some error where the source is undeterminable (network failure, etc), the transaction will remain Initialized. The corresponding state of the payment order will in this case be set to pending. No further transactions can be created.
• Completed - if everything went ok the transaction will follow through to completion.
• Failed - if the transaction has failed (i.e. a denial from the acquiring bank) it is possible to retry (i.e the payer tries using another card) up to a maximum amount of retries (in that case which the payment order gets the state failed as well).

Request

1
2
3
4

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

Response

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "transaction": {
        "id": "/psp/mobilepay/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":  "Capture", 
        "state": "Initialized",
        "number": 1234567890,
        "amount": 1000,
        "vatAmount": 250,
        "description": "Test transaction",
        "payeeReference": "AH123456",
        "failedReason": "",
        "isOperational": true,
        "operations": []
    }
}

Transaction Problems

In the event that a transaction is failed, the transaction response will contain a problem property as seen in the example below. To view all the problems that can occur due to an unsuccesful transaction, head over to the problems section.

The created transaction resource contains information about the transaction transaction made against a mobilepay 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

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

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

Prices

The prices resource lists the prices related to a specific payment. In short, it is where you enter the payment’s amount. It consists of the payment’s id and the priceList, which again contains the payment’s type, amount and vatAmount.

The type refers to the payment instrument, like Swish, Trustly or Creditcard. Read more about the types below the code example and table. The amount refers to the full amount (incl. VAT) for the payment, and vatAmount indicates how much of the full amount which is VAT.

Request

1
2
3
4

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

Response

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

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

{
    "payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "prices": {
        "id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices",
        "priceList": [
            {
                "type": "VISA",
                "amount": 2350,
                "vatAmount": 0
            },
            {
                "type": "MasterCard",
                "amount": 2350,
                "vatAmount": 0
            }
        ]
    }
}

Prices Object Types

Each payment instrument have one or more prices object types. Usually there is only one, whichs corresponds with the name of the payment instrument, like Vipps, Swish or Mobilepay.

The most common occurence of several object types is for card payments. While it is possible to group them all as Creditcard, you can also differentiate on card types as shown in the example above. This is useful if certain card brands have additional fees, others have discounts or something similar. If you do differentiate, you need to add all accepted card brands as a separate object types.

MobilePay Online Payments

Metadata

Metadata can be used to store data associated to a payment that can be retrieved later by performing a GET on the payment. Swedbank Pay does not use or process metadata, it is only stored on the payment so it can be retrieved later alongside the payment. An example where metadata might be useful is when several internal systems are involved in the payment process and the payment creation is done in one system and post-purchases take place in another. In order to transmit data between these two internal systems, the data can be stored in metadata on the payment so the internal systems do not need to communicate with each other directly. The usage of metadata field is shown in the abbreviated Purchase request below.

Request

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

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

{
  "payment": {
    "operation": "Purchase",
    "intent":  "Authorization", 
    "currency": "SEK",
    "description": "Test Purchase",
    "userAgent": "Mozilla/5.0...",
    "language": "sv-SE",
    "urls": {
      "hostUrls": ["https://example.com"],
      "completeUrl": "https://example.com/payment-completed"
    },
    "payeeInfo": {
      "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
      "payeeReference": "CD1234",
    },
    "payer": {  
      "payerReference": "AB1234",
    },
    "metadata": {
        "key1": "value1",
        "key2": 2,
        "key3": 3.1,
        "key4": false
    },
    "prefillInfo": {
        "msisdn": "+4798765432"
    }
  }
}

Request

1
2
3
4

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