PayTraq
PayTraq.com
API v1.3 · Updated 10 December 2023

PayTraq POS API

Connect point-of-sale systems to synchronize sales receipts and cash operations.

Read the docs
https://go.paytraq.com/api/pos/{ConnectorID}/
InterfacePOS API
PayloadXML
TransportHTTPS

Overview

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

Requests and Responses

All API requests and responses must be transmitted over HTTPS.
The API supports the following HTTP methods: GET and POST.
All POST requests must:

  • send the request body in XML format;
  • include the following header:

HTTP header
Content-Type: application/xml

Unless otherwise specified, successful responses are returned in XML format.

Authentication

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.

Request Example
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 Limits

  • API Rate Limit: 1 request per second at an average, with bursts not exceeding 5 requests
  • The daily API limit is 5000 requests per 24 hours.
    If you intend to make additional requests, please reach out to us beforehand by providing a description of your use case (Additional fees may apply).
    Excessive API usage may lead to the disabling of API access.

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

GETGet Client List

Request

XML / HTTP
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

XML / HTTP
<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

GETGet Product List

Request

XML / HTTP
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

XML / HTTP
<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

GETGet Product Image

Request

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

Response

XML / HTTP
Image (JPEG/PNG)

Back to API Calls

POSTAdd Sales Receipt

Request

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

Payload

XML / HTTP
<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

XML / HTTP
<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

POSTCash Out

Request

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

Payload

XML / HTTP
<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

XML / HTTP
<Response>
   <DocumentID></DocumentID>
</Response>
Tag Description
<DocumentID> Unique system identifier for payment document

Back to API Calls

POSTCash In

Request

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

Payload

XML / HTTP
<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

XML / HTTP
<Response>
   <DocumentID></DocumentID>
</Response>
Tag Description
<DocumentID> Unique system identifier for payment document

Back to API Calls

Copied to clipboard