Payments Only

Purchase

schedule 8 min read

The bread and butter of the payments.

Edit "Purchase" on GitHub

Payment Order Request

Request

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "paymentorder": {
        "operation": "Purchase",
        "currency": "SEK",
        "amount": 1500,
        "vatAmount": 375,
        "description": "Test Purchase",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "productName": "Checkout3",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-cancelled",
            "callbackUrl": "https://api.example.com/payment-callback",
            "termsOfServiceUrl": "https://example.com/termsandconditoons.pdf"
        },
        "payeeInfo": {
            "payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
            "payeeReference": "AB832",
            "payeeName": "Merchant1",
            "productCategory": "A123",
            "orderReference": "or-123456",
            "subsite": "MySubsite"
        },
        "payer": {
            "digitalProducts": false,
            "nationalIdentifier": {
                "socialSecurityNumber": "199710202392",
                "countryCode": "SE"
            }
            "firstName": "Leia"
            "lastName": "Ahlström"
            "email": "leia@payex.com",
            "msisdn": "+46787654321",
            "payerReference": "AB1234",
            "shippingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "string",
                "coAddress": "string",
                "city": "string",
                "zipCode": "string",
                "countryCode": "string"
            },
            "billingAddress": {
                "firstName": "firstname/companyname",
                "lastName": "lastname",
                "email": "karl.anderssson@mail.se",
                "msisdn": "+46759123456",
                "streetAddress": "string",
                "coAddress": "string",
                "city": "string",
                "zipCode": "string",
                "countryCode": "string"
            },
            "accountInfo": {
                "accountAgeIndicator": "04",
                "accountChangeIndicator": "04",
                "accountPwdChangeIndicator": "01",
                "shippingAddressUsageIndicator": "01",
                "shippingNameIndicator": "01",
                "suspiciousAccountActivity": "01",
            }
        },
        "orderItems": [
            {
                "reference": "P1",
                "name": "Product1",
                "type": "PRODUCT",
                "class": "ProductGroup1",
                "itemUrl": "https://example.com/products/123",
                "imageUrl": "https://example.com/product123.jpg",
                "description": "Product 1 description",
                "discountDescription": "Volume discount",
                "quantity": 4,
                "quantityUnit": "pcs",
                "unitPrice": 300,
                "discountPrice": 200,
                "vatPercent": 2500,
                "amount": 1000,
                "vatAmount": 250
            },
            {
                "reference": "I1",
                "name": "InvoiceFee",
                "type": "PAYMENT_FEE",
                "class": "Fees",
                "description": "Fee for paying with Invoice",
                "quantity": 1,
                "quantityUnit": "pcs",
                "unitPrice": 1900,
                "vatPercent": 0,
                "amount": 1900,
                "vatAmount": 0,
                "restrictedToInstruments": [
                    "Invoice-PayExFinancingSe"
                ]
            }
        ],
        "riskIndicator": {
            "deliveryEmailAddress": "olivia.nyhuus@payex.com",
            "deliveryTimeFrameIndicator": "01",
            "preOrderDate": "19801231",
            "preOrderPurchaseIndicator": "01",
            "shipIndicator": "01",
            "giftCardPurchase": false,
            "reOrderPurchaseIndicator": "01",
            "pickUpAddress": {
                "name": "Olivia Nyhus",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            }
        }
    }
}
Required Field Type Description
check paymentorder object The payment order object.
check └➔ operation string The operation that the payment order is supposed to perform.
check └➔ currency string The currency of the payment.
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 The description of the payment order.
check └➔ 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.
check └➔ language string The language of the payer.
check └➔ productName string Used to tag the payment as Checkout v3. Mandatory for Checkout v3, as you won’t get the operations in the response without submitting this field.
check └➔ urls object The urls object, containing the URLs relevant for the payment order.
check └─➔ completeUrl string The URL that Swedbank Pay will redirect back to when the payer has completed his or her 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 order to inspect it further. See completeUrl for details.
  └─➔ cancelUrl string The URL to redirect the payer to if the payment is cancelled, either by the payer or by the merchant trough an abort request of the payment or paymentorder.
