PayTraq - A Cloud-based Business Suite - more than just online accounting

PayTraq POS API

Current Version: v1.1
Last Updated: 22 Nov, 2017

Overview

The PayTraq POS API has been deleloped as the extension of our REST 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}

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: text/xml" header.
All success responses are also given in XML format.

Examples
GET
curl -v -X GET https://go.paytraq.com/api/pos/{ConnectorID}/{APICall} \
-H "Content-Type:text/xml" \
-H "APISignature: {APISignature}"
POST
curl -v https://go.paytraq.com/api/pos/{ConnectorID}/{APICall} \
-H "Content-Type:text/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.
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.

Every successful request should always return HTTP 200 OK code.

API Conventions

  • 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.

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.

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


<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>
      </LineItem>
      ...
   </LineItems>
   <Adjustments>
      <Adjustment>
         <Amount></Amount>
         <Description />
         <TypeID></TypeID>
         <PctOrAmount></PctOrAmount>
      </Adjustment>
      ...
   </Adjustments>
   <ShippingCharge>
      <Amount></Amount>
   </ShippingCharge>
   <Payments>
      <Cash>
         <Amount></Amount>
         <Narration />
      </Cash>
      <Card>
         <Amount></Amount>
         <Narration />
      </Card>
   </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)
  • 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 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


<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


<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