Card – Unscheduled Purchase

Unscheduled Purchase

This feature is only available for merchants who have a specific agreement with Swedbank Pay.

An unscheduled purchase, also called a Merchant Initiated Transaction (MIT), is a payment which uses a paymentToken generated through a previous payment in order to charge the same card at a later time. They are done by the merchant without the cardholder being present.

Unscheduled purchases can be used in cases where you have an agreement with your customer which handles both recurring orders and/or singular transactions. Observe - it’s important that the Terms of Service clearly and understandably states how the payment will be done towards your customer. Example use cases are car rental companies charging the payer’s card for toll road expenses after the rental period, or different subscription services and recurring orders where the periodicity and/or amount varies.

Please note that you need to do a capture after sending the unscheduled request. We have added a capture section at the end of this page for that reason.

Generating The Token

First, you need an initial transaction where the unscheduledToken is generated and connected. You do that by adding the field generateUnscheduledToken in the request and set the value to true. The payer must complete the purchase to activate the token. You can also use Verify to activate tokens.

(Read more about deleting the unscheduled token here.)

Initial Request

The initial request should look like this:

Request

1
2
3

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [{
                "type": "CreditCard",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase", 
        "generatePaymentToken": true, 
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.pdf",
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or123",
            "subsite": "mySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "cardholder": {
            "firstName": "Olivia",
            "lastName": "Nyhuus",
            "email": "olivia.nyhuus@payex.com",
            "msisdn": "+4798765432",
            "homePhoneNumber": "+4787654321",
            "workPhoneNumber": "+4776543210",
            "shippingAddress": {
                "firstName": "Olivia",
                "lastName": "Nyhuus",
                "email": "olivia.nyhuus@payex.com",
                "msisdn": "+4798765432",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }, 
        },
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhuus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}

Show fields

