Payer Aware Payment Menu
To give your payers the best experience possible, you should implement the Payer
Aware Payment Menu by identifying each payer with a unique identifier. It is
important that you enforce a good SCA (Strong Consumer Authentication) strategy
when authenticating the payer. The payer identifier must then be included as a
payerReference
in the paymentOrder
request to Swedbank Pay. This will enable
Swedbank Pay to render a unique payment menu experience for each payer. It will
also increase the chance for a frictionless payment.
By identifying your payers, their payment information can be stored for future
purchases by setting the generatePaymentToken
value to true
. The payer is,
by default, asked if they want to store their payment details, so even with
generatePaymentToken
set to true
, it is still up to the payer if they want
the details stored or not.
Please note that not all payment instruments provided by Swedbank Pay support Payer Awareness today.
Trustly Express
If you are offering Trustly Express through our payment aware payment menu, we have two recommendations to make the experience as smooth as possible.
-
Include the first and last name of the payer in the
payer
object. -
Add the payer’s SSN. If you provide it in the
payerReference
field, the SSN has to be hashed.
If you want to read about Trustly Express and the banks who offer it, you can find more information here.
BYO Payment Menu
The payment UI is versatile and can be configured in such a way that it functions like a single payment instrument. In such configuration, it is easy to Bring Your Own Payment Menu, i.e. building a customized payment menu in your own user interface.
Add Stored Payment Instrument Details
When building a custom payment menu, features like adding new stored payment instrument details (i.e. “Add new card”) is something that needs to be provided in your UI.
This can be achieved by forcing the creation of a paymentToken
by setting
disableStoredPaymentDetails
to true
in a Purchase payment (if you want
to withdraw money and create the token in the same operation), or by performing
a verification (without withdrawing any money).
Setting disableStoredPaymentDetails
to true
will turn off all stored payment
details for the current purchase. The payer will also not be asked if they want
to store the payment details that will be part of the purchase. When you use
this feature, it is important that you have asked the payer in advance if it is
ok to store their payment details for later use.
Most often you will use the disableStoredPaymentDetails
feature in combination
with the Instrument Mode capability. If you build your own
menu and want to show stored payment details, you will need to set the
disableStoredPaymentDetails
to true
. It is important that you then store the
paymentToken
in your system or call Swedbank Pay with the payerReference
to
get all active payment tokens registered on that payer when building your
menu.
GDPR
Remember that you have the responsibility of enforcing GDPR requirements and
letting the payer remove active payment tokens when they want. It is up to you
how to implement this functionality on your side, but Swedbank Pay has the API
you need to make it easy to clean up old data. See more below the main
paymentOrder
request example, or follow the hyperlink above.
A Payer Aware Payment Menu request can look like this.
Payer Aware Payment Menu 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
POST /psp/paymentorders HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
CContent-Type: application/json;version=3.1/3.0/2.0 // Version optional for 3.0 and 2.0
{
"paymentorder": {
"operation": "Purchase",
"currency": "SEK",
"amount": 1500,
"vatAmount": 375,
"description": "Test Purchase",
"userAgent": "Mozilla/5.0...",
"generatePaymentToken": true,
"language": "sv-SE",
"instrument": null,
"disableStoredPaymentDetails": false,
"urls": {
"hostUrls": [ "https://example.com", "https://example.net" ],
"completeUrl": "https://example.com/payment-completed",
"cancelUrl": "https://example.com/payment-cancelled",
"callbackUrl": "https://api.example.com/payment-callback",
"termsOfServiceUrl": "https://example.com/termsandconditions.pdf"
},
"payeeInfo": {
"payeeId": "5cabf558-5283-482f-b252-4d58e06f6f3b",
"payeeReference": "AB832",
"payeeName": "Merchant1",
"productCategory": "A123",
"orderReference": "or-123456",
"subsite": "MySubsite",
},
"payer": {
"digitalProducts": false,
"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": "Solna",
"zipCode": "17674",
"countryCode": "SE"
},
"billingAddress": {
"firstName": "firstname/companyname",
"lastName": "lastname",
"email": "karl.anderssson@mail.se",
"msisdn": "+46759123456",
"streetAddress": "string",
"coAddress": "string",
"city": "Solna",
"zipCode": "17674",
"countryCode": "SE"
},
"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": 5,
"quantityUnit": "pcs",
"unitPrice": 300,
"discountPrice": 0,
"vatPercent": 2500,
"amount": 1500,
"vatAmount": 375
},
{
"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 |
Determines the initial operation, defining the type of payment order created. | |
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. | |
disableStoredPaymentDetails |
bool |
Set to false by default. Switching to true will turn off all stored payment details for the current purchase. When you use this feature it is important that you have asked the payer in advance if it is ok to store their payment details for later use. |
||
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. |
|
generatePaymentToken |
bool |
Determines if a payment token should be generated. Default value is false . |
||
check | language |
string |
The language of the payer. | |
check | urls |
object |
The urls object, containing the URLs relevant for the payment order. |
|
check | hostUrls |
array |
The array of URLs valid for embedding of Swedbank Pay Seamless Views. | |
check | 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 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 that Swedbank Pay will perform an HTTP POST against every time a transaction is created on the payment order. See callback for details. |
|
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 |
object |
The payeeInfo object, containing information about the payee. |
|
check | payeeId |
string |
The ID of the payee, usually the merchant ID. | |
check | 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(30) . 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. |
|
payeeName |
string |
The name of the payee, usually the name of the merchant. | ||
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 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 |
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. |
||
firstName |
string |
The first name of the payer. | ||
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 the Enterprise and Payments Only implementations to recognize the payer when no SSN is stored. | ||
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, e.g. SE , NO , or FI . |
||
billingAddress |
object |
The billing address object containing information about the payer’s billing address. | ||
firstName |
string |
The first name of the payer. | ||
lastName |
string |
The last name of the payer. | ||
︎ | streetAddress |
string |
The street address of the payer. Maximum 50 characters long. | |
coAddress |
string |
The CO-address (if used) | ||
zipCode |
string |
The postal number (ZIP code) of the payer. | ||
city |
string |
The city of the payer. | ||
countryCode |
string |
Country code for country of residence, e.g. 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 Merchant Portal 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 |
number |
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 |
A list of the instruments you wish to restrict the payment to. Currently Invoice only. 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. |
Payer Aware Payment Menu 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
65
66
67
68
69
70
71
72
73
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0
{
"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",
"paymentToken" : "5a17c24e-d459-4567-bbad-aa0f17a76119",
"currency": "SEK",
"vatAmount": 375,
"amount": 1500,
"description": "Test Purchase",
"initiatingSystemUserAgent": "PostmanRuntime/3.0.1",
"language": "sv-SE",
"availableInstruments": [
"CreditCard",
"Invoice-PayExFinancingSe",
"Invoice-PayMonthlyInvoiceSe",
"Swish",
"CreditAccount",
"Trustly" ],
"instrumentMode": false,
"guestMode": false,
"payer": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/payers"
},
"orderItems": {
"id": "/psp/paymentorders/09ccd29a-7c4f-4752-9396-12100cbfecce/orderitems"
},
"history": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/history"
},
"failed": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failed"
},
"aborted": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/aborted"
},
"paid": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/paid"
},
"cancelled": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/cancelled"
},
"financialTransactions": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/financialtransactions"
},
"failedAttempts": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/failedattempts"
},
"metadata": {
"id": "/psp/paymentorders/8be318c1-1caa-4db1-e2c6-08d7bf41224d/metadata"
}
},
"operations": [
{
"href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
"rel":"update-order",
"method":"PATCH",
"contentType":"application/json"
},
{
"href": "https://api.payex.com/psp/paymentorders/222a50ca-b268-4b32-16fa-08d6d3b73224",
"rel": "abort",
"method": "PATCH",
"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. |
paymentToken |
string |
The payment token generated in the initial purchase. |
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. |
initiatingSystemUserAgent |
string |
The userAgent of the system used when the merchant makes a call towards the resource. |
language |
string |
sv-SE , nb-NO , da-DK , en-US or fi-FI . |
availableInstruments |
string |
A list of instruments available for this payment. |
implementation |
string |
The merchant’s Digital Payments implementation type. Enterprise or PaymentsOnly . We ask that you don’t build logic around this field’s response. It is mainly for information purposes, as the implementation types might be subject to name changes. If this should happen, updated information will be available in this table. |
integration |
string |
The merchant’s Digital Payments integration type. HostedView (Seamless View) or Redirect . This field will not be populated until the payer has opened the payment UI, and the client script has identified if Swedbank Pay or another URI is hosting the container with the payment iframe. We ask that you don’t build logic around this field’s response. It is mainly for information purposes. as the integration types might be subject to name changes, If this should happen, updated information will be available in this table. |
instrumentMode |
bool |
Set to true or false . Indicates if the payment is initialized with only one payment instrument available. |
guestMode |
bool |
Set to true or false . Indicates if the payer chose to pay as a guest or not. When using the Payments Only implementation, this is triggered by not including a payerReference in the original paymentOrder request. |
payer |
id |
The URL to the payer resource where information about the payer can be retrieved. |
orderItems |
id |
The URL to the orderItems resource where information about the order items can be retrieved. |
history |
id |
The URL to the history resource where information about the payment’s history can be retrieved. |
failed |
id |
The URL to the failed resource where information about the failed transactions can be retrieved. |
aborted |
id |
The URL to the aborted resource where information about the aborted transactions can be retrieved. |
paid |
id |
The URL to the paid resource where information about the paid transactions can be retrieved. |
cancelled |
id |
The URL to the cancelled resource where information about the cancelled transactions can be retrieved. |
financialTransactions |
id |
The URL to the financialTransactions resource where information about the financial transactions can be retrieved. |
failedAttempts |
id |
The URL to the failedAttempts resource where information about the failed attempts can be retrieved. |
metadata |
id |
The URL to the metadata resource where information about the metadata can be retrieved. |
operations |
array |
The array of operations that are possible to perform on the payment order in its current state. See Operations for details. |
Tokens
It is possible to query for all active payment tokens registered on a specific
payerReference
. After doing so, you can either remove all tokens or a subset
of the tokens registered on the payer. This is the easiest way of cleaning up
all data for Payments Only implementations. It is also possible to delete a
single token if you wish to do that.
GET Tokens Request
Querying with a GET
request will give you a response containing all tokens and
the operation(s) available for them.
Request
1
2
3
4
GET /psp/paymentorders/payerownedtokens/<payerReference> HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0 // Version optional for 3.0 and 2.0
GET Tokens 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
65
66
67
68
69
70
71
72
73
74
75
76
77
78
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0
{
"payerOwnedTokens": {
"id": "/psp/paymentorders/payerownedtokens/{payerReference}",
"payerReference": "{payerReference}",
"tokens": [
{
"token": "{paymentToken}",
"tokenType": "Payment",
"instrument": "CreditCard",
"instrumentDisplayName": "492500******0004",
"correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
"instrumentParameters": {
"expiryDate": "12/2022",
"cardBrand": "Visa"
},
"operations": [
{
"method": "PATCH",
"href": "https://api.internaltest.payex.com/psp/paymentorders/paymenttokens/0ecf804f-e68f-404e-8ae6-adeb43052559",
"rel": "delete-paymenttokens",
"contentType": "application/json"
}
]
},
{
"token": "{paymentToken}",
"tokenType": "Payment",
"instrument": "Invoice-payexfinancingno",
"instrumentDisplayName": "260267*****",
"correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
"instrumentParameters": {
"email": "hei@hei.no",
"msisdn": "+4798765432",
"zipCode": "1642"
},
"operations": [
{
"method": "PATCH",
"href": "https://api.internaltest.payex.com/psp/paymentorders/paymenttokens/dd9c1103-3e0f-492a-95a3-a39bb32a6b59",
"rel": "delete-paymenttokens",
"contentType": "application/json"
}
]
},
{
"token": "{token}",
"tokenType": "Unscheduled",
"instrument": "CreditCard",
"instrumentDisplayName": "492500******0004",
"correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
"instrumentParameters": {
"expiryDate": "12/2020",
"cardBrand": "Visa"
},
"operations": [
{
"method": "PATCH",
"href": "https://api.internaltest.payex.com/psp/paymentorders/unscheduledtokens/e2f06785-805d-4605-bf40-426a725d313d",
"rel": "delete-unscheduledtokens",
"contentType": "application/json"
}
]
}
]
},
"operations": [
{
"method": "PATCH",
"href": "https://api.internaltest.payex.com/psp/paymentorders/payerOwnedPaymentTokens/{payerReference}",
"rel": "delete-payerownedtokens",
"contentType": "application/json"
}
]
}
Field | Type | Description |
---|---|---|
payerOwnedTokens |
object |
The payerOwnedTokens object containing information about the payer relevant for the payment order. |
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. |
payerReference |
string |
A reference used in the Enterprise and Payments Only implementations to recognize the payer when no SSN is stored. |
tokens |
integer |
A list of tokens connected to the payment. |
token |
string |
The token guid . |
tokenType |
string |
payment , recurrence , transactionOnFile or unscheduled . The different types of available tokens. |
instrument |
string |
Payment instrument connected to the token. |
instrumentDisplayName |
string |
Payment instrument connected to the token. |
correlationId |
string |
A unique ID used in the system. Makes it easier to see cards, accounts etc. the token is connected to. |
instrumentParameters |
integer |
A list of additional information connected to the token. Depending on the instrument, it can e.g. be expiryDate , cardBrand , email , msisdn or zipCode . |
operations |
array |
The array of operations that are possible to perform on the token in its current state. |
PATCH Request For Removing Tokens
You can remove the tokens by using the following PATCH
request.
Request
1
2
3
4
5
6
7
8
9
PATCH /psp/paymentorders/payerownedtokens/<payerReference> HTTP/1.1
Host: api.externalintegration.payex.com
Authorization: Bearer <AccessToken>
Content-Type: application/json;version=3.1/3.0/2.0 // Version optional for 3.0 and 2.0
{
"state": "Deleted",
"comment": "Some words about why the tokens are being deleted"
}
Field | Type | Description |
---|---|---|
state |
string |
The state you want the token to be in. |
comment |
string |
Explanation as to why the token is being deleted. |
Which will provide this 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
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8; version=3.1/3.0/2.0
api-supported-versions: 3.1/3.0/2.0
{
"payerOwnedTokens": {
"id": "/psp/paymentorders/payerownedtokens/{payerReference}",
"payerReference": "{payerReference}",
"tokens": [
{
"token": "{paymentToken}",
"tokenType": "Payment",
"instrument": "Invoice-payexfinancingno",
"instrumentDisplayName": "260267*****",
"instrumentParameters": {
"email": "hei@hei.no",
"msisdn": "+4798765432",
"zipCode": "1642"
}
},
{
"token": "{paymentToken}",
"tokenType": "Unscheduled",
"instrument": "CreditCard",
"instrumentDisplayName": "492500******0004",
"correlationId": "e2f06785-805d-4605-bf40-426a725d313d",
"instrumentParameters": {
"expiryDate": "12/2020",
"cardBrand": "Visa"
}
}
]
}
}
Field | Type | Description |
---|---|---|
payerOwnedTokens |
object |
The payerOwnedTokens object containing information about the payer relevant for the payment order. |
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. |
payerReference |
string |
A reference used in the Enterprise and Payments Only implementations to recognize the payer when no SSN is stored. |
tokens |
integer |
A list of tokens connected to the payment. |
token |
string |
The token guid . |
tokenType |
string |
payment , recurrence , transactionOnFile or unscheduled . The different types of available tokens. |
instrument |
string |
Payment instrument connected to the token. |
instrumentDisplayName |
string |
Payment instrument connected to the token. |
correlationId |
string |
A unique ID used in the system. Makes it easier to see cards, accounts etc. the token is connected to. |
instrumentParameters |
integer |
A list of additional information connected to the token. Depending on the instrument, it can e.g. be expiryDate , cardBrand , email , msisdn or zipCode . |