nexo Retailer

PaymentResponse

Payment response holds the receipt data

Edit "PaymentResponse" on GitHub

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 instrument 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