Card

Purchase

schedule 8 min read

The bread and butter of the payments.

Edit "Purchase" on GitHub

Purchase

A Purchase payment is a straightforward way to charge the card of the payer. It is followed up by posting a capture, cancellation or reversal transaction. An example of a request is provided below. Each individual field of the JSON document is described in the following section.

Purchase Operation

Posting a payment (operation Purchase) returns the options of aborting the payment altogether or creating an authorization transaction through the redirect-authorization hyperlink.

Request

1
2
3
4
5
{
    "payment": {
        "operation": "Purchase"
    }
}

Purchase Payment

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
POST /psp/creditcard/payments HTTP/1.1
Authorization: Bearer <AccessToken>
Content-Type: application/json

{
    "payment": {
        "operation": "Purchase",
        "intent": "Authorization",
        "currency": "SEK",
        "prices": [{
                "type": "CreditCard",
                "amount": 1500,
                "vatAmount": 0
            }
        ],
        "description": "Test Purchase",
        "generatePaymentToken": false,
        "generateRecurrenceToken": false,
        "generateUnscheduledToken": false,
        "userAgent": "Mozilla/5.0...",
        "language": "nb-NO",
        "urls": { 
            "completeUrl": "https://example.com/payment-completed",
            "cancelUrl": "https://example.com/payment-canceled",
            "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"
            }, 
            "billingAddress": {
                "firstName": "Olivia",
                "lastName": "Nyhuus",
                "email": "olivia.nyhuus@payex.com",
                "msisdn": "+4798765432",
                "streetAddress": "Saltnestoppen 43",
                "coAddress": "",
                "city": "Saltnes",
                "zipCode": "1642",
                "countryCode": "NO"
            },
            "accountInfo": {
                "accountAgeIndicator": "01",
                "accountChangeIndicator": "01",
                "accountPwdChangeIndicator": "01",
                "shippingAddressUsageIndicator": "01",
                "shippingNameIndicator": "01",
                "suspiciousAccountActivity": "01",
                "addressMatchIndicator": "false"
            }
        },
        "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"
            }
        },
        "metadata": {
            "key1": "value1",
            "key2": 2,
            "key3": 3.1,
            "key4": false
        }
    },
    "creditCard": {
        "rejectCreditCards": false,
        "rejectDebitCards": false,
        "rejectConsumerCards": false,
        "rejectCorporateCards": false,
        "no3DSecure": false
    }
}
Required Field Type Description
check payment object The payment object
check └➔ operation string Determines the initial operation, that defines the type card payment created.

Purchase. Used to charge a card. It is followed up by a capture or cancel operation.

Recur.Used to charge a card on a recurring basis. Is followed up by a capture or cancel operation (if not Autocapture is used, that is).

Payout. Used to deposit funds directly to credit card. No more requests are necessary from the merchant side.

Verify. Used when authorizing a card withouth reserveing any funds. It is followed up by a verification transaction.
check └➔ 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.
  └➔ paymentToken string If a paymentToken is included in the request, the card details stored in the paymentToken will be prefilled on the payment page. The payer still has to enter the cvc to complete the purchase. This is called a “One Click” purchase.
check └➔ currency string NOK, SEK, DKK, USD or EUR.
check └➔ prices array The prices resource lists the prices related to a specific payment.
check └─➔ type string Use the generic type CreditCard if you want to enable all card brands supported by merchant contract. Use card brands like Visa (for card type Visa), MasterCard (for card type MasterCard) and others if you want to specify different amount for each card brand. If you want to use more than one amount you must have one instance in the prices node for each card brand. You will not be allowed to both specify card brands and CreditCard at the same time in this field. See the Prices resource and prices object types for more information.
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(40) A 40 character length textual description of the purchase.
  └➔ generatePaymentToken boolean true or false. Set this to true if you want to create a paymentToken for future use as One Click.
  └➔ generateRecurrenceToken boolean true or false. Set this to true if you want to create a recurrenceToken for future use Recurring purchases (subscription payments).
  └➔ generateUnscheduledToken boolean true or false. Set this to true if you want to create a unscheduledToken for future use Unscheduled purchases (merchant initiated transactions).