Required	Field	Type	Description
	`payment`	`object`	The payment object
	`operation`	`string`	Determines the initial operation, defining the type of payment order created.
	`intent`	`string`	`Authorization`. Reserves the amount, and is followed by a `Cancel` or `Capture` of funds. `AutoCapture`. A one phase option that enables the `Capture` of funds automatically after authorization.
	`currency`	`string`	NOK, SEK, DKK, USD or EUR.
	`prices`	`array`	The `prices` resource lists the prices related to a specific payment.
	`type`	`string`	Use the value ``.See the `prices` resource for more information.
	`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(40)`	A 40 character length textual description of the purchase.
	`generatePaymentToken`	`boolean`	`true` or `false`. Set to `true` if you want to generate a `paymentToken` for future unscheduled purchases (Merchant Initiated Transactions).
	`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
	`language`	`string`	`sv-SE`, `nb-NO`, `da-DK`, `de-DE`, `ee-EE`, `en-US`, `es-ES`, `fr-FR`, `lv-LV`, `lt-LT`, `ru-RU` or `fi-FI`.
︎	`urls`	`object`	The object containing URLs relevant for the `payment`.
	`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
	`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with `paymentUrl`; only `cancelUrl` or `paymentUrl` can be used, not both.
	`paymentUrl`	`string`	The `paymentUrl` represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used.
	`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment. See callback for details.
	`logoUrl`	`string`	The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
	`termsOfServiceUrl`	`string`	The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.
	`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
	`payeeId`	`string`	This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
	`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
	`payeeName`	`string`	The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
	`productCategory`	`string(50)`	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 a split settlement on the payment. The different `subsite` values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown `subsite` value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of `A-Za-z0-9`.
	`payer`	`string`	The `payer` object, containing information about the payer.
	`payerReference`	`string`	The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if `generateRecurrenceToken`, `RecurrenceToken`, `generatePaymentToken` or `paymentToken` is `true`.
	`metadata`	`object`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
	`cardholder`	`object`	Optional. Cardholder object that can hold information about a buyer (private or company). The information added increases the chance for frictionless flow and is related to 3-D Secure 2.0..
	`firstName`	`string`	Optional (increased chance for frictionless flow if set). If buyer is a company, use only `firstName`.
	`lastName`	`string`	Optional (increased chance for frictionless flow if set). If buyer is a company, use only `firstName`.
	`email`	`string`	Optional (increased chance for frictionless flow if set)
	`msisdn`	`string`	Optional (increased chance for frictionless flow if set)
	`homePhoneNumber`	`string`	Optional (increased chance for frictionless flow if set)
	`workPhoneNumber`	`string`	Optional (increased chance for frictionless flow if set)
	`shippingAddress`	`object`	Optional (increased chance for frictionless flow if set)
	`firstName`	`string`	Optional (increased chance for frictionless flow if set)
	`lastName`	`string`	Optional (increased chance for frictionless flow if set)
	`email`	`string`	Optional (increased chance for frictionless flow if set)
	`msisdn`	`string`	Optional (increased chance for frictionless flow if set)
	`streetAddress`	`string`	Optional (increased chance for frictionless flow if set)
	`coAddress`	`string`	Optional (increased chance for frictionless flow if set)
	`city`	`string`	Optional (increased chance for frictionless flow if set)
	`zipCode`	`string`	Optional (increased chance for frictionless flow if set)
	`countryCode`	`string`	Optional (increased chance for frictionless flow if set)
	`billingAddress`	`object`	Optional (increased chance for frictionless flow if set)
	`firstName`	`string`	Optional (increased chance for frictionless flow if set). If buyer is a company, use only `firstName`.
	`lastName`	`string`	Optional (increased chance for frictionless flow if set). If buyer is a company, use only `firstName`.
	`email`	`string`	Optional (increased chance for frictionless flow if set)
	`msisdn`	`string`	Optional (increased chance for frictionless flow if set)
	`streetAddress`	`string`	Optional (increased chance for frictionless flow if set)
	`coAddress`	`string`	Optional (increased chance for frictionless flow if set)
	`city`	`string`	Optional (increased chance for frictionless flow if set)
	`zipCode`	`string`	Optional (increased chance for frictionless flow if set)
	`countryCode`	`string`	Optional (increased chance for frictionless flow if set)
	`riskIndicator`	`array`	This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelihood of having to prompt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase.
	`deliveryEmailAdress`	`string`	For electronic delivery, the email address to which the merchandise was delivered. Providing this field when appropriate decreases the likelihood of a 3-D Secure authentication for the payer.
	`deliveryTimeFrameIndicator`	`string`	Indicates the merchandise delivery timeframe. `01` (Electronic Delivery) `02` (Same day shipping) `03` (Overnight shipping) `04` (Two-day or more shipping)
	`preOrderDate`	`string`	For a pre-ordered purchase. The expected date that the merchandise will be available. Format: `YYYYMMDD`
	`preOrderPurchaseIndicator`	`string`	Indicates whether the payer is placing an order for merchandise with a future availability or release date. `01` (Merchandise available) `02` (Future availability)
	`shipIndicator`	`string`	Indicates shipping method chosen for the transaction. `01` (Ship to cardholder’s billing address) `02` (Ship to another verified address on file with merchant) `03` (Ship to address that is different than cardholder’s billing address) `04` (Ship to Store / Pick-up at local store. Store address shall be populated in shipping address fields) `05` (Digital goods, includes online services, electronic giftcards and redemption codes) `06` (Travel and Event tickets, not shipped) `07` (Other, e.g. gaming, digital service)
	`giftCardPurchase`	`bool`	`true` if this is a purchase of a gift card.
	`reOrderPurchaseIndicator`	`string`	Indicates whether the cardholder is reordering previously purchased merchandise. `01` (First time ordered) `02` (Reordered).
	`pickUpAddress`	`object`	If `shipIndicator` set to `04`, then prefill this with the payers `pickUpAddress` of the purchase to decrease the risk factor of the purchase.
	`name`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `name` of the purchase to decrease the risk factor of the purchase.
	`streetAddress`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `streetAddress` of the purchase to decrease the risk factor of the purchase. Maximum 50 characters long.
	`coAddress`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `coAddress` of the purchase to decrease the risk factor of the purchase.
	`city`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `city` of the purchase to decrease the risk factor of the purchase.
	`zipCode`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `zipCode` of the purchase to decrease the risk factor of the purchase.
	`countryCode`	`string`	If `shipIndicator` set to `04`, then prefill this with the payers `countryCode` of the purchase to decrease the risk factor of the purchase.

