Table of content

  1. Payment API WSDL
  2. Methods for payments
  3. Methods specific for point of sale (terminal) registration
  4. Methods for reconciliation and reporting
  5. Request objects data
  6. Result codes

Payment API

This is a description of SEQR SOAP-WS-API v2.6.0 for merchants.
Our test environment WSDL is available at: https://extdev.seqr.com/soap/merchant/cashregister-2?wsdl

Methods for payments

Method Description
sendInvoice Sends an invoice to the SEQR service. Tokens are optional and only for loyalty.
updateInvoice Updates an already sent invoice with new set of invoice rows and amount or attributes, for example loyalty.
getPaymentStatus Obtains status of a previously submitted invoice. When fetching the payment status, SEQR may communicate a set of customer tokens to the merchant that are applicable for the payment. The merchant must then decide which tokens are applied (such as for loyalty) and send them back with the updateInvoice request.
cancelInvoice Cancels an unpaid invoice.
commitReservation Commits a payment, if a payment reservation successfully executed. We are working on support for reservations in cooperation with more banks.
submitPaymentReceipt Used to confirm that the payment was received by the point of sale. Adds a receipt document to the payment.
refundPayment Refunds a previous payment, either part of it or the whole sum.

Methods specific for point of sale (terminal) registration

Method Description
registerTerminal Registers a new terminal in the SEQR service.
unRegisterTerminal Unregisters an already registered terminal.
assignSeqrId Assigns a SEQR ID to a terminal.

Methods for reconciliation and reporting

Method Description
markTransactionPeriod Marks the end of one and the beginning of a new transaction period. Used in reporting.
executeReport Executes a report on the SEQR service.

Request objects data

ClientContext parameter used in all calls

A principal is the main actor in each request to the SEQR service and represents either a seller or a buyer. Each request has at least an initiator principal. The client Context structure is used in all requests to identify, authenticate and authorize the client initiating the transaction. For authentication the credentials of the initiator principal are used. As all transactions take place over a secure channel (typically HTTPS) the ClientContext is sent in clear text.

If no max-length is specified it is unlimited for strings.

ClientContext
Fields Description
channel The channel used to send a request. Always use ClientWS or WS.
  • Type: string
  • Required: Y
  • Max-Length: 40
  • Sample value: ClientWS
clientComment Client comment included within the request.
  • Type: string
  • Required: N
  • Max-Length: 80
  • Sample value: My comment
clientId Client ID identifies the software which the SEQR service is communicating with.
  • Type: string
  • Required: Y
  • Sample value: My POS Version 1.2.3
clientReference The client reference for the transaction. Recommendation: the clientReference should be unique at least for the specific clientId. Note: SEQR service does not check this field. The field is mandatory for troubleshooting purposes.
  • Type: string
  • Required: Y
  • Max-Length: 32
  • Sample value: my_invoice_1234567890
clientRequestTimeout The client side timeout for the request. If the response is not received before the timeout the client will attempt to abort the request. Must be set to 0, so there will not be any client forced timeouts in the SEQR service.
  • Type: long
  • Required: Y
  • Recommended value: 0
initiatorPrincipalId Used for authentication of the principal. Contains subfields id, type and optional userId. Use RESELLERUSER type when you register a new terminal with id provided from SEQR and userId with fixed value, otherwise use TERMINALID type with id provided from SEQR.
  • Type: string
  • Required: Y
  • Samples below:
    <initiatorPrincipalId>
        <id>my_terminal_id</id>
        <type>TERMINALID</type>
    </initiatorPrincipalId>
    <initiatorPrincipalId>
        <id>my_reseller_id</id>
        <type>RESELLERUSER</type>
        <userId>9900</userId>
    </initiatorPrincipalId>
password The password used to authenticate the initiator principal.
  • Type: string
  • Required: Y
  • Sample value: my_password

Invoice data

Invoice is used in sending, updating and receiving status on a payment. What you need to set is:

Invoice
Fields Description
paymentMode The mode of payment. For standard payments use IMMEDIATE_DEBIT.
Modes RESERVATION_DESIRED / RESERVATION_REQUIRED / RESERVATION_REQUIRED_PRELIMINARY_AMOUNT are used in non-standard payments.
  • Type: string
  • Required: Y
  • Sample value: IMMEDIATE_DEBIT
