A payment is approved if the Result attribute of the /PaymentResponse/Response element is Success.
For all unapproved payments the same attribute is Failure and the actual response code is found in the receipt data if wanted.
Depending on why a payment is unapproved the response may not contain a receipt. However, make sure to always make a payment terminal receipt available if a card has been used.
The payment response carries both a merchant receipt and a customer receipt. The customer receipt should always be used. The merchant receipt is used if the receipt needs to be signed by the customer. The receiptdata is a Base64 encoded JSON structure.
Sample Payment Response for approved payment with physical payment card
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
<?xml version="1.0" encoding="UTF-8"?>
<SaleToPOIResponse>
<MessageHeader MessageClass="Service" MessageCategory="Payment" MessageType="Response" ServiceID="3" SaleID="1" POIID="A-POIID"/>
<PaymentResponse>
<Response Result="Success"/>
<SaleData>
<SaleTransactionID TransactionID="1703372" TimeStamp="2023-08-24T17:03:37+02:00"/>
</SaleData>
<POIData>
<POITransactionID TransactionID="8778880185" TimeStamp="2023-08-24T15:04:00.498Z"/>
</POIData>
<PaymentResult PaymentType="Normal">
<PaymentInstrumentData PaymentInstrumentType="Card">
<CardData PaymentBrand="01,Mastercard Debit" MaskedPAN="516815******9659" EntryMode="Contactless">
<PaymentToken TokenRequestedType="Customer" TokenValue="6FD955C23A48A041D881003CDBF836DC59F89CE0ECA8288129696CDF9BB8B8DD67F233"/>
</CardData>
</PaymentInstrumentData>
<AmountsResp Currency="SEK" AuthorizedAmount="56" CashBackAmount="0.00"/>
<PaymentAcquirerData MerchantID="10020001" AcquirerPOIID="877888">
<ApprovalCode>611506</ApprovalCode>
</PaymentAcquirerData>
</PaymentResult>
<PaymentReceipt DocumentQualifier="CashierReceipt">
<OutputContent OutputFormat="Text">
<OutputText>eyJNZXJjaGFudCI6eyJNYW5kYXRvcnkiOnsiQWNxdWlyZXIiOnsiQ2FyZEFjY2VwdG9yTnVtYmVyIjoiMTAwMjAwMDEiLCJUZXJtaW5hbElEIjoiODc3ODg4In0sIkNhcmRBY2NlcHRvciI6eyJBZGRyZXNzMSI6IkjDpGxsZXNrw6VyYW4gMjkiLCJCYW5rQWdlbnROYW1lIjoiYmFua3ktYmFuayIsIk5hbWUiOiJUZXN0IHNob3AiLCJPcmdhbmlzYXRpb25OdW1iZXIiOiI1NTY1NjcxLTYxNjUiLCJQb3N0WmlwQ29kZSI6IjUwNTAiLCJUb3duQ2l0eSI6Im1lcmNoYW50LUJhc2UyNC1DaXR5In0sIkNhcmREZXRhaWxzIjp7IkFwcGxpY2F0aW9uSWRlbnRpZmllciI6IkEwMDAwMDAwMDQxMDEwIiwiQ2FyZFNjaGVtZU5hbWUiOnsiQXBwbGljYXRpb25MYWJlbCI6Ik1hc3RlcmNhcmQifSwiUHJpbWFyeUFjY291bnROdW1iZXIiOiI1MTY4MTUqKioqKio5NjU5IiwiVGVybWluYWxWZXJpZmljYXRpb25SZXN1bHQiOiIwMDAwMDA4MDAxIiwiVHJhbnNhY3Rpb25TdGF0dXNJbmZvcm1hdGlvbiI6IjAwMDAifSwiT3V0Y29tZSI6eyJBcHByb3ZhbENvZGUiOiI2MTE1MDYiLCJBdXRob3Jpc2F0aW9uUmVzcG9uZGVyIjoiMyIsIkF1dGhvcmlzYXRpb25SZXNwb25zZUNvZGUiOiIwMCIsIkRlYml0U3RhdHVzIjoiMDAifSwiUGF5bWVudCI6eyJBdXRob3Jpc2F0aW9uQ2hhbm5lbCI6IjEiLCJDYXJkaG9sZGVyVmVyaWZpY2F0aW9uTWV0aG9kIjoiLyIsIkN1cnJlbmN5IjoiU0VLIiwiRmluYW5jaWFsSW5zdGl0dXRpb24iOiJTV0UiLCJQYXltZW50QW1vdW50IjoiNTYsMDAiLCJSZWNlaXB0TnVtYmVyIjoiODc3ODg4MDE4NSIsIlNpZ25hdHVyZUJsb2NrIjpmYWxzZSwiVG90YWxBbW91bnQiOiI1NiwwMCIsIlRyYW5zYWN0aW9uU291cmNlIjoiSyIsIlRyYW5zYWN0aW9uVHlwZSI6IjAwIn0sIlRpbWVTdGFtcCI6eyJEYXRlT2ZQYXltZW50IjoiMjAyMy0wOC0yNCIsIlRpbWVPZlBheW1lbnQiOiIxNzowNiJ9fSwiT3B0aW9uYWwiOnsiQ2FyZEFjY2VwdG9yIjp7IkNvdW50cnlOYW1lIjoiNzUyIiwiUGhvbmVOdW1iZXIiOiIrNDY4NDA1MTAwMCJ9LCJDYXJkRGV0YWlscyI6eyJDYXJkU2NoZW1lTmFtZSI6eyJBcHBsaWNhdGlvbkxhYmVsIjoiTWFzdGVyY2FyZCJ9fSwiUGF5bWVudCI6eyJSZWZlcmVuY2UiOiIxNzAzMzcyIn0sIlJlY2VpcHRTdHJpbmciOlsiVGVzdCBzaG9wIiwiSMOkbGxlc2vDpXJhbiAyOSIsIjUwNTAgbWVyY2hhbnQtQmFzZTI0LUNpdHkiLCIyMDIzLTA4LTI0IDE3OjA2IiwiIiwiTWFzdGVyY2FyZCIsIkNvbnRhY3RsZXNzIiwiNTE2ODE1KioqKioqOTY1OSIsIiIsIksvMSAzIDAwIFNXRSIsIkFJRDogQTAwMDAwMDAwNDEwMTAiLCJUVlI6IDAwMDAwMDgwMDEiLCJUU0k6IDAwMDAiLCJSUk46IDg3Nzg4ODAxODUiLCJBdXRoIGNvZGU6IDYxMTUwNiIsIkFSQzogMDAiLCIiLCJLw5ZQOiAgICAgICAgIDU2LDAwIFNFSyIsIkdvZGvDpG5kIiwiIiwiIiwiIiwiRsO2cnPDpGxqYXJlbnMga3ZpdHRvIl19fX0=</OutputText>
</OutputContent>
</PaymentReceipt>
<PaymentReceipt DocumentQualifier="CustomerReceipt">
<OutputContent OutputFormat="Text">
<OutputText>eyJDYXJkaG9sZGVyIjp7Ik1hbmRhdG9yeSI6eyJBY3F1aXJlciI6eyJDYXJkQWNjZXB0b3JOdW1iZXIiOiIxMDAyMDAwMSIsIlRlcm1pbmFsSUQiOiI4Nzc4ODgifSwiQ2FyZEFjY2VwdG9yIjp7IkFkZHJlc3MxIjoiSMOkbGxlc2vDpXJhbiAyOSIsIkJhbmtBZ2VudE5hbWUiOiJiYW5reS1iYW5rIiwiTmFtZSI6IlRlc3Qgc2hvcCIsIk9yZ2FuaXNhdGlvbk51bWJlciI6IjU1NjU2NzEtNjE2NSIsIlBvc3RaaXBDb2RlIjoiNTA1MCIsIlRvd25DaXR5IjoibWVyY2hhbnQtQmFzZTI0LUNpdHkifSwiQ2FyZERldGFpbHMiOnsiQXBwbGljYXRpb25JZGVudGlmaWVyIjoiQTAwMDAwMDAwNDEwMTAiLCJDYXJkU2NoZW1lTmFtZSI6eyJBcHBsaWNhdGlvbkxhYmVsIjoiTWFzdGVyY2FyZCJ9LCJQcmltYXJ5QWNjb3VudE51bWJlciI6IioqKioqKioqKioqKjk2NTkiLCJUZXJtaW5hbFZlcmlmaWNhdGlvblJlc3VsdCI6IjAwMDAwMDgwMDEiLCJUcmFuc2FjdGlvblN0YXR1c0luZm9ybWF0aW9uIjoiMDAwMCJ9LCJPdXRjb21lIjp7IkFwcHJvdmFsQ29kZSI6IjYxMTUwNiIsIkF1dGhvcmlzYXRpb25SZXNwb25kZXIiOiIzIiwiQXV0aG9yaXNhdGlvblJlc3BvbnNlQ29kZSI6IjAwIiwiRGViaXRTdGF0dXMiOiIwMCJ9LCJQYXltZW50Ijp7IkF1dGhvcmlzYXRpb25DaGFubmVsIjoiMSIsIkNhcmRob2xkZXJWZXJpZmljYXRpb25NZXRob2QiOiIvIiwiQ3VycmVuY3kiOiJTRUsiLCJGaW5hbmNpYWxJbnN0aXR1dGlvbiI6IlNXRSIsIlBheW1lbnRBbW91bnQiOiI1NiwwMCIsIlJlY2VpcHROdW1iZXIiOiI4Nzc4ODgwMTg1IiwiU2lnbmF0dXJlQmxvY2siOmZhbHNlLCJUb3RhbEFtb3VudCI6IjU2LDAwIiwiVHJhbnNhY3Rpb25Tb3VyY2UiOiJLIiwiVHJhbnNhY3Rpb25UeXBlIjoiMDAifSwiVGltZVN0YW1wIjp7IkRhdGVPZlBheW1lbnQiOiIyMDIzLTA4LTI0IiwiVGltZU9mUGF5bWVudCI6IjE3OjA2In19LCJPcHRpb25hbCI6eyJDYXJkQWNjZXB0b3IiOnsiQ291bnRyeU5hbWUiOiI3NTIiLCJQaG9uZU51bWJlciI6Iis0Njg0MDUxMDAwIn0sIkNhcmREZXRhaWxzIjp7IkNhcmRTY2hlbWVOYW1lIjp7IkFwcGxpY2F0aW9uTGFiZWwiOiJNYXN0ZXJjYXJkIn19LCJQYXltZW50Ijp7IlJlZmVyZW5jZSI6IjE3MDMzNzIifSwiUmVjZWlwdFN0cmluZyI6WyJUZXN0IHNob3AiLCJIw6RsbGVza8OlcmFuIDI5IiwiNTA1MCBtZXJjaGFudC1CYXNlMjQtQ2l0eSIsIjIwMjMtMDgtMjQgMTc6MDYiLCIiLCJNYXN0ZXJjYXJkIiwiQ29udGFjdGxlc3MiLCIqKioqKioqKioqKio5NjU5IiwiIiwiSy8xIDMgMDAgU1dFIiwiQUlEOiBBMDAwMDAwMDA0MTAxMCIsIlRWUjogMDAwMDAwODAwMSIsIlRTSTogMDAwMCIsIlJSTjogODc3ODg4MDE4NSIsIkF1dGggY29kZTogNjExNTA2IiwiQVJDOiAwMCIsIiIsIkvDllA6ICAgICAgICAgNTYsMDAgU0VLIiwiR29ka8OkbmQiLCIiLCIiLCIiLCJLb3J0aW5uZWhhdmFyZW5zIGt2aXR0byJdfX19</OutputText>
</OutputContent>
</PaymentReceipt>
</PaymentResponse>
</SaleToPOIResponse>
PaymentResponse in Detail
| Name | Lev | Attributes | Description |
|---|---|---|---|
| PaymentResponse | 1 | ||
| Response | 2 | Result | Success or Failure. |
| ErrorCondition | Only present if Failure: Common values are Busy- wait and try again, Refusal- Request not accepted. |
||
| AdditionalResponse | 3 | Only present if Failure and should be a describing text. | |
| SaleData | 2 | ||
| SaleTransactionID | 3 | TransactionID | ID of transaction provided by the sale system and may be seen in PosPay reports. Information will not be past to clearing and is not seen in Merchant Portal. |
| TimeStamp | Timestamp set by sale system for when the transaction is started. Note that the format is local time. | ||
| POIData | 2 | ||
| POITransactionID | 3 | TransactionID | ID of transaction set by the terminal. This is seen in PosPay reports as well as on Merchant Portal. The complete element is needed if the transaction needs to be reversed. |
| TimeStamp | Timestamp set by terminal when the transaction is started. Note that the format is UTC. | ||
| PaymentResult | 2 | PaymentType | Values: Normal for purchase and Refund for refund. |
| PaymentInstrumentData | 3 | PaymentInstrumentType | Values: Card for any transaction made by the terminal with a card or any consumer device. Mobile for an alternative payment method made via the terminal. |
| CardData | 4 | PaymentBrand | Comma separated string where the first part is card type. 01-payment card. 02-Combined payment and Loyalty, 03-Loyalty, 04-Neither. May be used instead of 03 for controlling the dialog in the terminal. Second part is the product name. |
| MaskedPAN | |||
| EntryMode |
ICC, Contactless, Magstripe. |
||
| PaymentToken | 5 | TokenRequestedType |
Customer. |
| TokenValue | An irreversible 70 byte hash computed locally in the terminal. A specific card will get the same CNA in all SwedbankPay PAX terminals. | ||
| AmountsResp | 3 | Currency | Needs to be configured in the terminal. Available DKK, EUR, NOK, SEK. |
| AuthorizedAmount | Total amount for transaction. | ||
| CashBackAmount | Amount included in AuthorizedAmount. | ||
| TipAmount | Tip included in AuthorizedAmount. | ||
| PaymentAquirerData | 3 | MerchantID | Id of merchant set by Swedbank Pay. |
| AquirerPOIID | A terminal id within Swedbank Pay. | ||
| ApprovalCode | 4 | Authorization approval code. Only present if Result is Success. | |
| PaymentReceipt | 2 | DocumentQualifier |
CashierReceipt- Merchant copy. CustomerReceipt- receipt information for customer. Note! This element appears twice. |
| OutputContent | 3 | OutputFormat | Only value Text. |
| OutputText | 4 | A Base64 encoded JSON structure with information for the receipt. |
PaymentReceipt in Detail
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
{
"Cardholder": {
"Mandatory": {
"Acquirer": {
"CardAcceptorNumber": "10020001",
"TerminalID": "877888"
},
"CardAcceptor": {
"Address1": "Hälleskåran 29",
"BankAgentName": "banky-bank",
"Name": "Test shop",
"OrganisationNumber": "5565671-6165",
"PostZipCode": "5050",
"TownCity": "merchant-Base24-City"
},
"CardDetails": {
"ApplicationIdentifier": "A0000000041010",
"CardSchemeName": {
"ApplicationLabel": "Mastercard"
},
"PrimaryAccountNumber": "************9659",
"TerminalVerificationResult": "0000008001",
"TransactionStatusInformation": "0000"
},
"Outcome": {
"ApprovalCode": "611506",
"AuthorisationResponder": "3",
"AuthorisationResponseCode": "00",
"DebitStatus": "00"
},
"Payment": {
"AuthorisationChannel": "1",
"CardholderVerificationMethod": "/",
"Currency": "SEK",
"FinancialInstitution": "SWE",
"PaymentAmount": "56,00",
"ReceiptNumber": "8778880185",
"SignatureBlock": false,
"TotalAmount": "56,00",
"TransactionSource": "K",
"TransactionType": "00"
},
"TimeStamp": {
"DateOfPayment": "2023-08-24",
"TimeOfPayment": "17:06"
}
},
"Optional": {
"CardAcceptor": {
"CountryName": "752",
"PhoneNumber": "+4684051000"
},
"CardDetails": {
"CardSchemeName": {
"ApplicationLabel": "Mastercard"
}
},
"Payment": {
"Reference": "1703372"
},
"ReceiptString": [
"Test shop",
"Hälleskåran 29",
"5050 merchant-Base24-City",
"2023-08-24 17:06",
"",
"Mastercard",
"Contactless",
"************9659",
"",
"K/1 3 00 SWE",
"AID: A0000000041010",
"TVR: 0000008001",
"TSI: 0000",
"RRN: 8778880185",
"Auth code: 611506",
"ARC: 00",
"",
"KÖP: 56,00 SEK",
"Godkänd",
"",
"",
"",
"Kortinnehavarens kvitto"
]
}
}
}
For CVM method Signature default integration
If the full integration is made and the login was made with SaleCapabilities including CashierInput, the following sequence diagram shows how a purchase that is apporoved with a card holder signature would look like.
sequenceDiagram
POS->>+Terminal: Http POST PaymentRequest
Terminal->>POS: Http POST DisplayRequest
POS->>Terminal: rsp 204 - no content
Terminal->>POS: Http POST DisplayRequest
Note over Terminal: "Please wait"
POS->>Terminal: rsp 204 - no content
Terminal->>POS: Http POST DisplayRequest
Note over Terminal: "Authorizing"
POS->>Terminal: rsp 204 - no content
Terminal->>POS: Http POST PrintRequest
Note over Terminal: Merchant receipt
POS->>Terminal: rsp 204 - no content
Terminal->>POS: Http POST InputRequest Confirmation
Note over Terminal: Is signature OK?
alt
Note right of POS: Approve signature
POS->>Terminal: rsp 200 InputResponse True
Terminal->>POS: Http POST DisplayRequest
Note over Terminal: "Approved"
POS->>Terminal: rsp 204 - no content
else
Note right of POS: Disapprove signature
POS->>Terminal: rsp 200 InputResponse False
Terminal->>POS: Http POST DisplayRequest
Note over Terminal: "Disapproved"
POS->>Terminal: rsp 204 - no content
end
Terminal->>-POS: rsp 200 PaymentResponse Success/Failure
Terminal->>POS: Http POST DisplayRequest
Note over Terminal: "Welcome"
POS->>Terminal: rsp 204 - no content
For CVM method Signature Client Only mode
If the Client-Only integration is made or rather, if login was made without SaleCapabilites CashierInput, it is essential to check the receipt data Json for {"Merchant":{"Mandatory":{"Payment":"SignatureBlock":true"}}}. If SignatureBlock is true, the merchant receipt must be printed and signed by the customer.
The following sequence diagram shows how a purchase that is apporoved with a card holder signature would look like when running Client-Only mode.
sequenceDiagram
POS->>+Terminal: Http POST PaymentRequest
Terminal->>-POS: Http Response 200 PaymentResponse
Note over Terminal: Merchant receipt data<br>JSON SignatureBlock is true
Note over POS: Print merchant receipt
Note over POS: Ask customer to sign<br>verify ID of customer
alt Approve
Note over POS: Print Customer receipt
else Don't approve
Note right of POS: Disapprove signature
POS->>Terminal: Http POST ReversalRequest
Terminal->>POS: Http Response 200
Note over Terminal: includes new customer receipt
Note over POS: Print customer receipt
end
Note over Terminal: Ready for new request