Initial Response

Response

1
2

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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64

{
    "payment": {
        "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "number": 1234567890,
        "instrument": "CreditCard",
        "created": "2016-09-14T13:21:29.3182115Z",
        "updated": "2016-09-14T13:21:57.6627579Z",
        "state": "Ready",
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "amount": 0,
        "remainingCaptureAmount": 1500,
        "remainingCancellationAmount": 1500,
        "remainingReversalAmount": 0,
        "description": "Test Purchase",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE", 
        "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1", 
        "prices": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
        "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
        "authorizations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
        "captures": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
        "reversals": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
        "cancellations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
        "urls": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
        "payeeInfo": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
        "payers": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" },
        "settings": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/settings" }
    },
    "operations": [
        {
            "rel": "update-payment-abort",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
            "method": "PATCH",
            "contentType": "application/json"
        },
        {
            "rel": "redirect-authorization",
            "href": "https://ecom.externalintegration.payex.com/creditcard/payments/authorize/5a17c24e-d459-4567-bbad-aa0f17a76119",
            "method": "GET",
            "contentType": "text/html"
        },
        {
            "rel": "view-authorization",
            "href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "method": "GET",
            "contentType": "application/javascript"
        },
        {
            "rel": "view-payment",
            "href": "https://ecom.externalintegration.payex.com/creditcard/core/scripts/client/px.creditcard.client.js?token=5a17c24e-d459-4567-bbad-aa0f17a76119",
            "method": "GET",
            "contentType": "application/javascript"
        },
        {
            "rel": "direct-authorization",
            "href": "https://api.externalintegration.payex.com/psp/creditcard/confined/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations",
            "method": "POST",
            "contentType": "application/json"
        }
    ]
}

Show fields