check └➔ userAgent string The User-Agent string of the payer’s web browser.
check └➔ 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.
check └➔ urls object The object containing URLs relevant for the payment.
check └─➔ hostUrls array The array of URLs valid for embedding of Swedbank Pay Seamless Views. If not supplied, view-operation will not be available.
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 to inspect it further. See completeUrl for details.
check └─➔ cancelUrl string The URI to redirect the payer to if the payment is canceled. Only used in redirect scenarios. Can not be used simultaneously with paymentUrl; only cancelUrl or paymentUrl can be used, not both.
  └─➔ paymentUrl string The URI 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. Only used in Seamless Views. If both cancelUrl and paymentUrl is sent, the paymentUrl will used. See paymentUrl for details.
  └─➔ 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 URI 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 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. The subsites must be resolved with Swedbank Pay reconciliation before being used.
  └➔ 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 generateReccurenceToken, RecurrenceToken, generatePaymentToken or paymentToken is true.
  └➔ metadata object 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.
  └➔ 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)
  └─➔ accountInfo object Optional (increased chance for frictionless flow if set).

If cardholder is known by merchant and have some kind of registered user then these fields can be set.
  └──➔ accountAgeIndicator string Optional (increased chance for frictionless flow if set).

Indicates the length of time that the payments account was enrolled in the cardholder’s account with merchant.
01 (No account, guest)
02 (Created during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)
  └──➔ accountChangeIndicator string Optional (increased chance for frictionless flow if set).

Length of time since the cardholder’s account information with the merchant was changed. Including billing etc.
01 (Changed during transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)
  └──➔ accountPwdChangeIndicator string Optional (increased chance for frictionless flow if set).

Indicates the length of time since the cardholder’s account with the merchant had a password change or account reset.
01 (No change)
02 (Changed during transaction)
03 (Less than 30 days)
04 (30-60 days)
05 (More than 60 days)
  └──➔ shippingAddressUsageIndicator string Optional (increased chance for frictionless flow if set).

Indicates when the shipping address used for this transaction was first used with the merchant.
01 (This transaction)
02 (Less than 30 days)
03 (30-60 days)
04 (More than 60 days)
  └──➔ shippingNameIndicator string Optional (increased chance for frictionless flow if set).

Indicates if the Cardholder Name on the account is identical to the shipping Name used for this transaction.
01 (Account name identical to shipping name)
02 (Account name different than shipping name)
  └──➔ suspiciousAccountActivity string Optional (increased chance for frictionless flow if set).

Indicates whether merchant has experienced suspicious activity (including previous fraud) on the cardholder account.
01 (No suspicious activity has been observed)
02 (Suspicious activity has been observed)
  └──➔ addressMatchIndicator boolean Optional (increased chance for frictionless flow if set)

Allows the 3-D Secure Requestor to indicate to the ACS whether the cardholder’s billing and shipping address are the same.
  └─➔ riskIndicator object This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelyhood of having to prompt for 3-D Secure 2.0 authentication of the payer when they are authenticating the purchase.
  └➔ riskIndicator array This optional object consist of information that helps verifying the payer. Providing these fields decreases the likelyhood 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 likelyhood 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.
  creditCard object The credit card object.
  └➔ rejectDebitCards boolean true if debit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectCreditCards boolean true if credit cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectConsumerCards boolean true if consumer cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ rejectCorporateCards boolean true if corporate cards should be declined; otherwise false per default. Default value is set by Swedbank Pay and can be changed at your request.
  └➔ no3DSecure boolean true if 3-D Secure should be disabled for this payment in the case a stored card is used; otherwise false per default. To use this feature it has to be enabled on the contract with Swedbank Pay.
  └➔ noCvc boolean true if the CVC field should be disabled for this payment in case a stored card is used; otherwise false per default. This feature is commonly used when One-Click Payments is enabled. To use this feature it has to be enabled on the contract with Swedbank Pay.

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
65
66
HTTP/1.1 200 OK
Content-Type: application/json

{
    "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": "PostmanRuntime/3.0.1",
        "userAgent": "Mozilla/5.0...",
        "language": "sv-SE",
        "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"
        }
    ]
}
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.
└─➔ 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.
└➔ 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 string of 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 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.
└➔ payers string The URI to the payer resource where the information about the payer can be retrieved.
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.