PayTraq POS API

Current Version: v1.3
Last Updated: 10 Dec, 2023

Overview

The PayTraq POS API has been deleloped as the extension of our API and is designed to be used primary by POS systems. POS API is available over HTTPS by using the provided connector endpoint: https://go.paytraq.com/api/pos/{ConnectorID}

Getting Started

POS API uses PayTraq POS Connector that should be activated and set up by going to Money -> Cash Accounts -> POS Connectors. Actual endpoint address and API signature that are required for API calls can be obtained from the POS connector.

The header of any request should always contain {APISignature} parameter that is required for authentication.

POS API Access can be blocked at any time by deactivating associated connector.

The transmission of all API requests and responses needs to be made over HTTPS.
All POST requests should be made in XML format with "Content-Type: application/xml" header.
All success responses are also given in XML format.

Examples

curl -v -X GET https://go.paytraq.com/api/pos/{ConnectorID}/{APICall} \
-H "APISignature: {APISignature}"
curl -v https://go.paytraq.com/api/pos/{ConnectorID}/{APICall} \
-H "Content-Type:application/xml" \
-H "APISignature: {APISignature}" \
-d "{RequestBody}"

List of Return Codes and Statuses

Code Status Definition
200 OK The request has succeeded.
400 Bad Request The request could not be understood by the server due to malformed syntax, invalid values or validation issues.
401 Unauthorized API credentials have not been provided or company license key is not valid.
403 Forbidden Request is not permitted and has been forbidden by the server due to incorrect data, validation issues or authorization failure.
404 Not Found The server has not found anything matching the Request-URI.
429 Too Many Requests The user has sent too many requests in a given amount of time ("rate limiting").
500 Internal Server Error The server encountered an unexpected condition which prevented it from fulfilling the request.
501 Not Implemented The method called has not been implemented yet.
503 Service Unavailable The server is currently unable to handle the request due to maintenance of the server. This is a temporary condition which will be alleviated after some delay.

API Convensions

  • Decimal values should be passed with dot separator e.g. 10.90
  • Dates should be passed in the following format YYYY-MM-DD e.g. 2014-01-30
  • Boolean values should be false or true, 0 or 1 is not permitted.
  • API Rate Limit: 1 request per second at an average, with bursts not exceeding 5 requests

Optional Parameters

GET requests that are used to retrieve clients and products can contain some optional parameters:

  • Pagination
    By default only the first 100 records are returned.
    To utilise paging, append a page parameter to the URL e.g. &page=0.
    If there are 100 records in the response you will need to check if there is any more data by fetching the next page e.g. &page=1 and continuing this process until no more results are returned.
    Note: Page values start with 0.
  • Filtering
    A filter can be applied to the results by appending a query parameter to the URL e.g. &query=John
    Possible values depend on request and retrieved object types.
    Example:
    List of clients can be filtered by name or email.
    List of products - by name, SKU or barcode.
     No filters are applied by default.

API Calls

Get Client List

Request

GET https://go.paytraq.com/api/pos/{ConnectorID}/clients

Result list is sorted by client name in ascending order.
Optional parameters are available. Results can be filtered by client name or email.

Response


<Clients>
   <Client>
      <ClientID></ClientID>
      <Name />
      <Email />
      <Type></Type>
      <Status></Status>
      <RegNumber />
      <VatNumber />
      <LegalAddress>
         <Address />
         <Zip />
         <Country></Country>
      </LegalAddress>
      <Phone />
      <ClientGroup>
         <GroupID />
         <GroupName />
      </ClientGroup>
   </Client>
   ...
</Clients>

Tag Description
<ClientID> Unique system identifier for client
<Type> Possible values:
  • 1 - Individual
  • 2 - Corporate
<Status> Possible values:
  • 1 - Prospective
  • 2 - Active
  • 3 - Inactive
<Country> 2-letter ISO country code

Back to API Calls

Get Product List

Request

GET https://go.paytraq.com/api/pos/{ConnectorID}/products

Result list is sorted by product name in ascending order.
Optional parameters are available. Results can be filtered by product name, SKU or barcode.

Response


<Products>
   <Product>
      <ItemID></ItemID>
      <Name></Name>
      <Code></Code>
      <Unit>
         <UnitID></UnitID>
         <UnitName></UnitName>
      </Unit>
      <Description />
      <Status></Status>
      <Type></Type>
      <BarCode />
      <Weight></Weight>
      <Group>
         <GroupID />
         <GroupName />
      </Group>
      <Inventory>
         <Qty></Qty>
      </Inventory>
      <Price>
         <GrossAmount></GrossAmount>
         <TaxRate></TaxRate>
         <Currency></Currency>
         <Discount></Discount>
      </Price>
   </Product>
   ...
</Products>

Tag Description
<ItemID> Unique system identifier for product
<Code> Product code (SKU)
<UnitID> Unique system identifier for unit of measure
<Status> Possible values:
  • 1 - Active
  • 2 - Discontinued
<Type> Possible values:
  • 1 - Stockable
  • 2 - Consumable
  • 3 - Fixed asset
<GroupID> Unique system identifier for product group
<Qty> Quantity available
<GrossAmount> Gross price (tax incl.)
<TaxRate> Tax rate
<Discount> Promo discount in %

Back to API Calls

Get Product Image

Request

GET https://go.paytraq.com/api/pos/{ConnectorID}/productImage/{ItemID}
Parameter Description
ItemID Unique system identifier for product