Field	Type	Description
`payment`	`object`	The `payment` object contains information about the specific payment.
`id`	`string`	The relative URL and unique identifier of the `payment` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`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, where `id` should be used instead.
`instrument`	`string`	The payment method used in the payment.
`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`.
`operation`	`string`	`Purchase`
`intent`	`string`	`Authorization`
`currency`	`string`	NOK, SEK, DKK, USD or EUR.
`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.
`remainingCaptureAmount`	`integer`	The available amount to capture.
`remainingCancelAmount`	`integer`	The available amount to cancel.
`remainingReversalAmount`	`integer`	The available amount to reverse.
`description`	`string(40)`	A 40 character length textual description of the purchase.
`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
`language`	`string`	`sv-SE`, `nb-NO`, `da-DK`, `de-DE`, `ee-EE`, `en-US`, `es-ES`, `fr-FR`, `lv-LV`, `lt-LT`, `ru-RU` or `fi-FI`.
`paymentToken`	`string`	The generated payment token, if `operation: Verify`, `operation: UnscheduledPurchase` or `generatePaymentToken: true` was used.
`prices`	`id`	The URL to the `prices` resource where all URLs related to the payment can be retrieved.
`transactions`	`id`	The URL to the `transactions` resource where the information about the payer can be retrieved.
`authorizations`	`id`	The URL to the `authorizations` resource where the information about the payer can be retrieved.
`captures`	`id`	The URL to the `captures` resource where the information about the payer can be retrieved.
`reversals`	`id`	The URL to the `reversals` resource where the information about the payer can be retrieved.
`cancellations`	`id`	The URL to the `cancellations` resource where the information about the payer can be retrieved.
`urls`	`id`	The URL to the `urls` resource where all URLs related to the payment can be retrieved.
`payeeInfo`	`id`	The URL to the `payeeInfo` resource where information related to the payee can be retrieved.
`payers`	`id`	The URL to the `payer` resource where the information about the payer can be retrieved.

`settings`	`id`	The URL to the `settings` resource where the information about the payer can be retrieved.
`operations`	`array`	The array of operations that are possible to perform on the payment in its current state.

GET The Token

You can retrieve the token by using the expand option when you GET your payment. The GET request should look like the one below, with a ?$expand=paid after the paymentOrderId. The response should match the initial payment response, but with an expanded paid field.

Request

1
2
3
4

GET /psp/creditcard/payments/09ccd29a-7c4f-4752-9396-12100cbfecce/?$expand=paid HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [{
                "type": "CreditCard",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase", 
        "generatePaymentToken": true, 
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.pdf",
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or123",
            "subsite": "mySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        },
        "cardholder": {
            "firstName": "Olivia",
            "lastName": "Nyhuus",
            "email": "olivia.nyhuus@payex.com",
            "msisdn": "+4798765432",
            "homePhoneNumber": "+4787654321",
            "workPhoneNumber": "+4776543210",
            "shippingAddress": {
                "firstName": "Olivia",
                "lastName": "Nyhuus",
                "email": "olivia.nyhuus@payex.com",
                "msisdn": "+4798765432",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }, 
        },
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhuus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}

Performing The Unscheduled Purchase

When you are ready to perform the unscheduled purchase, simply add the unscheduledToken field and use the token as the value. Your request should look like this:

Unscheduled Request

Request

1
2
3
4

POST /psp/creditcard/payments HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31

{
    "payment": {
        "operation": "UnscheduledPurchase",
        "intent": "Authorization",
        "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
        "currency": "NOK",
        "amount": 1500,
        "vatAmount": 0,
        "description": "Test Unscheduled",
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://example.com/payment-callback",
            "logoUrl": "https://example.com/payment-logo.png",
            "termsOfServiceUrl": "https://example.com/payment-terms.pdf",
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "CD1234",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-12456",
            "subsite": "MySubsite"
        },
        "payer": {
            "payerReference": "AB1234",
        }
    }
}

Show fields

Required	Field	Type	Description
	`payment`	`object`	The payment object
	`operation`	`string`	For unscheduled purchases, this needs to be `unscheduledPurchase`.
	`intent`	`string`	`Authorization`.
	`paymentToken`	`string`	The paymentToken generated in the initial purchase, if `operation: Verify` or `generatePaymentToken: true` was used.
	`currency`	`string`	NOK, SEK, DKK, USD or EUR.
	`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(40)`	A 40 character length textual description of the purchase.
	`userAgent`	`string`	The user agent of the payer. Should typically be set to the value of the `User-Agent` header sent by the payer’s web browser.
	`language`	`string`	`sv-SE`, `nb-NO`, `da-DK`, `de-DE`, `ee-EE`, `en-US`, `es-ES`, `fr-FR`, `lv-LV`, `lt-LT`, `ru-RU` or `fi-FI`.
︎	`urls`	`object`	The object containing URLs relevant for the `payment`.
	`completeUrl`	`string`	The URL that Swedbank Pay will redirect back to when the payer has completed their interactions with the payment. This does not indicate a successful payment, only that it has reached a final (complete) state. A `GET` request needs to be performed on the payment to inspect it further. See `completeUrl` for details.
	`cancelUrl`	`string`	The URL to redirect the payer to if the payment is cancelled. Only used in redirect scenarios. Can not be used simultaneously with `paymentUrl`; only `cancelUrl` or `paymentUrl` can be used, not both.
	`paymentUrl`	`string`	The `paymentUrl` represents the URL that Swedbank Pay will redirect back to when the view-operation needs to be loaded, to inspect and act on the current status of the payment, such as when the payer is redirected out of the Seamless View (the `<iframe>`) and sent back after completing the payment. `paymentUrl` is only used in Seamless Views and should point to the page of where the Payment Order Seamless View is hosted. If both `cancelUrl` and `paymentUrl` is sent, the `paymentUrl` will used.
	`callbackUrl`	`string`	The URL that Swedbank Pay will perform an HTTP `POST` against every time a transaction is created on the payment. See callback for details.
	`logoUrl`	`string`	The URL that will be used for showing the customer logo. Must be a picture with maximum 50px height and 400px width. Requires HTTPS.
	`termsOfServiceUrl`	`string`	The URL to the terms of service document which the payer must accept in order to complete the payment. HTTPS is a requirement.
	`payeeInfo`	`object`	The `payeeInfo` object, containing information about the payee (the recipient of the money). See `payeeInfo` for details.
	`payeeId`	`string`	This is the unique id that identifies this payee (like merchant) set by Swedbank Pay.
	`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
	`payeeName`	`string`	The payee name (like merchant name) that will be displayed when redirected to Swedbank Pay.
	`productCategory`	`string(50)`	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 a split settlement on the payment. The different `subsite` values must be resolved with Swedbank Pay reconciliation before being used. If you send in an unknown `subsite` value, it will be ignored and the payment will be settled using the merchant’s default settlement account. Must be in the format of `A-Za-z0-9`.
	`payer`	`string`	The `payer` object, containing information about the payer.
	`payerReference`	`string`	The reference to the payer from the merchant system, like e-mail address, mobile number, customer number etc. Mandatory if `generateRecurrenceToken`, `RecurrenceToken`, `generatePaymentToken` or `paymentToken` is `true`.

