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
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",
"payerReference": "AB1234",
"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"
},
"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"
},
]
}
Field | Type | Description |
---|---|---|
payment |
object |
The payment object contains information about the specific payment. |
└➔ id
|
string |
The relative URI and unique identifier of the payment resource . Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ number
|
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead. |
└➔ created
|
string |
The ISO-8601 date of when the payment was created. |
└➔ updated
|
string |
The ISO-8601 date of when the payment was updated. |
└➔ state
|
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment, not the state of any transactions performed on the payment. To find the state of the payment’s transactions (such as a successful authorization), see the transactions resource or the different specialized type-specific resources such as authorizations or sales . |
└➔ prices
|
object |
The prices resource lists the prices related to a specific payment. |
└➔ prices.id
|
string |
The relative URI and unique identifier of the prices resource . Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ description
|
string |
A 40 character length textual description of the purchase. |
└➔ payerReference
|
string(40) |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. |
└➔ language
|
string |
da-DK , fi-FI or en-US . |
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment can be retrieved. |
└➔ payeeInfo
|
string |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
operations |
array |
The array of possible operations to perform |
└─➔ method
|
string |
The HTTP method to use when performing the operation. |
└─➔ href
|
string |
The target URI to perform the operation against. |
└─➔ rel
|
string |
The name of the relation the operation has to the current resource. |
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 | Description |
---|---|
update-payment-abort |
abort s the payment order before any financial transactions are performed. |
redirect-authorization |
Contains the URI that is used to redirect the payer to the Swedbank Pay Payments containing the card authorization UI. |
view-authorization |
Contains the JavaScript href that is used to embed the card authorization UI directly on the webshop/merchant site |
view-payment |
Contains the URI of the JavaScript to create a Seamless view iframe directly without redirecting the payer to a separate payment page. |
create-capture |
Creates a capture transaction in order to charge the reserved funds from the payer. |
create-cancellation |
Creates a cancellation transaction that cancels a created, but not yet captured payment. |
paid-payment |
Returns the information about a payment that has the status paid . |
failed-payment |
Returns the information about a payment that has the status failed . |
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,
}
}
Field | Type | Description |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ transaction
|
string |
The transaction object, containing information about the current transaction. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└─➔ 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, for that id should be used instead. |
└➔ 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. |
└➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. |
└➔ 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. |
└➔ tokens
|
integer |
List of tokens generated. |
└➔ details
|
integer |
A human readable and descriptive text of the payment. |
└─➔ cardBrand
|
string |
Visa , MC , etc. The brand of the card. |
└─➔ maskedPan
|
string |
The masked PAN number of the card. |
└─➔ cardType
|
string |
Credit Card or Debit Card . Indicates the type of card used for the authorization. |
└─➔ issuingBank
|
string |
The name of the bank that issued the card used for the authorization. |
└─➔ countryCode
|
string |
The country the card is issued in. |
└─➔ acquirerTransactionType
|
string |
3DSECURE or SSL . Indicates the transaction type of the acquirer. |
└─➔ acquirerStan
|
string |
The System Trace Audit Number assigned by the acquirer to uniquely identify the transaction. |
└─➔ acquirerTerminalId
|
string |
The ID of the acquirer terminal. |
└─➔ acquirerTransactionTime
|
string |
The ISO-8601 date and time of the acquirer transaction. |
└─➔ nonPaymentToken
|
string |
Result of our own tokenization of the card used. Activated in POS on merchant or merchant group. |
└─➔ externalNonPaymentToken
|
string |
Result of external tokenization. This value varies depending on cards, acquirer, customer, etc. For ICA cards, the token comes in response from Swedbank. For Mass Transit(SL) it is populated with PAR if it comes in response from the redeemer (Visa). If not, our own token (Mastercard / Amex). |
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
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",
"payerReference": "AB1234",
"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"
}
},
"mobilepay": {
"shoplogoUrl": "https://example.com/shop-logo.png"
}
}
Required | Field | Data type | Description | |
---|---|---|---|---|
check | payment |
object |
The payment object. | |
check | └➔ operation
|
string |
Purchase |
|
check | └➔ intent
|
string |
Authorization |
|
check | └➔ currency
|
string |
NOK , SEK , DKK , USD or EUR . |
|
check | └➔ prices
|
object |
The prices object. | |
check | └─➔ type
|
string |
Visa (for card type Visa), MC (for card type Mastercard), MobilePay (for all card types). |
|
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 DKK, 5000 = 50.00 DKK. |
|
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 DKK, 5000 = 50.00 DKK. 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. |
|
└─➔ feeAmount
|
integer |
If the amount given includes Fee, this may be displayed for the user in the payment page (redirect only). | ||
check | └➔ description
|
string(40) |
A 40 character length textual description of the purchase. | |
└➔ payerReference
|
string |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. | ||
check | └➔ userAgent
|
string |
The User-Agent string of the payer’s web browser. |
|
check | └➔ language
|
string |
da-DK , fi-FI or en-US . |
|
check | └➔ urls
|
object |
The URLs object containing the urls used for this payment. | |
check | └─➔ completeUrl
|
string |
The URI that Swedbank Pay will redirect back to when the payment page is completed. This does not indicate a successful payment, only that it has reached a completion state. A GET request needs to be performed on the payment to inspect it further. See completeUrl for details. |
|
check | └─➔ cancelUrl
|
string |
The URI that Swedbank Pay will redirect back to when the user presses the cancel button in the payment page. | |
└─➔ callbackUrl
|
string |
The URI that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment. See callback for details. |
||
check | └➔ payeeInfo
|
object |
The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details. |
|
check | └─➔ payeeId
|
string |
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay. | |
check | └─➔ payeeReference
|
string(50) |
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. |
|
└─➔ payeeName
|
string |
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay. | ||
└─➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. | ||
└─➔ orderReference
|
String(50) |
The order reference should reflect the order reference found in the merchant’s systems. | ||
└─➔ subsite
|
String(40) |
The subsite field can be used to perform split settlement on the payment. Thesubsite s must be resolved with Swedbank Pay reconciliation before being used.If you send in an unknown subsite value, it will be ignored and the paymentwill be settled using the merchant’s default settlement account. |
||
check | └➔ mobilepay.shoplogoUrl
|
string |
URI to logo that will be visible at MobilePay Online. For it to display correctly in the MobilePay app, the image must be 250x250 pixels, a png or jpg served over a secure connection using https, and publicly available |
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
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",
"payerReference": "AB1234",
"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"
}
},
"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"
}
]
}
Field | Data type | Description |
---|---|---|
payment |
object |
The payment object contains information about the retrieved payment. |
└➔ id
|
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ number
|
integer |
The payment number , useful when there’s need to reference the payment in human communication. Not usable for programmatic identification of the payment, for that id should be used instead. |
└➔ created
|
string |
The ISO-8601 date of when the payment was created. |
└➔ updated
|
string |
The ISO-8601 date of when the payment was updated. |
└➔ instrument
|
string |
The instrument used |
└➔ operation
|
string |
Purchase |
└➔ intent
|
string |
The intent sent in on request |
└➔ state
|
string |
Ready , Pending , Failed or Aborted . Indicates the state of the payment. This field is only for status display purposes. |
└➔ currency
|
string |
The currency used |
└➔ description
|
string(40) |
A 40 character length textual description of the purchase. |
└➔ payerReference
|
string |
The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. |
└➔ initiatingSystemUserAgent
|
string |
The system user agent used |
└➔ userAgent
|
string |
The user agent string of the payer’s browser. |
└➔ language
|
string |
da-DK , fi-FI or en-US . |
└➔ urls
|
string |
The URI to the urls resource where all URIs related to the payment can be retrieved. |
└➔ payeeInfo
|
string |
The URI to the payeeinfo resource where the information about the payee of the payment can be retrieved. |
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"
},
]
}
Field | Description |
---|---|
href |
The target URI to perform the operation against. |
rel |
The name of the relation the operation has to the current resource. |
method |
The HTTP method to use when performing the operation. |
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 | Description |
---|---|
update-payment-abort |
Aborts the payment before any financial transactions are performed. |
create-authorization |
Create an authorization transaction. |
redirect-authorization |
Used to redirect the payer to the MobilePay Online authorization UI. |
create-capture |
Creates a capture transaction. |
create-cancellation |
Creates a cancellation transaction. |
create-reversal |
Creates a reversal transaction. |
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"
}
]
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this authorizations belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
authorizations |
object |
The current authorizations resource. |
└➔ id
|
string |
The relative URI and unique identifier of the authorizations resource this authorizations belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ authorizationList
|
array |
The array of authorization transaction objects. |
└➔ authorizationList[]
|
object |
The authorization transaction object described in the authorization resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this authorizations belongs to.. Please read about URI Usage to understand how this and other URIs 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. |
└─➔ 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. |
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": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this captures belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
captures |
object |
The current captures resource. |
└➔ id
|
string |
The relative URI and unique identifier of the captures resource this captures belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ captureList
|
array |
The array of capture transaction objects. |
└➔ captureList[]
|
object |
The capture transaction object described in the capture resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this captures belongs to.. Please read about URI Usage to understand how this and other URIs 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 capture 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. |
└─➔ 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. |
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"
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The currenct capture object. |
check | └➔ amount
|
integer |
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. |
check | └➔ vatAmount
|
integer |
The payment’s VAT (Value Added Tax) amount , entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount . This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged. |
check | └➔ description
|
string |
A textual description of the capture transaction. |
check | └➔ payeeReference
|
string(50) |
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. |
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"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
capture |
string |
The current capture transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the capture resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this capture belongs to.. Please read about URI Usage to understand how this and other URIs 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 capture 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. |
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": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this cancellations belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
cancellations |
object |
The current cancellations resource. |
└➔ id
|
string |
The relative URI and unique identifier of the cancellations resource this cancellations belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ cancellationList
|
array |
The array of cancellation transaction objects. |
└➔ cancellationList[]
|
object |
The cancellation transaction object described in the cancellation resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this cancellations belongs to.. Please read about URI Usage to understand how this and other URIs 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 cancellation 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. |
└─➔ 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. |
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"
}
}
Required | Field | Type | Description |
---|---|---|---|
check | transaction |
object |
The current cancellation. |
check | └➔ description
|
string |
A textual description of the reason for the cancellation. |
check | └➔ payeeReference
|
string(50) |
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. |
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"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this cancellation belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
cancellation |
string |
The current cancellation transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the cancellation resource this cancellation belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this cancellation belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this cancellation belongs to.. Please read about URI Usage to understand how this and other URIs 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 cancellation 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. |
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": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this reversals belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
reversals |
object |
The current reversals resource. |
└➔ id
|
string |
The relative URI and unique identifier of the reversals resource this reversals belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ reversalList
|
array |
The array of reversal transaction objects. |
└➔ reversalList[]
|
object |
The reversal transaction object described in the reversal resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this reversals belongs to.. Please read about URI Usage to understand how this and other URIs 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 reversal 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. |
└─➔ 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. |
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"
}
}
Required | Field | Type | Description |
---|---|---|---|
check︎ | transaction |
object |
The current reversal transaction object |
check︎ | └➔ amount
|
integer |
The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. |
check︎ | └➔ vatAmount
|
integer |
The payment’s VAT (Value Added Tax) amount , entered in the lowest monetary unit of the selected currency. E.g.: 10000 = 100.00 SEK, 5000 = 50.00 SEK. The vatAmount entered will not affect the amount shown on the payment page, which only shows the total amount . This field is used to specify how much of the total amount the VAT will be. Set to 0 (zero) if there is no VAT amount charged. |
check︎ | └➔ description
|
string |
A textual description of the capture |
check︎ | └➔ payeeReference
|
string(50) |
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. |
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"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this reversal belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
reversal |
string |
The current reversal transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the reversal resource this reversal belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this reversal belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this reversal belongs to.. Please read about URI Usage to understand how this and other URIs 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 reversal 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. |
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
Reconciliation is an important step in an economic transaction. When a payment is reconciled, captured amounts for the payment are matched against the corresponding settlement.
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 Transfered
amount
- 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
Field | Type | Description |
---|---|---|
Prefix |
String |
The Prefix used for transactions, only eligible if merchant uses prefix. |
Currency | ISO 4217 |
Settlement currency (e.g. SEK, NOK, EUR ). |
ServiceType |
String |
The service type of the service used (e.g. Creditcard ). |
Service |
String |
The service used (e.g. Creditcard ). |
NoOfDebet |
Decimal |
Total number of debit transactions for the given service. |
NoOfCredit |
Decimal |
Total number of credit transactions for the given service. |
Amount |
Decimal |
Total amount for the given service (e.g 100.00). |
FromDate |
ISO 8601 |
The earlistest transaction date, YYYY-MM-DD . |
ToDate |
ISO 8601 |
The latest transaction date, YYYY-MM-DD . |
Body fields
Field | Type | Description |
---|---|---|
Swedbank Pay Batch Number |
Decimal |
A batch number common to all types of transactions processed by Swedbank Pay. |
Transaction Number |
Decimal |
A unique identifier of the transaction, can be traced in Swedbank Pay Admin user interface. |
Order id |
String |
A unique identifier of the order, as sent from the merchant to Swedbank Pay. Transactions that are related to the same order are associated with this ID. |
Date Created |
ISO 8601 |
Transaction capture date/time. YYYY-MM-DD hh:mm:ss. |
Date Modified |
ISO 8601 |
Transaction settle date/time. YYYY-MM-DD hh:mm:ss. |
Provider |
String |
The service provider (e.g. Babs, Swedbank). |
Type |
String |
The service type of the related transaction (e.g. Creditcard ). |
Amount |
Decimal |
Total amount of the related transaction (e.g 100.00). |
Currency |
ISO 4217 |
Settlement currency (e.g. SEK, NOK, EUR ). |
Product Number |
String |
A product number, as sent by merchant to Swedbank Pay. |
Description |
String |
A textual description of the transaction, as sent by merchant to Swedbank Pay. |
VAT Amount |
Decimal |
VAT Amount for the given transaction (e.g 100.00). |
VAT Percentage |
Decimal |
VAT Percentage for the given transaction. |
Credit Card Batch Number |
Decimal |
The reference number from the credit card processor. |
Reference |
Decimal |
The transaction reference from processor. |
Swedbank Pay Account Number |
Decimal |
The Account number given, shown in Swedbank Pay admin. |
Referenced Transaction Number |
Decimal |
Transaction number for the Authoriation transaction for a two-stage transaction or the number of the debit transaction if it is a credit transaction. |
Sales Channel |
String |
The channel through which the transaction was sent to Swedbank Pay (e.g Transaction via eCommerce APIs). |
Brand |
String |
If eligible, Branding information as sent by merchant to Swedbank Pay. |
Point Of Sale |
String |
If eligible, POS information as sent by merchant to Swedbank Pay. |
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:
- You can use information generated by your system (you will have to set a unique payeeReference when you make the transaction), or
- 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 toOrderId
in the reconciliation file. -
capture.transaction.number
returned from Swedbank Pay is equal toTransactionNo
in reconciliation file.
Below you will see the API mapping tables to the fields in the settlement
report for Capture
and Reversal
.
Capture
API | XLSX | XML | |
---|---|---|---|
Swedbank Pay Batch Number |
SwedbankbatchNo |
||
transaction.number |
Transaction Number |
TransactionNo |
|
transaction.payeeReference |
Order id |
OrderId |
|
transaction.created |
Date Created |
DateCreated |
|
Date Modified |
DateModified |
||
Provider |
Provider |
||
Type |
Type |
||
transaction.amount |
Amount |
Amount |
|
Currency |
Currency |
||
Product Number |
MerchantProductNo |
||
Description |
Description |
||
transaction.vatAmount |
VAT Amount |
VATAmount |
|
VAT Percentage |
VatoPercentage |
||
Credit Card Batch Number |
CreditCardBatchNo |
||
Direct Debit Bank Reference |
DirectDebitbankRef |
||
Reference |
Reference |
||
Swedbank Account Number |
SwedbankAccountNo |
||
transaction.number if reversed later |
Referenced Transaction Number |
ReferencedTransaction |
|
Sales Channel |
SalesChannel |
||
Brand |
|||
Point Of Sale |
Reversal
API | XLSX | XML | |
---|---|---|---|
Swedbank Pay Batch Number |
SwedbankbatchNo |
||
transaction.number |
Transaction Number |
TransactionNo |
|
transaction.payeeReference |
Order id |
OrderId |
|
transaction.created |
Date Created |
DateCreated |
|
Date Modified |
DateModified |
||
Provider |
Provider |
||
Type |
Type |
||
transaction.amount |
Amount |
Amount |
|
Currency |
Currency |
||
Product Number |
MerchantProductNo |
||
Description |
Description |
||
transaction.vatAmount |
VAT Amount |
VATAmount |
|
VAT Percentage |
VatoPercentage |
||
Credit Card Batch Number |
CreditCardBatchNo |
||
Direct Debit Bank Reference |
DirectDebitbankRef |
||
Reference |
Reference |
||
Swedbank Account Number |
SwedbankAccountNo |
||
Referenced Transaction Number |
ReferencedTransaction |
||
Sales Channel |
SalesChannel |
||
Brand |
|||
Point Of Sale |
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
Split Settlement
The prefix split is the easy way of doing settlements for companies with multiple sub merchants. With only a few easy steps, you can make the settlement process 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 prefix numbers to sub merchants selling their goods or services through the company. The prefix number is used to match the transactions and the merchant, so the settlement is automatically split between the sub merchants. If you run a site selling tickets to concerts, theatres, sporting events etc., each venue gets its own prefix number. If you run a funeral home, the sub merchants can be everything from flower delivery to charities.
What we need from you as a company
- Send us a KYC 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 at your website or in your app a unique prefix number. This needs to be included in the KYC form you send to us. We recommend using the same customer number they have in your system.
- Attach the prefix 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 the automatic deduction of revenue cuts and fees.
How it works
- We set up the sub merchant prefix in our systems.
- The prefix number is added in the subsite field in the API call when you create the payment for the goods or service.
- The customer selects payment instrument and completes the payment.
- The payment goes into the client funds account.
- Swedbank Pay matches the transaction and the merchant using the prefix number.
- The settlement is split and connected to the correct merchant.
- Revenue cuts for the super merchant and fees from Swedbank Pay are deducted automatically.
- Payout to the sub merchant is done.
The upsides
- Since the sub merchants are connected to Swedbank Pay through the super merchant instead of having separate setups, this means that you:
- Only need one agreement for credit card, Vipps, Swish, MobilePay Online, invoice and payment gateway.
- Only need one acquiring agreement.
- Only need one Vipps/Swish certificate.
- Can add more payment instruments easily, as it only has to be done once.
- Can set up new sub merchants quickly, as the only thing needed is a KYC form and a prefix 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 prefix split is available with 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 prefix. 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.
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 sending information in e-mail/SMS, it is strongly recommended that you add information about your terms and conditions, including purchase information and price. See recommendations in the next section.
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.
Please note that the the callback may come either before, after or in the same moment as the payer is redirected to the status page at the merchant site when the purchase is fulfilled. Don’t rely on the callback being timed at any specific moment.
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 theCapture
andCancel
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 thePOST
request. IfcallbackURL
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.
Notice that for Redirect,
the description will be shown as Test - Reference1583419461
, as set
in the code example. For the Seamless View scenario, the description is not
shown in the payment window, but it is still required in the initial request.
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:
- If the payer closes the payment window, the merchant will never know what
happened to the payment if
callbackUrl
is not implemented. - 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. - 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 thecallbackUrl
that was specified when the payee (merchant) created the payment. - When the
callbackUrl
receives such a callback, an HTTPGET
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. - The callback will be retried if it fails. Below are the retry timings, in
seconds from the initial transaction time:
- 30 seconds
- 60 seconds
- 360 seconds
- 432 seconds
- 864 seconds
- 1265 seconds
- The callback is sent from the following IP address:
82.115.146.1
- 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"
}
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
authorization |
string |
The current authorization transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the authorization resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this authorization belongs to.. Please read about URI Usage to understand how this and other URIs 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 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": []
}
}]
}
}
Field | Type | Required |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
transactions |
object |
The current transactions resource. |
└➔ id
|
string |
The relative URI and unique identifier of the transactions resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ transactionList
|
array |
The array of transaction transaction objects. |
└➔ transactionList[]
|
object |
The transaction transaction object described in the transaction resource below. |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transactions belongs to.. Please read about URI Usage to understand how this and other URIs 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 transaction 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. |
└─➔ 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. |
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 statefailed
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": [
]
}
}
}
Field | Type | Description | |
---|---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
transaction |
string |
The current transaction transaction resource. |
|
└➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ itemDescriptions
|
object |
The object representation of the itemDescriptions resource. |
|
└─➔ id
|
string |
The relative URI and unique identifier of the itemDescriptions resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
|
└➔ transaction
|
object |
The object representation of the generic transaction resource. | |
└─➔ id
|
string |
The relative URI and unique identifier of the transaction resource this transaction belongs to.. Please read about URI Usage to understand how this and other URIs 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 transaction 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. |
Prices
The prices
resource lists the prices related to a specific payment.
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
}
]
}
}
Field | Type | Description |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
prices |
object |
The prices resource. |
└➔ id
|
string |
The relative URI and unique identifier of the prices resource this prices belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ priceList
|
array |
The array of price objects. Note: Even if you specifiy CreditCard in the input message the system will return all your configured card brands instead when you expan the priceList. |
└─➔ type
|
string |
The type of the price object. |
└─➔ 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. |
Prices Object Types
Each payment instrument have one or more prices object types. This is most relevant when using card based payments as each type correspond to a card brand or bank respectively.
MobilePay Online Payments
Type | Description |
---|---|
Mobilepay |
Always MobilePay |
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
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",
"payerReference": "AB1234",
"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",
},
"metadata": {
"key1": "value1",
"key2": 2,
"key3": 3.1,
"key4": false
},
"prefillInfo": {
"msisdn": "+4798765432"
}
}
}
Parameter | Type |
---|---|
metadata |
string , boolean , integer ,decimal
|
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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"metadata": {
"id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/metadata",
"key1": "value1",
"key2": 2,
"key3": 3.1,
"key4": false
}
}
PayeeInfo
The payeeinfo
resource contains information about the payee (i.e. a merchant,
a corporation etc) related to a specific payment.
Request
1
2
3
4
GET /psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo 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
HTTP/1.1 200 OK
Content-Type: application/json
{
"payment": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
"payeeInfo": {
"id": "/psp/mobilepay/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo",
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "EN1234",
"payeeName": "TestMerchant1",
"productCategory": "EF1234",
"orderReference": "or-123456"
}
}
Field | Type | Description |
---|---|---|
payment |
string |
The relative URI and unique identifier of the payment resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ id
|
string |
The relative URI and unique identifier of the payeeInfo resource this payeeInfo belongs to.. Please read about URI Usage to understand how this and other URIs should be used in your solution. |
└➔ payeeId
|
string |
This is the unique id that identifies this payee (like merchant) set by Swedbank Pay |
└➔ payeeReference
|
string(50) |
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. |
└➔ payeeName
|
string |
The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay. |
└➔ productCategory
|
string |
A product category or number sent in from the payee/merchant. This is not validated by Swedbank Pay, but will be passed through the payment process and may be used in the settlement process. You therefore need to ensure that the value given here is valid in the settlement. |
└➔ orderReference
|
string(50) |
The order reference should reflect the order reference found in the merchant’s systems. |
Payee Reference
The payeeReference
given when creating transactions and payments has some
specific processing rules depending on specifications in the contract.
- It must be unique for every operation, used to ensure exactly-once delivery of a transactional operation from the merchant system.
- Its length and content validation is dependent on whether the
transaction.number
or thepayeeReference
is sent to the acquirer.- If you select Option A in the settlement process (Swedbank Pay will
handle the settlement), Swedbank Pay will send the
transaction.number
to the acquirer and thepayeeReference
must be in the format of charactersA-Za-z0-9
(including-
) andstring(30)
. - If you select Option B in the settlement process (you will handle the
settlement yourself), Swedbank Pay will send the
payeeReference
to the acquirer and it will be limited to the format ofstring(12)
and all characters must be digits.
- If you select Option A in the settlement process (Swedbank Pay will
handle the settlement), Swedbank Pay will send the
Problems
When performing operations against a resource in the Swedbank Pay API Platform, it will respond with a problem message that contain details of the error type if the request could not be successfully performed. Regardless of why the error occurred, the problem message will follow the same structure as specified in the Problem Details for HTTP APIs (RFC 7807) specification.
We generally use the problem message type
and status
code to identify the
nature of the problem. The problems
array contains objects with name
and
description
that will often help narrow down the specifics of the problem,
usually to the field in the request that was missing or contained invalid data.
The structure of a problem message will look like this:
Problem Example
1
2
3
4
5
6
7
8
9
10
11
12
{
"type": "https://api.payex.com/psp/errordetail/<resource>/inputerror",
"title": "There was an input error",
"detail": "Please correct the errors and retry the request",
"instance": "ec2a9b09-601a-42ae-8e33-a5737e1cf177",
"status": 400,
"action": "RetryNewData",
"problems": [{
"name": "CreditCardParameters.Issuer",
"description": "minimum one issuer must be enabled"
}]
}
Field | Type | Description |
---|---|---|
type |
string |
The URI that identifies the error type. This is the only field usable for programmatic identification of the type of error! When dereferenced, it might lead you to a human readable description of the error and how it can be recovered from. |
title |
string |
The title contains a human readable description of the error. |
detail |
string |
A detailed, human readable description of the error and how you can recover from it. |
instance |
string |
The identifier of the error instance. This might be of use to Swedbank Pay support personnel in order to find the exact error and the context it occurred in. |
status |
integer |
The HTTP status code that the problem was served with. |
action |
string |
The action indicates how the error can be recovered from. |
problems |
array |
The array of problem detail objects. |
└➔ name
|
string |
The name of the field, header, object, entity or likewise that was erroneous. |
└➔ description
|
string |
The human readable description of what was wrong with the field, header, object, entity or likewise identified by name . |
Common Problems
All common problem types will have a URI in the format
https://api.payex.com/psp/errordetail/<error-type>
. The URI is an
identifier that you can hard-code and implement logic around. It is currently
not not possible to dereference this URI, although that might be possible in the
future.
Type | Status | Description |
---|---|---|
inputerror |
400 |
The server cannot or will not process the request due to an apparent client error (e.g. malformed request syntax, size to large, invalid request). |
forbidden |
403 |
The request was valid, but the server is refusing the action. The necessary permissions to access the resource might be lacking. |
notfound |
404 |
The requested resource could not be found, but may be available in the future. Subsequent requests are permissible. |
systemerror |
500 |
A generic error message. |
configurationerror |
500 |
A error relating to configuration issues. |