Response

Image (JPEG/PNG)

Back to API Calls

Add Sales Receipt

Request

POST https://go.paytraq.com/api/pos/{ConnectorID}/sale

Payload


<Sale>
   <Header>
      <Operation></Operation>
      <Document>
         <DocumentDate></DocumentDate>
         <DocumentRef></DocumentRef>
         <ClientID/>
         <Client>
            <ClientName></ClientName>
            <ClientRegNumber></ClientRegNumber>
            <ClientTaxNumber></ClientTaxNumber>
            <ClientEmail></ClientEmail>
            <BillingAddress>
              <Address></Address>
              <Zip></Zip>
              <Country></Country>
            </BillingAddress>
            <IsCompany></IsCompany>
         </Client>
      </Document>
      <Comment />
      <ShippingData>
         <ShippingAddress>
            <ShipTo></ShipTo>
            <Address></Address>
            <Zip></Zip>
            <Country></Country>
         </ShippingAddress>
      </ShippingData>
   </Header>
   <LineItems>
      <LineItem>
         <ItemID/>
         <Item>
            <ItemCode></ItemCode>
            <ItemBarCode></ItemBarCode>
            <ItemName></ItemName>
         </Item>
         <Qty></Qty>
         <Price></Price>
         <LineDiscount></LineDiscount>
         <TaxKey>
             <TaxKeyID></TaxKeyID> 
         </TaxKey>    
      </LineItem>
      ...
   </LineItems>
   <Adjustments>
      <Adjustment>
         <Amount></Amount>
         <Description />
         <TypeID></TypeID>
         <PctOrAmount></PctOrAmount>
      </Adjustment>
      ...
   </Adjustments>
   <ShippingCharge>
      <Amount></Amount>
      <TaxKey>
         <TaxKeyID></TaxKeyID> 
      </TaxKey> 
   </ShippingCharge>
   <Payments>
      <Cash>
         <Amount></Amount>
         <Narration />
      </Cash>
      <Card>
         <Amount></Amount>
         <Narration />
      </Card>
      <GiftCard>
         <Amount></Amount>
         <Narration />
      </GiftCard>
   </Payments>
</Sale>

Most tags are optional.
Prices and other amounts should be passed as tax inclusive and in the balance currency.
In case of refund or product return passed qty should be negative.
Payments are always positive.

Tag Description
<Operation> Possible values:
  • sell_goods - Selling Goods (Default)
  • sell_services - Selling Services
  • other_income - Other Income
<DocumentDate> Receipt date.
Should be passed in the following format YYYY-MM-DD e.g. 2014-01-30
If not passed the current date (UTC) will be applied.
<DocumentRef> Receipt No.
<ClientID> Unique system identifier for client.
If not passed a client will be looked up by <ClientName> or by <ClientRegNumber>
<ClientName> Client name
<BillingAddress> Client billing address
<IsCompany> Boolean value (false | true)
<ShippingAddress> Client shipping address
<ItemID> Unique system identifier for product.
If not passed an item will be looked up by <ItemCode>, <ItemBarCode> or by <ItemName>
<ItemCode> Product SKU
<ItemName> Product name
<LineDiscount> Line discount in %
<TypeID> Possible values:
  • charge - Charge
  • discount - Discount
<PctOrAmount> Possible values:
  • pct - Percent
  • amount - Amount
<Cash> Amount paid by cash
<Card> Amount paid by bank card
<GiftCard> Amount paid by gift card

Response


<Response>
   <DocumentID></DocumentID>
   <DocumentStatus></DocumentStatus>
   <AmountDue></AmountDue>
   <PostResult>
      <ResultCode></ResultCode>
      <Msg></Msg>  
   </PostResult>
</Response>

Tag Description
<DocumentID> Unique system identifier for sales document
<DocumentStatus> Possible values:
  • draft - Draft
  • wait_payment - Waiting for Payment
  • part_paid - Partially Paid
  • paid - Paid
Should be paid if request is succeeded
<AmountDue> Should be 0 if request is succeeded

Back to API Calls

Cash Out

Request

POST https://go.paytraq.com/api/pos/{ConnectorID}/cashOut

Payload


<MoneyTransfer>
   <CashOut>
      <Amount></Amount>
      <Date></Date>
      <Employee />
      <Narration />
   </CashOut>
</MoneyTransfer>

Tag Description
<Amount> Amount to be collected from cash account (POS)
<Date> Date of operation.
Should be passed in the following format YYYY-MM-DD e.g. 2014-01-30
If not passed the current date (UTC) will be applied.
<Employee> Cashier's full name

Response


<Response>
   <DocumentID></DocumentID>
</Response>

Tag Description
<DocumentID> Unique system identifier for payment document

Back to API Calls

Cash In

Request

POST https://go.paytraq.com/api/pos/{ConnectorID}/cashIn

Payload


<MoneyTransfer>
   <CashIn>
      <Amount></Amount>
      <Date></Date>
      <Employee />
      <Narration />
   </CashIn>
</MoneyTransfer>

Tag Description
<Amount> Amount to be added to cash account (POS)
<Date> Date of operation.
Should be passed in the following format YYYY-MM-DD e.g. 2014-01-30
If not passed the current date (UTC) will be applied.
<Employee> Cashier's full name

Response


<Response>
   <DocumentID></DocumentID>
</Response>

Tag Description
<DocumentID> Unique system identifier for payment document

Back to API Calls