Unscheduled Response

Response

1
2

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

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

{
  "payment": {
    "id": "/psp/creditcard/payments/5adc265f-f87f-4313-577e-08d3dca1a26c",
    "number": 1234567890,
    "created": "2016-09-14T13:21:29.3182115Z",
    "updated": "2016-09-14T13:21:57.6627579Z",
    "state": "Ready",
    "operation": "Purchase",
    "intent": "Authorization",
    "currency": "NOK",
    "amount": 1500,
    "remainingCaptureAmount": 1500,
    "remainingCancellationAmount": 1500,
    "remainingReversalAmount": 0,
    "description": "Test Unscheduled",
    "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
    "userAgent": "Mozilla/5.0...",
    "language": "nb-NO",
    "paymentToken": "7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "prices": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/prices" },
    "transactions": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/transactions" },
    "authorizations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/authorizations" },
    "captures": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/captures" },
    "reversals": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/reversals" },
    "cancellations": { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/cancellations" },
    "urls" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/urls" },
    "payeeInfo" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payeeInfo" },
    "payers" : { "id": "/psp/creditcard/payments/7e6cdfc3-1276-44e9-9992-7cf4419750e1/payers" }
  }
}

See the table in the initial purchase response for descriptions.

Capture

The capture transaction is where you ensure that the funds are charged from the payer. This step usually takes place when the product has exchanged possession. You must first do a GET request on the payment to find the create-capture operation.

Please note that you have a maximum of 5 consecutive failed attempts at a capture. The payment will be locked after this, and you need to contact us for another attempt.

Create Capture Transaction

To create a capture transaction to withdraw money from the payer’s card, you need to perform the create-capture operation.

Capture Request

Request

1
2
3
4

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

1
2
3
4
5
6
7
8

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

Field	Type	Description
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`amount`	`integer`	Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
`vatAmount`	`integer`	Amount Entered in the lowest momentary units of the selected currency. E.g. 10000 100.00 NOK, 5000 50.00 SEK.
`description`	`string`	A textual description of the capture transaction.
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.

Capture Response

Response

1
2

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

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

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

Show fields

Property	Type	Description
`payment`	`string`	The relative URL of the payment this `capture` transaction belongs to.
`capture`	`object`	The `capture` resource contains information about the `capture` transaction made against a card payment.
`id`	`string`	The relative URL of the created `capture` transaction.
`transaction`	`object`	The object representation of the generic `transaction` resource, containing information about the current transaction.
`id`	`string`	The relative URL of the current `transaction` resource.
`created`	`string`	The ISO-8601 date and time of when the transaction was created.
`updated`	`string`	The ISO-8601 date and time of when the transaction was updated.
`type`	`string`	Indicates the transaction type.
`state`	`string`	Indicates the state of the transaction, usually `initialized`, `completed` or `failed`. If a partial has been done and further transactions are possible, the state will be `awaitingActivity`.
`number`	`integer`	The transaction `number`, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where `id` should be used instead.
`amount`	`integer`	Amount is entered in the lowest momentary units of the selected currency. E.g. 10000 = 100.00 NOK, 5000 = 50.00 SEK.
`vatAmount`	`integer`	If the amount given includes VAT, this may be displayed for the user in the payment page (redirect only). Set to 0 (zero) if this is not relevant.
`description`	`string`	A human readable description of maximum 40 characters of the transaction
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits.
`failedReason`	`string`	The human readable explanation of why the payment failed.
`isOperational`	`boolean`	`true` if the transaction is operational; otherwise `false` .
`operations`	`array`	The array of operations that are possible to perform on the transaction in its current state.