acknowledgmentMode Needs to be set to NO_ACKNOWLEDGMENT unless you provide loyalty flow.
  • Type: string
  • Required: Y
  • Sample value: NO_ACKNOWLEDGMENT
issueDate The date of invoice submit.
  • Type: dateTime
  • Required: Y
  • Sample value: 2015-12-25T12:34:56
title Title displayed on bill and receipt.
  • Type: string
  • Required: Y
  • Sample value: My Sample Store
clientInvoiceId This invoice id refers to the identification number from the merchant's shop.
  • Type: string
  • Required: Y
  • Sample value: Merchant34213421
invoiceRows Contains multiple invoiceRows. See invoiceRow data description.
totalAmount Summary amount of invoice/bill. Consists of a value (in pattern #.##) and a currency. Use ISO standard currency of the country you are in.
  • Value type: decimal
  • Currency type: string
  • Required: Y
  • Sample below:
    <totalAmount>
        <value>149.99</value>
        <currency>SEK</currency>
    </totalAmount>
cashierId Merchant cashier id.
  • Type: string
  • Required: Y
  • Sample value: John00232
footer Footer that you want to display in the users phone receipt.
  • Type: string
  • Required: Y
  • Sample value: RFC:12389234DKJ3
backURL A web-site address to where the SEQR mobile application user will be redirected after a successful payment or after pressing cancel.
  • Type: string
  • Required: N
  • Sample value: http://merchant.com/displayafterpay
notificationUrl An optional notification/confirmation URL. If set SEQR will access this URL after successful payment by user.
  • Type: string
  • Required: N
  • Sample value: http://merchant.com/paymentConfirmation?inv=32923423423
commitReservationTimeout Time (in seconds) while merchant can make a commit of preliminary payment.
  • Type: long
  • Required: N
  • Sample value: 3600

InvoiceRow data

Used to present the payment in the app.

InvoiceRow
Fields Description
itemDescription Description of the item that was sold.
  • Type: string
  • Required: N
  • Sample value: Coca-Cola
itemDiscount Total discount for listed products. Consists of a value (in pattern #.##) and a currency field. Use ISO standard currency signature of the country you are in.
  • Value type: decimal
  • Currency type: string
  • Required: N
  • Sample below:
    <itemDiscount>
        <value>2.50</value>
        <currency>SEK</currency>
    </itemDiscount>
itemEAN Product EAN.
  • Type: string
  • Required: N
  • Sample value: 0076232342123
itemQuantity Should be 1 or more.
  • Type: decimal
  • Required: Y
  • Sample value: 2
itemSKU Product SKU.
  • Type: string
  • Required: N
  • Sample value: 12345-A
itemTaxRate Use the tax rate of your country (in integer format: ##).
  • Type: integer
  • Required: N
  • Sample value: 24
itemTotalAmount Total value for listed products. Consists of a value (in format #.##) and a currency field. Use ISO standard currency signature of the country you are in.
  • Value type: decimal
  • Currency type: string
  • Required: Y
  • Sample below:
    <itemTotalAmount>
        <value>44.99</value>
        <currency>SEK</currency>
    </itemTotalAmount>
itemUnit Use the type of unit based on ISO-20022.
  • Type: string
  • Required: N
  • Sample value: kg
itemUnitPrice Unit price for listed products. Consists of a value (in format #.##) and a currency field. Use ISO standard currency signature of the country you are in.
  • Value type: decimal
  • Currency type: string
  • Required: N
  • Sample below:
    <itemUnitPrice>
        <value>2.99</value>
        <currency>SEK</currency>
    </itemUnitPrice>

Receipt data

Used to receipt information after payment.

Receipt
Fields Description
terminalId The name of the registered terminal.
  • Type: string
  • Sample value: my_terminal
paymentDate The date of the payment.
  • Type: dateTime
  • Sample value: 2015-10-29T10:18:48.663+01:00
invoiceReference The SEQR service reference to the registered invoice.
  • Type: string
  • Sample value: 20151029186719114
paymentReference The SEQR service reference to the registered payment.
  • Type: string
  • Sample value: 2015102910184861801032678
payerTerminalId The id of the terminal registered in SEQR system.
  • Type: string
  • Sample value: d613c5b8428d17248751bc101
receiverName The name of the receiver.
  • Type: string
invoice Invoice data which contains the amount and other invoice information. See invoice description.

Requests and responses

sendInvoice

sendInvoice SOAP request fields

sendInvoice request
Fields Description
context Request context information. See context description.
invoice Invoice data which contains the amount and other invoice information. See invoice description.
tokens The customer tokens applied to this invoice. Can be used for loyalty membership, coupons, etc. Consists of following fields: description (that will be presented to a customer after scaning QR code), id, value (such as card value, coupon code, etc.), status (0 - pending, 1 - used when updated by merchant, 90 - blocked or 99 - invalid, unknown).
Note! The new token (e.g. name of loyalty card) must be added to SEQR system in advance.
  • Description type: string
  • Id type: string
  • Value type: string
  • Status type: integer
  • Required: N
  • Sample below (zero or more repetitions):
    <tokens>
       <description>Loyalty card name</description>
       <id>SOME_CARD</id>
       <status>1</status>
       <value>2610411111110</value>
    </tokens>

sendInvoice SOAP response fields

sendInvoice response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
invoiceQRCode SEQR generated QR Code (used for webshops; not relevant for points of sale).
  • Type: string
  • Sample value: HTTP://SEQR.SE/R1397240460668
resultDescription A textual description of the resultCode.
  • Type: string
  • Sample value: SUCCESS
invoiceReference The SEQR service reference to the registered invoice. This is the invoice reference a merchant should use within getPaymentStatus.
  • Type: string
  • Sample value: 1397240460668

sendInvoice SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:sendInvoice>
       <context>
          <channel>extWS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>8609bf533abf4a20816e8bfe76639521</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>N2YFUhKaB1ZSuVF</password>
       </context>
       <invoice>
        <acknowledgmentMode>NO_ACKNOWLEDGMENT</acknowledgmentMode>
          <title>Some Invoice</title>
          <cashierId>Bob</cashierId>
          <invoiceRows>
            <invoiceRow>
              <itemDescription>Laptop Samsung Ultrabook</itemDescription>
              <itemQuantity>2</itemQuantity>
              <itemSKU>16</itemSKU>
              <itemTaxRate>24</itemTaxRate>
              <itemTotalAmount>
                <currency>SEK</currency>
                <value>500</value>
              </itemTotalAmount>
              <itemUnit></itemUnit>
              <itemUnitPrice>
                <currency>SEK</currency>
                <value>250</value>
              </itemUnitPrice>
            </invoiceRow>
            <invoiceRow>
              <itemDescription>Laptop Apple MacBook Air</itemDescription>
              <itemQuantity>1</itemQuantity>
              <itemSKU>3</itemSKU>
              <itemTaxRate>24</itemTaxRate>
              <itemTotalAmount>
                <currency>SEK</currency>
                <value>1000</value>
              </itemTotalAmount>
              <itemUnit></itemUnit>
              <itemUnitPrice>
                <currency>SEK</currency>
                <value>1000</value>
              </itemUnitPrice>
            </invoiceRow>
          </invoiceRows>
          <totalAmount>
            <currency>SEK</currency>
            <value>1500</value>
          </totalAmount>
          <notificationUrl>http://www.thirdparty.com/notifyMeHere</notificationUrl>
       </invoice>
     </ext:sendInvoice>
   </soapenv:Body>
</soapenv:Envelope>

sendInvoice SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:sendInvoiceResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
            <invoiceQRCode>HTTP://SEQR.SE/R1397222701693</invoiceQRCode>
            <invoiceReference>1397222701693</invoiceReference>
         </return>
      </ns2:sendInvoiceResponse>
   </soap:Body>
</soap:Envelope>

updateInvoice

updateInvoice SOAP request fields

updateInvoice request
Fields Description
context Request context information. See context description.
invoice Invoice data which contains the amount and other invoice information. See invoice description.
invoiceReference The SEQR service reference of the registered invoice.
  • Type: string
  • Sample value: 1397240460668
tokens The customer tokens applied to this invoice. Can be used for loyalty membership, coupons, etc. Contains of: description (that will be presented to a customer after scaning QR code), id, value (such as card value, coupon code, etc.), status (0 - pending, 1 - used when updated by merchant, 90 - blocked or 99 - invalid, unknown).
Note! The new token (e.g. name of loyalty card) must be added to SEQR system in advance.
  • Description type: string
  • Id type: string
  • Value type: string
  • Status type: integer
  • Required: N
  • Sample below (zero or more repetitions):
    <tokens>
       <description>Loyalty card name</description>
       <id>SOME_CARD</id>
       <status>1</status>
       <value>2610411111110</value>
    </tokens>

updateInvoice SOAP response fields

updateInvoice response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of the resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.

updateInvoice SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:updateInvoice>
       <context>
          <channel>extWS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>1234</password>
       </context>
       <invoiceReference>123123</invoiceReference>
       <invoice>
          <title>Some Invoice</title>
          <cashierId>Bob</cashierId>
          <totalAmount>
            <currency>SEK</currency>
            <value>10.22</value>
          </totalAmount>
       </invoice>
     </ext:updateInvoice>
   </soapenv:Body>
</soapenv:Envelope>

updateInvoice SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:updateInvoiceResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:updateInvoiceResponse>
   </soapenv:Body>
</soapenv:Envelope>

getPaymentStatus

getPaymentStatus SOAP request fields

getPaymentStatus request
Fields Description
context Request context information. See context description.
invoice Invoice data which contains the amount and other invoice information. See invoice description.
invoiceReference The SEQR service reference of the registered invoice.
  • Type: string
  • Sample value: 1397240460668
invoiceVersion Version of the invoice. The first time that it uses getPaymentStatus method the client sets the invoiceVersion to zero. The SEQR service increments the invoiceVersion in response message when: the state of the payment status changes or a new buyer token is provided to be considered in the invoice. In subsequent uses of the getPaymentStatus method, the client must use the latest value of invoiceVersion as an acknowledgement that it has received the latest change.
  • Type: integer
  • Required: Y
  • Sample value: 0

getPaymentStatus SOAP response fields

getPaymentStatus response
Fields Description
ersReference The unique reference generated by the SEQR service once the invoice has been paid (null for all other invoiceStatus than PAID).
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
status Status of the invoice.
  • 0 - pending usage (when sent from SEQR)
  • ISSUED - invoice is issued and waiting for payment
  • PAID - invoice is paid
  • PARTIALLY_PAID - invoice is partially paid
  • PENDING_ISSUER_ACKNOWLEDGE - payment is updated and waiting for issuer acknowledgement
  • CANCELED - invoice is canceled
  • FAILED - invoice payment has failed
  • RESERVED - invoice amount is reserved
Note! If getPaymentStatus is not queried within 20 seconds after a successful payment, SEQR will assume that cash register is not notified of the successful payment and will reverse the transaction.
  • Type: string
  • Sample value: ISSUED
receipt Receipt information. See receipt description.

getPaymentStatus SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:getPaymentStatus>
       <context>
         <channel>extWS</channel>
         <clientComment>comment</clientComment>
         <clientId>testClient</clientId>
         <clientReference>12345</clientReference>
         <clientRequestTimeout>0</clientRequestTimeout>
         <initiatorPrincipalId>
           <id>87e791f9e24148a6892c52aa85bb0331</id>
           <type>TERMINALID</type>
         </initiatorPrincipalId>
         <password>123456</password>
       </context>
       <invoiceVersion>0</invoiceVersion>
       <invoiceReference>123123</invoiceReference>
     </ext:getPaymentStatus>
   </soapenv:Body>
</soapenv:Envelope>

getPaymentStatus SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:getPaymentStatusResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
        <return>
           <resultCode>0</resultCode>
           <resultDescription>SUCCESS</resultDescription>
           <status>ISSUED</status>
           <version>1</version>
        </return>
      </ns2:getPaymentStatusResponse>
   </soap:Body>
</soap:Envelope>

submitPaymentReceipt

submitPaymentReciept SOAP request fields

This method confirms that the payment has been acknowledged and adds a receipt from the point of sale as html. This receipt won’t appear in the app automatically. Please contact us if you are interested in using a customized receipt in the app.

submitPaymentReciept request
Fields Description
context Request context information. See context description.
ersReference Reference of the payment for which the receipt is applicable.
  • Type: string
  • Sample value: 1397240460668
receiptDocument Receipt document, containing the full details of the receipt (mimeType, receiptData, receiptType - all mandatory). Preferably in ARTS Receipt XML/HTML format.
  • MimeType type: string
  • ReceiptData type: base64Binary
  • ReceiptType type: string
  • Sample value: see request example below.

submitPaymentReceipt SOAP response fields

submitPaymentReciept response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.

submitPaymentReceipt SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:submitPaymentReceipt>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
       <ersReference>2012050100000000000000001</ersReference>
       <receiptDocument>
          <mimeType>plain/xml</mimeType>
          <receiptData>Cjw/eG1sIHZlcnNpb249IjEuMCIgZW5jb2Rpbmc9IlVURi04Ij8+Cjx</receiptData>
          <receiptType>xxx</receiptType>
       </receiptDocument>
     </ext:submitPaymentReceipt>
   </soapenv:Body>
</soapenv:Envelope>

submitPaymentReceipt SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:submitPaymentReceiptResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
           <ersReference>2012050100000000000000002</ersReference>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:submitPaymentReceiptResponse>
   </soapenv:Body>
</soapenv:Envelope>

cancelInvoice

cancelInvoice SOAP request fields

cancelInvoice request
Fields Description
context Request context information. See context description.
invoiceReference Reference of the invoice to be canceled.
  • Type: string
  • Sample value: 1397240460668

cancelInvoice SOAP response fields

cancelInvoice response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.

cancelInvoice SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:cancelInvoice>
       <context>
          <channel>extWS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>1234</password>
       </context>
       <invoiceReference>123123</invoiceReference>
     </ext:cancelInvoice>
   </soapenv:Body>
</soapenv:Envelope>

cancelInvoice SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:cancelInvoiceResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:cancelInvoiceResponse>
   </soapenv:Body>
</soapenv:Envelope>

commitReservation

commitReservation SOAP request fields

commitReservation request
Fields Description
context Request context information. See context description.
amount Commited amount and currency. Consists of currency (ISO standard currency signature) and value (in format #.##).
  • Value type: decimal
  • Currency type: string
  • Required: N
  • Sample below:
    <amount>
        <value>2.99</value>
        <currency>SEK</currency>
    </amount>
invoiceReference Reference of the invoice that refers to the commitment.
  • Type: string
  • Sample value: 1397240460668

commitReservation SOAP response fields

commitReservation response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS

commitReservation SOAP request example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:commitReservation xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <context>
            <clientRequestTimeout>0</clientRequestTimeout>
            <initiatorPrincipalId>
               <id>87e791f9e24148a6892c52aa85bb0331</id>
               <type>TERMINALID</type>
            </initiatorPrincipalId>
            <password>1234</password>
         </context>
         <amount>
            <currency>SEK</currency>
            <value>5</value>
         </amount>
         <invoiceReference>123123</invoiceReference>
      </ns2:commitReservation>
   </soap:Body>
</soap:Envelope>

commitReservation SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:commitReservationResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:commitReservationResponse>
   </soap:Body>
</soap:Envelope>

refundPayment

refundPayment SOAP request fields

refundPayment request
Fields Description
context Request context information. See context description.
ersReference Reference of the payment to be refunded.
  • Type: string
  • Sample value: 2015050100000000000000002
invoice Invoice data which contains the amount and other invoice information. See invoice description.

refundPayment SOAP response fields

refundPayment response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Reference to the payment that is refunded.

refundPayment SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:refundPayment>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
       <ersReference>2012050100000000000000001</ersReference>
       <invoice>
          <title>Refund</title>
          <cashierId>Bob</cashierId>
          <totalAmount>
            <currency>SEK</currency>
            <value>10.22</value>
          </totalAmount>
       </invoice>
     </ext:refundPayment>
   </soapenv:Body>
</soapenv:Envelope>

refundPayment SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:refundPaymentResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
          <ersReference>2012050100000000000000002</ersReference>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:refundPaymentResponse>
   </soapenv:Body>
</soapenv:Envelope>

registerTerminal

registerTerminal SOAP request fields

registerTerminal request
Fields Description
context Request context information. See context description.
externalTerminalId The identifier of the terminal in the client system.
  • Type: string
  • Required: Y
  • Sample value: Store 111/Till 4
password Password of the registered terminal for future communications with the SEQR service.
  • Type: string
  • Required: Y
  • Sample value: my_terminal_pass
name The name to appear on the buyer’s mobile device.
  • Type: string
  • Required: Y
  • Sample value: My restaurant, cash register 2

registerTerminal SOAP response fields

registerTerminal response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.
terminalId The newly generated unique identifier in SEQR system for this terminal. This identifier should be used in future communications of this terminal towards the SEQR service.
  • Type: string
  • Sample value: 87e791f9e24148a6892c52aa85bb0331

registerTerminal SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:registerTerminal>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>fredellsfisk</id>
            <type>RESELLERUSER</type>
            <userId>9900</userId>
          </initiatorPrincipalId>
          <password>2009</password>
       </context>
       <externalTerminalId>Shop 1/POS 2</externalTerminalId>
       <password>secret</password>
       <name>My Shop's Name</name>
     </ext:registerTerminal>
   </soapenv:Body>
</soapenv:Envelope>

registerTerminal SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:registerTerminalResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
            <terminalId>87e791f9e24148a6892c52aa85bb0331</terminalId>
         </return>
      </ns2:registerTerminalResponse>
   </soapenv:Body>
</soapenv:Envelope>

unregisterTerminal

unregisterTerminal SOAP request fields

unregisterTerminal request
Fields Description
context Request context information. See context description. Contains terminalId of the terminal to deregister.

unregisterTerminal SOAP response fields

unregisterTerminal response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.

unregisterTerminal SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:unregisterTerminal>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
     </ext:unregisterTerminal>
   </soapenv:Body>
</soapenv:Envelope>

unregisterTerminal SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:registerTerminalResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:unregisterTerminalResponse>
   </soapenv:Body>
</soapenv:Envelope>

assingSeqrId

assignSeqrId SOAP request fields

assignSeqrId request
Fields Description
context Request context information. See context description. The terminalId within is the terminal to which assign seqrId.
seqrId An alphanumeric code to assign to a terminal (POS). It is used to generate a static QR code.
  • Type: alphanumeric
  • Sample value: my_qr_code_string

assignSeqrId SOAP response fields

assignSeqrId response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
ersReference Not used, will be null.

assignSeqrId SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:assignSeqrId>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>87e791f9e24148a6892c52aa85bb0331</id>
            <type>TERMINALID</type>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
       <seqrId>ABC123456</seqrId>
     </ext:assignSeqrId>
   </soapenv:Body>
</soapenv:Envelope>

assignSeqrId SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:assignSeqrIdResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
         </return>
      </ns2:assignSeqrIdResponse>
   </soapenv:Body>
</soapenv:Envelope>

markTransactionPeriod

markTransactionPeriod request fields

markTransactionPeriod request
Fields Description
context Request context information. See context description.
parameters An optional key-value parameter map that can be used in processing the request.
  • Sample value: see request per terminal reconciliation example.

markTransactionPeriod response fields

markTransactionPeriod response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
transactionPeriodId The reference of this operation.
  • Type: string
  • Sample value: 2015100916014994401047376

markTransactionPeriod SOAP request example, per shop reconciliation

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:markTransactionPeriod>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>fredellsfisk</id>
            <type>RESELLERUSER</type>
            <userId>9900</userId>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
     </ext:markTransactionPeriod>
   </soapenv:Body>
</soapenv:Envelope>

markTransactionPeriod SOAP response example, per shop reconciliation

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:markTransactionPeriodResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
            <transactionPeriodId>2012053119463656301000002</transactionPeriodId>
         </return>
      </ns2:markTransactionPeriodResponse>
   </soapenv:Body>
</soapenv:Envelope>

markTransactionPeriod SOAP request example, per terminal reconciliation

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:markTransactionPeriod>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>fredellsfisk</id>
            <type>RESELLERUSER</type>
            <userId>9900</userId>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
       <parameters>
        <parameter>
          <entry>
             <key>TERMINALID</key>
             <value>2469e0bf14214797880cafb0eda1b535</value>
          </entry>
        </parameter>
       <parameters>
     </ext:markTransactionPeriod>
   </soapenv:Body>
</soapenv:Envelope>

markTransactionPeriod SOAP response example, per terminal reconciliation

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:markTransactionPeriodResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
            <transactionPeriodId>2012053119463656301000002</transactionPeriodId>
         </return>
      </ns2:markTransactionPeriodResponse>
   </soapenv:Body>
</soapenv:Envelope>

executeReport

For SOAP examples of different reports, refer to Reporting.

executeReport SOAP request fields

executeReport request
Fields Description
context Request context information. See context description.
reportId The identifier of the report that should be executed/produced.
  • Type: string
  • Required: Y
  • Sample value: SOME_REPORT
language The report language (null if the default language is to be used).
  • Type: string
parameters An optional key-value parameter map that can be used in processing the request.
  • Sample value: see markTransactionPeriod request per terminal reconciliation example above.

executeReport SOAP response fields

executeReport response
Fields Description
resultCode Response result code.
  • Type: integer
  • Max-length: 2
  • Sample value: 0
resultDescription A textual description of resultCode.
  • Type: string
  • Sample value: SUCCESS
report The executed/produced report, in binary and plain text form, if available. Consists of: content, contentString, mimeType, title.
  • Content type: base64Binary
  • ContentString type: string
  • MimeType type: string
  • Title type: string
  • Sample: see response example below.

executeReport SOAP request example

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
 xmlns:ext="http://external.interfaces.ers.seamless.com/">
   <soapenv:Header/>
   <soapenv:Body>
     <ext:executeReport>
       <context>
          <channel>WS</channel>
          <clientComment>comment</clientComment>
          <clientId>testClient</clientId>
          <clientReference>12345</clientReference>
          <clientRequestTimeout>0</clientRequestTimeout>
          <initiatorPrincipalId>
            <id>fredellsfisk</id>
            <type>RESELLERUSER</type>
            <userId>9900</userId>
          </initiatorPrincipalId>
          <password>secret</password>
       </context>
       <reportId>SOME_REPORT</reportId>
     </ext:executeReport>
   </soapenv:Body>
</soapenv:Envelope>

executeReport SOAP response example

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
   <soap:Body>
      <ns2:executeReportResponse xmlns:ns2="http://external.interfaces.ers.seamless.com/">
         <return>
            <resultCode>0</resultCode>
            <resultDescription>SUCCESS</resultDescription>
            <report>
               <content>MTE1Nzky</content>
               <contentString>115792</contentString>
               <mimeType>text/plain</mimeType>
               <title>Number of transfers today</title>
            </report> 
         </return>
      </ns2:executeReportResponse>
   </soapenv:Body>
</soapenv:Envelope>

Result codes

Note that this list points out the responses that are relevant, with the API request(s) that may issue the response. The other response codes are unrelevant but could occur in some cases.

Code Description Detailed description Request that may issue this response
0 SUCCESS Given operation ended successfully All requests
20 AUTHENTICATION_FAILED Wrong password All requests
21 ACCESS_DENIED Password assigned to terminalId is less than 4 characters unregisterTerminal, sendInvoice, getPaymentStatus
23 INVALID_ERS_REFERENCE Given ERS reference number cannot be found refundPayment
29 INVALID_INITIATOR_ PRINCIPAL_ID Given id for TERMINALID in initiatorPrincipalId cannot be found All requests
37 INITIATOR_PRINCIPAL_ NOT_FOUND Given id or userId for RESELLERUSER in initiatorPrincipalId section not found in SEQR All requests
49 INVALID_INVOICE_ DATA For example wrong currency sendInvoice, updateInvoice
50 CANNOT_CANCEL_PAID_ INVOICE Invoice with given reference number has already been paid cancelInvoice
51 CANNOT_CANCEL_INVOICE_ IN_PROGRESS   cancelInvoice
53 INVALID_SEQR_ID Not alphanumeric string has been used or given seqrID has already been assigned to other terminal. Tip: use your own unique prefix for seqrID. Example mymerchantname31231231 assignSeqrId
54 INVALID_INVOICE_ REFERENCE Invoice with given reference number can’t be found for given terminal id getPaymentStatus
64 INVALID_NOTIFICATION_ URL Not valid notificationUrl (e.g not starting with http://) sendInvoice, updateInvoice, refundPayment
90 SYSTEM_ERROR Unclassified errors All requests
91 UNSUPPORTED_OPERATION The method is not supported by the service All requests
94 SERVICE_UNAVAILABLE External backend system unavailable (e.g. Bank system) All requests
95 INVOICE_ALREADY_CANCELED Invoice with given reference number is already canceled through cancelInvoice call cancelInvoice
96 INVOICE_STATE_NOT_RESERVED The invoice state is not reserved for doing final or actual transaction commitReservation
97 RESELLER_NOT_ALLOWED_ TO_DO_REFUND Refund option is not allowed for that reseller refundPayment
98 SUM_OF_REFUNDS_CAN_NOT_ BE_MORE_THAN_ORIGINAL_ TRANSACTION Sum of the refunds is more than the original transaction refundPayment
99 RECEIVER_ACCOUNT_DOES_ NOT_ALLOW_REFUNDS External backend does not allow refund (e.g. receiver’s banking system) refundPayment