check └─➔ callbackUrl string The URL to the API endpoint receiving POST requests on transaction activity related to the payment order.
check └─➔ 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.
check └➔ payeeInfo string The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.
check └─➔ payeeId string The ID of the payee, usually the merchant ID.
check └─➔ payeeReference string(30) 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.
  └─➔ payeeName string The name of the payee, usually the name of the merchant.
  └─➔ 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. The subsites must be resolved with Swedbank Pay reconciliation before being used.
  └➔ payer object The payer object containing information about the payer relevant for the payment order.
  └➔ digitalProducts bool Set to true for merchants who only sell digital goods and only require email and/or msisdn as shipping details. Set to false if the merchant also sells physical goods.
  └─➔ nationalIdentifier string The national identifier object.
  └──➔ socialSecurityNumber string The payer’s social security number.
  └──➔ countryCode string The country code of the payer.
check └─➔ firstName string The first name of the payer.
check └─➔ lastName string The last name of the payer.
  └─➔ email string The e-mail address of the payer. Will be used to prefill the Checkin as well as on the payer’s profile, if not already set. Increases the chance for frictionless 3-D Secure 2 flow.
  └─➔ msisdn string The mobile phone number of the Payer. Will be prefilled on Checkin page and used on the payer’s profile, if not already set. The mobile number must have a country code prefix and be 8 to 15 digits in length. The field is related to 3-D Secure 2.
  └─➔ payerReference string A reference used in Enterprise integrations to recognize the payer in the absence of SSN and/or a secure login. Read more about this in the payerReference feature section.
  └➔ shippingAddress object The shipping address object related to the payer. The field is related to 3-D Secure 2.
  └─➔ firstName string The first name of the addressee – the receiver of the shipped goods.
  └─➔ lastName string The last name of the addressee – the receiver of the shipped goods.
  └─➔ streetAddress string Payer’s street address. Maximum 50 characters long.
  └─➔ coAddress string Payer’ s c/o address, if applicable.
  └─➔ zipCode string Payer’s zip code
  └─➔ city string Payer’s city of residence.
  └─➔ countryCode string Country code for country of residence.
check billingAddress object The billing address object containing information about the payer’s billing address.
check └➔ firstName string The first name of the payer.
check └➔ firstName string The first name of the payer.
check︎︎︎︎ ︎ └➔ streetAddress string The street address of the payer. Maximum 50 characters long.
  └➔ coAddress string The CO-address (if used)
check └➔ zipCode string The postal number (ZIP code) of the payer.
check └➔ city string The city of the payer.
check └➔ countryCode string SE, NO, or FI.
  └➔ accountInfo object Object related to the payer containing info about the payer’s account.
  └─➔ accountAgeIndicator string Indicates the age of the payer’s account.
01 (No account, guest checkout)
02 (Created during this transaction)
03 (Less than 30 days old)
04 (30 to 60 days old)
05 (More than 60 days old)
  └─➔ accountChangeIndicator string Indicates when the last account changes occurred.
01 (Changed during this transaction)
02 (Less than 30 days ago)
03 (30 to 60 days ago)
04 (More than 60 days ago)
  └─➔ accountChangePwdIndicator string Indicates when the account’s password was last changed.
01 (No changes)
02 (Changed during this transaction)
03 (Less than 30 days ago)
04 (30 to 60 days ago)
05 (More than 60 days old)
  └─➔ shippingAddressUsageIndicator string Indicates when the payer’s shipping address was last used.
01(This transaction)
02 (Less than 30 days ago)
03 (30 to 60 days ago)
04 (More than 60 days ago)
  └─➔ shippingNameIndicator string Indicates if the account name matches the shipping name.
01 (Account name identical to shipping name)
02 (Account name different from shipping name)
  └─➔ suspiciousAccountActivity string Indicates if there have been any suspicious activities linked to this account.
01 (No suspicious activity has been observed)
02 (Suspicious activity has been observed)
check └➔ orderItems array The array of items being purchased with the order. Note that authorization orderItems will not be printed on invoices, so lines meant for print must be added in the Capture request. The authorization orderItems will, however, be used in the Admin system when captures or reversals are performed, and might be shown other places later. It is required to use this field to be able to send Capture orderItems. Capture requests should only contain items meant to be captured from the order.
check └─➔ reference string A reference that identifies the order item.
check └─➔ name string The name of the order item.
check └─➔ type string PRODUCT, SERVICE, SHIPPING_FEE, PAYMENT_FEE DISCOUNT, VALUE_CODE or OTHER. The type of the order item. PAYMENT_FEE is the amount you are charged with when you are paying with invoice. The amount can be defined in the amount field below.
check └─➔ class string The classification of the order item. Can be used for assigning the order item to a specific product category, such as MobilePhone. Note that class cannot contain spaces and must follow the regex pattern [\w-]*. Swedbank Pay may use this field for statistics.
  └─➔ itemUrl string The URL to a page that can display the purchased item, product or similar.