List Capture Transactions

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

Request

1
2
3
4

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

1
2
3
4
5
6
7
8

{
    "transaction": {
        "amount": 1500,
        "vatAmount": 250,
        "description": "Test Capture",
        "payeeReference": "ABC123"
    }
}

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

Transaction List Response

Response

1
2

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

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

{
    "paymentorder": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1",
    "captures": { 
        "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment",
        "captureList": [{
            "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
            "transaction": {
                "id": "/psp/paymentorders/7e6cdfc3-1276-44e9-9992-7cf4419750e1/currentpayment/ec2a9b09-601a-42ae-8e33-a5737e1cf177",
                "created": "2016-09-14T01:01:01.01Z",
                "updated": "2016-09-14T01:01:01.03Z",
                "type": "Capture",
                "state": "Completed",
                "number": 1234567890,
                "amount": 1000,
                "vatAmount": 250,
                "description": "Test transaction",
                "payeeReference": "AH123456",
                "isOperational": false,
                "operations": []
            }
        }]
    }
}

Show fields

Field	Type	Required
`paymentOrder`	`string`	The relative URL and unique identifier of the `payment` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`id`	`string`	The relative URL and unique identifier of the `captures` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`{{ transaction }}List`	`array`	The array of capture transaction objects.
`{{ transaction }}List[]`	`object`	The capture transaction object described in the `capture` resource below.
`id`	`string`	The relative URL and unique identifier of the `transaction` resource . Please read about URL Usage to understand how this and other URLs should be used in your solution.
`created`	`string`	The ISO-8601 date and time of when the transaction was created.
`updated`	`string`	The ISO-8601 date and time of when the transaction was updated.
`type`	`string`	Indicates the transaction type.
`state`	`string`	Indicates the state of the transaction, usually `initialized`, `completed` or `failed`. If a partial capture has been done and further transactions are possible, the state will be `awaitingActivity`.
`number`	`integer`	The transaction `number`, useful when there’s need to reference the transaction in human communication. Not usable for programmatic identification of the transaction, where `id` should be used instead.
`amount`	`integer`	The transaction amount (including VAT, if any) entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK.
`vatAmount`	`integer`	The payment’s VAT (Value Added Tax) `amount`, entered in the lowest monetary unit of the selected currency. E.g.: `10000` = `100.00` SEK, `5000` = `50.00` SEK. The `vatAmount` entered will not affect the `amount` shown on the payment page, which only shows the total `amount`. This field is used to specify how much of the total `amount` the VAT will be. Set to `0` (zero) if there is no VAT `amount` charged.
`description`	`string`	A 40 character length textual description of the purchase.
`payeeReference`	`string`	A unique reference from the merchant system. Set per operation to ensure an exactly-once delivery of a transactional operation. Length and content validation depends on whether the `transaction.number` or the `payeeReference` is sent to the acquirer. If Swedbank Pay handles the settlement, the `transaction.number` is sent and the `payeeReference` must be in the format of `A-Za-z0-9` and `string(50)`. If you handle the settlement, Swedbank Pay will send the `payeeReference` and it will be limited to the format of `string(12)`. All characters must be digits. In Invoice Payments `payeeReference` is used as an invoice/receipt number, if the `receiptReference` is not defined.
`isOperational`	`bool`	`true` if the transaction is operational; otherwise `false`.
`operations`	`array`	The array of operations that are possible to perform on the transaction in its current state.

Capture Sequence Diagram

Capture can only be done on an authorized transaction. It is possible to do a partial capture where you only capture a part of the authorized amount. You can do more captures on the same payment up to the total authorization amount later.

sequenceDiagram
  activate Merchant
  Merchant->>-SwedbankPay: POST [ captures]
  activate SwedbankPay
  SwedbankPay-->>-Merchant: transaction resource