︎︎︎ └─➔ imageUrl string The URL to an image of the order item.
  └─➔ description string A 40 character length textual description of the purchase.
  └─➔ discountDescription string The human readable description of the possible discount.
check └─➔ quantity integer The 4 decimal precision quantity of order items being purchased.
check └─➔ quantityUnit string The unit of the quantity, such as pcs, grams, or similar. This is used for your own book keeping.
check └─➔ unitPrice integer The price per unit of order item, including VAT.
  └─➔ discountPrice integer If the order item is purchased at a discounted price. This field should contain that price, including VAT.
check └─➔ vatPercent integer The percent value of the VAT multiplied by 100, so 25% becomes 2500.
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.
  └➔ restrictedToInstruments array CreditCard, Invoice, Vipps, Swish, Trustly and/or CreditAccount. Invoice supports the subtypes PayExFinancingNo, PayExFinancingSe and PayMonthlyInvoiceSe, separated by a dash, e.g.; Invoice-PayExFinancingNo. Default value is all supported payment instruments. Use of this field requires an agreement with Swedbank Pay. You can restrict fees and/or discounts to certain instruments by adding this field to the orderline you want to restrict. Use positive amounts to add fees, and negative amounts to add discounts.
  └➔ 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.

Payment Order Response

Response

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

{
    "paymentorder": {
        "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
        "created": "2020-06-22T10:56:56.2927632Z",
        "updated": "2020-06-22T10:56:56.4035291Z",
        "operation": "Purchase",
        "state": "Ready",
        "currency": "SEK",
        "amount": 10000,
        "vatAmount": 0,
        "orderItems": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
        },
        "description": "test description",
        "initiatingSystemUserAgent": "swedbankpay-sdk-dotnet/3.0.1",
        "userAgent": "Mozilla/5.0",
        "language": "sv-SE",
        "urls": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/urls"
        },
        "payeeInfo": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payeeInfo"
        },
        "payments": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/payments"
        },
        "currentPayment": {
            "id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/currentpayment"
        },
        "items": [
            {
                "creditCard": {
                    "cardBrands": [
                        "Visa",
                        "MasterCard"
                    ]
                }
            }
        ]
    }
    "operations": [
        {
            "method": "PATCH",
            "href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-updateorder",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://api.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-abort",
            "contentType": "application/json"
        },
        {
            "method": "PATCH",
            "href": "https://ecom.externalintegration.payex.com/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce",
            "rel": "update-paymentorder-expandinstrument",
            "contentType": "application/json"
        }, 
    ]
}
Field Type Description  
paymentorder object The payment order object.  
└➔ id string The relative URL and unique identifier of the paymentorder 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 of when the payment order was created.  
└➔ updated string The ISO-8601 date of when the payment order was updated.  
└➔ operation string Purchase  
└➔ state string Ready, Pending, Failed or Aborted. Indicates the state of the payment order. Does not reflect the state of any ongoing payments initiated from the payment order. This field is only for status display purposes.  
└➔ currency string The currency of the payment order.  
└➔ 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, en-US or fi-FI.  
└➔ urls string The URL to the urls resource where all URLs related to the payment order can be retrieved.  
└➔ payeeInfo string The payeeInfo object, containing information about the payee (the recipient of the money). See payeeInfo for details.  
└➔ payers string The URL to the payers resource where information about the payee of the payment order can be retrieved.  
└➔ orderItems string The URL to the orderItems resource where information about the order items can be retrieved.  
└➔ payments string The URL to the payments resource where information about all underlying payments can be retrieved.  
└➔ currentPayment string The URL to the currentPayment resource where information about the current – and sole active – payment can be retrieved.  
└➔ operations array The array of possible operations to perform, given the state of the payment order. See Operations for details.