PayTraq API

https://paytraq.com/api
Admin
The PayTraq API is a RESTful web service that allows programmatic access over HTTPS to manage...
Tokens:11,690
Snippets:97
Trust Score:7.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Initiate Billing Process Request

Source: https://paytraq.com/api/billing.html

The endpoint used to start the billing process for invoice generation.

```HTTP
POST /api/billing/run
```

--------------------------------

### Execute POS API Request with cURL

Source: https://paytraq.com/api/pos.html

Example of a POST request using cURL, including the required Content-Type and APISignature headers.

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

--------------------------------

### Initiate Billing Process Request

Source: https://paytraq.com/api/billing.html

JSON payload for starting a billing process, including period details, webhook URL, and a list of client invoices with line items.

```JSON
{
  "billing": {
   "period_id": "2",
   "invoice_date": "2021-04-01",
   "webhook_url": "https://webhook.site/7e73bced-da2b-4ad3-9910-3c9efd956d77",
   "invoices": [
     {
      "client": {
           "client_correlation_id": "1",
           "client_name": "Milana Rush",
           "client_email": "bugs@paytraq.com"
         },
        "invoice_correlation_id": "1",
        "items": [
            {
            "item_name": "Management services",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_price": "5.23"
            },
            {
            "item_name": "Management fee",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_price": "10.80"
            },
            {
            "item_name": "Street lighting D2",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_price": "2.28"
            },
            {
            "item_name": "Savings fund",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_tax_rate": "0",
            "item_price": "9.25"
            },
            {
            "item_name": "Cold water and sewage",
            "item_qty": "15",
            "item_uom": "m3",
            "item_price": "1.50"
            },
            {
            "item_name": "Road maintenance fund",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_tax_rate": "0",
            "item_price": "5"
            }
          ]
        },
        {
        "client": {
           "client_name": "Mateo Leverenz"
         },
        "items": [
            {
            "item_name": "Management services",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_price": "5.23"
            },
            {
            "item_name": "Management fee",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_price": "10.80"
            },
            {
            "item_name": "Savings fund",
            "item_qty": "1",
            "item_uom": "pcs.",
            "item_tax_rate": "0",
            "item_price": "9.25"
            },
            {
            "item_name": "Cold water and sewage",
            "item_qty": "10",
            "item_uom": "m3",
            "item_price": "1.50"
            },
            {
            "item_name": "Other services",
            "item_qty": "1",
            "item_price": "2.50"
            }
          ]
        }
      ]
   }
}
```

--------------------------------

### GET /api/pos/{ConnectorID}/productImage/{ItemID}

Source: https://paytraq.com/api/pos.html

Retrieves the image for a specific product by its ItemID.

```APIDOC
## GET /api/pos/{ConnectorID}/productImage/{ItemID}

### Description
Retrieves the image file (JPEG/PNG) for a specific product.

### Method
GET

### Endpoint
https://go.paytraq.com/api/pos/{ConnectorID}/productImage/{ItemID}

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - Unique identifier for the connector.
- **ItemID** (string) - Required - Unique system identifier for the product.

### Response
#### Success Response (200)
- **Image** (Binary) - JPEG or PNG image data.
```

--------------------------------

### Paytraq XML Schema Example

Source: https://paytraq.com/api/direct.html

A template for the Paytraq XML format. Required fields include DocumentRef, SaleType, Operation, SupplierName, LineItem, and Currency.

```xml
<Sale>
  <Header>
    <Document>
      <DocumentDate></DocumentDate>
      <DocumentRef></DocumentRef>
      <SupplierData>
        <SupplierName></SupplierName>
        <SupplierRegNumber></SupplierRegNumber>
        <SupplierTaxNumber></SupplierTaxNumber>
      </SupplierData>
      <ClientData>
        <ClientName></ClientName>
        <ClientRegNumber></ClientRegNumber>
        <ClientTaxNumber></ClientTaxNumber>
      </ClientData>
    </Document>
    <SaleType></SaleType>
    <Operation></Operation>
    <Currency></Currency>
    <TaxBasis></TaxBasis>
    <IncludeTax></IncludeTax>
    <PayTerm>
      <PayTermType></PayTermType>
      <PayTermDays></PayTermDays>
    </PayTerm>
    <DateDue></DateDue>
    <Deposit></Deposit>
    <Comment></Comment>
    <PaymentMethod></PaymentMethod>
    <ShippingData>
      <ShippingType></ShippingType>
    </ShippingData>
  </Header>
  <LineItems>
    <LineItem>
      <Item>
        <ItemCode></ItemCode>
        <ItemBarCode></ItemBarCode>
        <ItemName></ItemName>
      </Item>
      <Description></Description>
      <Qty></Qty>
      <Price></Price>
      <LineDiscount></LineDiscount>
      <LineTotal></LineTotal>
      <Unit>
        <UnitName></UnitName>
      </Unit>
      <TaxKey>
        <TaxRate></TaxRate>
      </TaxKey>
    </LineItem>
  </LineItems>
  <Adjustments>
      <Adjustment>
         <Amount></Amount>
         <Description />
         <TypeID></TypeID>
         <PctOrAmount></PctOrAmount>
      </Adjustment>
   </Adjustments>
  <ShippingCharge>
    <Amount></Amount>
  </ShippingCharge>
  <Totals>
    <GrossAmount></GrossAmount>
    <NetAmount></NetAmount>
  </Totals>
  <Attachment>
    <PDFBase64></PDFBase64>
  </Attachment>
</Sale>
```

--------------------------------

### GET api/billing/{run_id}

Source: https://paytraq.com/api/billing.html

Retrieves the status of a billing process. If the process is complete, it returns details about the generated invoices.

```APIDOC
## GET api/billing/{run_id}

### Description
Check the status of a billing process and retrieve generation results.

### Method
GET

### Endpoint
api/billing/{run_id}

### Parameters
#### Path Parameters
- **run_id** (string) - Required - Billing process ID

### Response
#### Success Response (200)
- **run_id** (string) - Billing process ID
- **status** (string) - Current status of the process
- **created_at** (string) - Creation timestamp
- **completed_at** (string) - Completion timestamp (if finished)
- **period_from** (string) - Start of billing period (if finished)
- **period_till** (string) - End of billing period (if finished)
- **invoices** (array) - List of generated invoices (if finished)

#### Response Example
{
  "run_id": "123",
  "status": "completed",
  "created_at": "2023-01-01T00:00:00Z",
  "completed_at": "2023-01-01T00:05:00Z",
  "period_from": "2022-12-01",
  "period_till": "2022-12-31",
  "invoices": [
    {
      "client_id": "C1",
      "invoice_id": "INV-001",
      "invoice_ref": "REF-001",
      "total": 100.00,
      "status": "draft",
      "pdf_link": "https://api.paytraq.com/pdf/1",
      "is_sent": false
    }
  ]
}
```

--------------------------------

### GET /api/pos/{ConnectorID}/products

Source: https://paytraq.com/api/pos.html

Retrieves a list of products, sorted by name. Supports filtering by product name, SKU, or barcode.

```APIDOC
## GET /api/pos/{ConnectorID}/products

### Description
Retrieves a list of products sorted by name in ascending order. Results can be filtered by product name, SKU, or barcode.

### Method
GET

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

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - Unique identifier for the connector.

### Response
#### Success Response (200)
- **Products** (XML) - A list of product objects containing details like ItemID, Name, Code, Unit, Status, Type, BarCode, Weight, Group, Inventory, and Price.
```

--------------------------------

### GET /api/billing/companies

Source: https://paytraq.com/api/billing.html

Retrieves a list of companies available to the authenticated user or application.

```APIDOC
## GET /api/billing/companies

### Description
Retrieves the list of companies available to the authenticated user or application. Requires the CompanyID header for authentication.

### Method
GET

### Endpoint
/api/billing/companies

### Response
#### Success Response (200)
- **companies** (array) - A list of company objects.

#### Response Example
{
   "companies": [
    {
     "company_id": "_company_id",
     "company_name": "_company_name"
    }
   ]
  }
```

--------------------------------

### Retrieve Billing Process Status

Source: https://paytraq.com/api/billing.html

Use this GET request to check the status of a specific billing process using its run ID.

```HTTP
GET api/billing/{run_id}
```

--------------------------------

### GET /api/pos/{ConnectorID}/clients

Source: https://paytraq.com/api/pos.html

Retrieves a list of clients, sorted by name. Supports filtering by client name or email.

```APIDOC
## GET /api/pos/{ConnectorID}/clients

### Description
Retrieves a list of clients sorted by name in ascending order. Results can be filtered by client name or email.

### Method
GET

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

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - Unique identifier for the connector.

### Response
#### Success Response (200)
- **Clients** (XML) - A list of client objects containing details like ClientID, Name, Email, Type, Status, and address information.
```

--------------------------------

### Register Public Client

Source: https://paytraq.com/api/billing.html

Register a new client application for the Authorization Code flow.

```bash
curl -s https://go.paytraq.com/oauth/register \
  -H 'Content-Type: application/json' \
  -d '{
    "client_name": "Client Application Name",
    "redirect_uris": ["http://localhost:8080/callback"],
    "scope": "api"
  }'
```

--------------------------------

### POST /api/billing/run

Source: https://paytraq.com/api/billing.html

Initiates the billing process for invoice generation.

```APIDOC
## POST /api/billing/run

### Description
Starts the billing process for generating invoices based on the provided client and item data.

### Method
POST

### Endpoint
/api/billing/run

### Request Body
- **billing** (object) - Required - The billing configuration object containing webhook_url, period, invoice_date, tax_inclusive, and a list of invoices.
```

--------------------------------

### Authenticate via Query String Parameters

Source: https://paytraq.com/api/billing.html

Supply API credentials directly in the URL query string for authentication.

```bash
curl -v https://go.paytraq.com/api/{APICall}?APIToken={APIToken}&APIKey={APIKey} \
-H "Content-Type:application/xml" \
-d "{RequestBody}"
```

--------------------------------

### Retrieve Product List

Source: https://paytraq.com/api/pos.html

Fetches a list of products sorted by name, with optional filtering by name, SKU, or barcode.

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

```XML
<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>
```

--------------------------------

### Client Registration Response

Source: https://paytraq.com/api/billing.html

JSON response containing client registration details.

```json
{
    "client_id": "GjAtdC5s7gUXMSEXe0PpZLgc_xNYHD09",
    "client_id_issued_at": 1784645567,
    "client_name": "Client Application Name",
    "redirect_uris": [
        "http://localhost:8080/callback"
      ],
    "grant_types": [
        "authorization_code",
        "refresh_token"
      ],
    "response_types": [
        "code"
      ],
    "token_endpoint_auth_method": "none",
    "scope": "api"
}
```

--------------------------------

### Retrieve Product Image

Source: https://paytraq.com/api/pos.html

Fetches the image for a specific product identified by its ItemID.

```HTTP
GET https://go.paytraq.com/api/pos/{ConnectorID}/productImage/{ItemID}
```

```text
Image (JPEG/PNG)
```

--------------------------------

### Exchange Client Credentials for Access Token

Source: https://paytraq.com/api/billing.html

Use this cURL command for server-to-server authentication using client credentials.

```bash
curl -s https://go.paytraq.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=client_credentials \
  -d client_id=CLIENT_ID \
  -d client_secret=CLIENT_SECRET
```

--------------------------------

### Authenticate via HTTP Headers

Source: https://paytraq.com/api/billing.html

Supply API credentials using the APIToken and APIKey headers in a curl request.

```bash
curl -v https://go.paytraq.com/api/{APICall} \
-H "Content-Type:application/xml" \
-H "APIToken:{APIToken}" \
-H "APIKey:{APIKey}" \
-d "{RequestBody}"
```

--------------------------------

### Retrieve Client List

Source: https://paytraq.com/api/pos.html

Fetches a list of clients sorted by name, with optional filtering by name or email.

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

```XML
<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>
```

--------------------------------

### Authorization Callback

Source: https://paytraq.com/api/billing.html

The URL format received after user consent.

```text
REDIRECT_URI?code=AUTHORIZATION_CODE&state=abc123
```

--------------------------------

### Exchange Authorization Code for Tokens

Source: https://paytraq.com/api/billing.html

Exchange the authorization code for access and refresh tokens using PKCE.

```bash
curl -s https://go.paytraq.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=authorization_code \
  -d client_id=CLIENT_ID \
  -d redirect_uri=REDIRECT_URI \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=VERIFIER
```

--------------------------------

### POST https://go.paytraq.com/ext/direct/inbox/{ChannelID}

Source: https://paytraq.com/api/direct.html

Delivers a supplier invoice to the PayTraq Purchase Inbox. The request must be sent as XML with the Content-Type header set to application/xml.

```APIDOC
## POST https://go.paytraq.com/ext/direct/inbox/{ChannelID}

### Description
Delivers a supplier invoice in XML/UBL format to a client's PayTraq Purchase Inbox.

### Method
POST

### Endpoint
https://go.paytraq.com/ext/direct/inbox/{ChannelID}

### Parameters
#### Path Parameters
- **ChannelID** (string) - Required - The unique identifier for the PayTraq Direct channel, provided by the user upon activation.

### Request Body
- **XML/UBL Payload** (XML) - Required - The invoice data in Peppol/UBL, Estonian E-invoice, or Paytraq XML format.

### Response
#### Success Response (200)
- **Status** (integer) - Returns 200 OK upon successful receipt of the invoice.
```

--------------------------------

### POST /oauth/register

Source: https://paytraq.com/api/billing.html

Registers a new public client for the Authorization Code flow.

```APIDOC
## POST /oauth/register

### Description
Registers a public client to obtain a client_id for the Authorization Code flow.

### Method
POST

### Endpoint
https://go.paytraq.com/oauth/register

### Request Body
- **client_name** (string) - Required - Name of the application
- **redirect_uris** (array) - Required - List of whitelisted redirect URIs
- **scope** (string) - Required - Requested scopes

### Response
#### Success Response (200)
- **client_id** (string) - The issued client ID
- **client_id_issued_at** (integer) - Timestamp of issuance
- **client_name** (string) - Name of the application
- **redirect_uris** (array) - Whitelisted redirect URIs
- **grant_types** (array) - Supported grant types
- **response_types** (array) - Supported response types
- **token_endpoint_auth_method** (string) - Authentication method
- **scope** (string) - Granted scopes
```

--------------------------------

### Retrieve Billing Generation Results

Source: https://paytraq.com/api/billing.html

JSON response containing the status of a billing run and details for generated invoices, including links to PDF documents.

```JSON
{
    "run_id": "1318",
    "status": "done",
    "created_at": "2021-04-07 22:27:46",
    "completed_at": "2021-04-07 22:27:57",
    "period_from": "2021-03-01",
    "period_till": "2021-03-31",
    "invoices": [
        {
            "due": "55.06",
            "invoice_link": "https://go.paytraq.com/eInvoices/***",
            "invoice_ref": "0421/00001",
            "pdf_link": "https://go.paytraq.com/eInvoices/invoiceData/***",
            "updated": "2021-04-07 22:27:52",
            "status": "wait_payment",
            "is_sent": true,
            "invoice_date": "2021-04-07",
            "created": "2021-04-07 22:27:52",
            "total": "55.06",
            "client_id": "7969",
            "due_date": "2021-05-07",
            "currency": "EUR",
            "invoice_correlation_id": "1",
            "invoice_id": "6272",
            "client_correlation_id": "1"
        },
        {
            "due": "42.78",
            "invoice_link": "https://go.paytraq.com/eInvoices/***",
            "invoice_ref": "0421/00002",
            "pdf_link": "https://go.paytraq.com/eInvoices/invoiceData/***",
            "updated": "2021-04-07 22:27:57",
            "status": "wait_payment",
            "is_sent": false,
            "invoice_date": "2021-04-07",
            "created": "2021-04-07 22:27:57",
            "total": "42.78",
            "client_id": "7970",
            "due_date": "2021-05-07",
            "currency": "EUR",
            "invoice_correlation_id": "",
            "invoice_id": "6273",
            "client_correlation_id": ""
        }

    ]

}
```

--------------------------------

### Refresh Access Token

Source: https://paytraq.com/api/billing.html

Use a refresh token to obtain a new access token.

```bash
curl -s https://go.paytraq.com/oauth/token \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d grant_type=refresh_token \
  -d client_id=CLIENT_ID \
  -d refresh_token=REFRESH_TOKEN \
  -d scope=api
```

--------------------------------

### OAuth 2.1 Server Endpoints

Source: https://paytraq.com/api/billing.html

Base URLs for the authorization server and its metadata.

```text
https://go.paytraq.com/oauth
```

```text
https://go.paytraq.com/.well-known/oauth-authorization-server/oauth
```

--------------------------------

### POST https://go.paytraq.com/ext/webhooks/inbox/{ChannelID}

Source: https://paytraq.com/api/connect.html

Sends a new order to the PayTraq Sales Inbox. The request must be sent as an XML payload with the Content-Type: application/xml header.

```APIDOC
## POST https://go.paytraq.com/ext/webhooks/inbox/{ChannelID}

### Description
Push e-commerce orders directly to the PayTraq Sales Inbox for processing. This endpoint is triggered by a POST request whenever a new order is created on the e-commerce platform.

### Method
POST

### Endpoint
https://go.paytraq.com/ext/webhooks/inbox/{ChannelID}

### Parameters
#### Path Parameters
- **ChannelID** (string) - Required - The unique identifier for the PayTraq Connect channel, obtained by activating the channel in the Sales Inbox.

### Request Body
- **Sale** (XML) - Required - The XML structure containing order details including Header, LineItems, Adjustments, ShippingCharge, and AutoProcessing information.

### Response
#### Success Response (200)
- **Status** (integer) - Returns 200 OK upon successful receipt of the order.
```

--------------------------------

### POST /oauth/token (Refresh Token)

Source: https://paytraq.com/api/billing.html

Obtains a new access token using a refresh token.

```APIDOC
## POST /oauth/token

### Description
Uses a refresh token to obtain a new access token.

### Method
POST

### Endpoint
https://go.paytraq.com/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be 'refresh_token'
- **client_id** (string) - Required - The client ID
- **refresh_token** (string) - Required - The refresh token
- **scope** (string) - Required - Requested scopes

### Response
#### Success Response (200)
- **access_token** (string) - The new JWT access token
- **token_type** (string) - The type of token (Bearer)
- **expires_in** (integer) - Token expiration time in seconds
- **scope** (string) - Granted scopes
- **refresh_token** (string) - The new refresh token
```

--------------------------------

### Company List Response Format

Source: https://paytraq.com/api/billing.html

The expected JSON structure returned by the companies endpoint.

```JSON
{
   "companies": [
    {
     "company_id": _company_id,
     "company_name": _company_name
    }
   ]
  }
```

--------------------------------

### POST /oauth/token (Client Credentials)

Source: https://paytraq.com/api/billing.html

Exchanges client credentials for a JWT access token for server-to-server integrations.

```APIDOC
## POST /oauth/token

### Description
Exchanges client_id and client_secret for a JWT access token.

### Method
POST

### Endpoint
https://go.paytraq.com/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be 'client_credentials'
- **client_id** (string) - Required - The client ID obtained from Paytraq integrations
- **client_secret** (string) - Required - The client secret obtained from Paytraq integrations

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token
- **token_type** (string) - The type of token (Bearer)
- **expires_in** (integer) - Token expiration time in seconds
- **scope** (string) - Granted scopes
```

--------------------------------

### POST Add Sales Receipt Request

Source: https://paytraq.com/api/pos.html

Endpoint for creating a new sales receipt in the POS system.

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

--------------------------------

### POS API Request Structure

Source: https://paytraq.com/api/pos.html

General structure for making requests to the PayTraq POS API using HTTPS.

```APIDOC
## [POST/GET] https://go.paytraq.com/api/pos/{ConnectorID}/{APICall}

### Description
This endpoint is used to interact with the PayTraq POS system. Requests must be sent over HTTPS with the required authentication signature in the header.

### Method
GET or POST

### Endpoint
https://go.paytraq.com/api/pos/{ConnectorID}/{APICall}

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - The unique identifier for the POS connector.
- **APICall** (string) - Required - The specific API operation to perform.

#### Query Parameters
- **page** (integer) - Optional - Used for pagination, starting at 0. Default is 100 records per page.
- **query** (string) - Optional - Used for filtering results (e.g., by name, email, SKU, or barcode).

### Request Headers
- **Content-Type** (string) - Required - Must be 'application/xml' for POST requests.
- **APISignature** (string) - Required - The authentication signature obtained from the POS connector settings.

### Request Body
- **XML Payload** (xml) - Required for POST - The data to be processed in XML format.

### Response
#### Success Response (200)
- **XML Response** (xml) - The result of the operation in XML format.
```

--------------------------------

### POST /api/pos/{ConnectorID}/sale

Source: https://paytraq.com/api/pos.html

Adds a new sales receipt to the system. Supports selling goods, services, or other income types with optional client and item details.

```APIDOC
## POST /api/pos/{ConnectorID}/sale

### Description
Adds a new sales receipt to the system.

### Method
POST

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

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - Unique identifier for the POS connector.

### Request Body
- **Sale** (XML) - Required - The XML payload containing Header, LineItems, Adjustments, ShippingCharge, and Payments information.

### Response
#### Success Response (200)
- **DocumentID** (string) - Unique system identifier for sales document
- **DocumentStatus** (string) - Status of the document (draft, wait_payment, part_paid, paid)
- **AmountDue** (decimal) - Remaining amount due
- **PostResult** (object) - Result code and message
```

--------------------------------

### Request User Consent

Source: https://paytraq.com/api/billing.html

Redirect the user to the authorization endpoint to grant access.

```text
https://go.paytraq.com/oauth/authorize?response_type=code
    &client_id=CLIENT_ID
    &redirect_uri=REDIRECT_URI
    &scope=api
    &code_challenge=CHALLENGE
    &code_challenge_method=S256
    &resource=https://go.paytraq.com/api
    &state=abc123
```

--------------------------------

### Billing API Request

Source: https://paytraq.com/api/billing.html

The Billing API allows for the creation and distribution of invoices. It processes client information, line items, and optional payment details.

```APIDOC
## Billing API Request

### Description
Synchronizes clients, services, and units of measurement, and generates/distributes invoices.

### Parameters
#### Request Body
- **billing** (object) - Required - Container for invoice data
  - **invoices** (array) - Required - List of invoices to process
    - **client** (object) - Required - Client details (client_name, client_email, etc.)
    - **items** (array) - Required - List of line items (item_name, item_qty, item_price, etc.)
    - **webhook_url** (string) - Optional - URL for process completion notification
    - **period** (integer) - Optional - Billing period (1: current, 2: previous, 3: next)
    - **invoice_date** (string) - Optional - Date in YYYY-MM-DD format
    - **tax_inclusive** (boolean) - Optional - Default true
    - **invoice_ref** (string) - Optional - PayTraq invoice number
    - **invoice_correlation_id** (string) - Optional - External system ID
    - **custom_data** (object) - Optional - Custom fields
    - **comment** (string) - Optional - Invoice comment
    - **footer** (string) - Optional - Base64 encoded HTML footer
    - **payment** (object) - Optional - Payment details (money_account_id, date_paid)

### Request Example
{
  "billing": {
    "invoices": [
      {
        "client": {
          "client_name": "Example Client"
        },
        "items": [
          {
            "item_name": "Service Name",
            "item_qty": 1,
            "item_price": 100.00
          }
        ]
      }
    ]
  }
}

### Response
#### Success Response (200)
- **run_id** (string) - Billing process ID
- **status** (string) - Process status (e.g., "done")
- **created_at** (string) - Timestamp of creation
```

--------------------------------

### Retrieve Company List

Source: https://paytraq.com/api/billing.html

Call this endpoint to fetch all companies associated with the authenticated user or application.

```HTTP
GET /api/billing/companies
```

--------------------------------

### OAuth Token Response Format

Source: https://paytraq.com/api/billing.html

Standard JSON response structure for token exchange requests.

```json
{
    "access_token": ACCESS_TOKEN,
    "token_type": "Bearer",
    "expires_in": 86399,
    "scope": ""
}
```

--------------------------------

### Billing Process Response Structure

Source: https://paytraq.com/api/billing.html

The response format varies based on whether the billing process is still in progress or has completed, with the latter including a list of generated invoices.

```JSON
If the billing process is not yet completed:

{
  "run_id": _run_id,
  "status": _status,
  "created_at": _created_at
}

If the billing process is completed:

{

  "run_id": _run_id,
  "status": _status,
  "created_at": _created_at,
  "completed_at": _completed_at,
  "period_from": _period_from,
  "period_till": _period_till,
  "invoices": [
   {
    "client_correlation_id": _client_correlation_id,
    "invoice_correlation_id": _invoice_correlation_id,
    "client_id": _client_id,
    "invoice_id": _doc_id,
    "invoice_ref": _doc_ref,
    "invoice_date": _doc_date,
    "due_date": _due_date,
    "total": _total,
    "due": _due,
    "currency": _currency,
    "status": _status,
    "is_sent": _is_sent,
    "pdf_link": _pdf_link,
    "invoice_link": _invoice_link,
    "created_at": _created_at,
    "updated_at": _updated_at
   }
  ]
}
```

--------------------------------

### POST /api/pos/{ConnectorID}/cashIn

Source: https://paytraq.com/api/pos.html

Registers a cash-in operation for a specific POS connector.

```APIDOC
## POST /api/pos/{ConnectorID}/cashIn

### Description
Registers an amount added to the cash account for a specific POS connector.

### Method
POST

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

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - The unique identifier for the POS connector.

#### Request Body
- **Amount** (decimal) - Required - Amount to be added to cash account.
- **Date** (string) - Optional - Date of operation in YYYY-MM-DD format. Defaults to current UTC date if omitted.
- **Employee** (string) - Optional - Cashier's full name.
- **Narration** (string) - Optional - Description of the transaction.

### Request Example
<MoneyTransfer>
   <CashIn>
      <Amount>100.00</Amount>
      <Date>2014-01-30</Date>
      <Employee>John Doe</Employee>
      <Narration>Initial float</Narration>
   </CashIn>
</MoneyTransfer>

### Response
#### Success Response (200)
- **DocumentID** (string) - Unique system identifier for the payment document.

#### Response Example
<Response>
   <DocumentID>12345</DocumentID>
</Response>
```

--------------------------------

### POST Cash Out Request

Source: https://paytraq.com/api/pos.html

Endpoint for recording a cash out operation.

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

--------------------------------

### XML Order Payload Structure

Source: https://paytraq.com/api/connect.html

The XML schema for the order payload, including header, line items, adjustments, and auto-processing configurations.

```xml
<Sale>
   <Header>
      <Document>
         <DocumentDate></DocumentDate>
         <DocumentRef></DocumentRef>
         <Client>
            <ClientName></ClientName>
            <ClientRegNumber></ClientRegNumber>
            <ClientTaxNumber></ClientTaxNumber>
            <ClientEmail></ClientEmail>
            <ClientPhone></ClientPhone>
            <BillingAddress>
              <Address></Address>
              <Zip></Zip>
              <Country></Country>
            </BillingAddress>
            <IsCompany></IsCompany>
         </Client>
      </Document>
      <Total></Total>
      <Taxes></Taxes>
      <Currency></Currency>
      <IncludeTax></IncludeTax>
      <Comment />
      <ShippingData>
         <ShippingAddress>
            <ShipTo></ShipTo>
            <Address></Address>
            <Zip></Zip>
            <Country></Country>
         </ShippingAddress>
      </ShippingData>
   </Header>
   <LineItems>
      <LineItem>
         <Item>
            <ItemCode></ItemCode>
            <ItemBarCode></ItemBarCode>
            <ItemName></ItemName>
         </Item>
         <Qty></Qty>
         <Price></Price>
         <LineDiscount></LineDiscount>
         <Unit>
            <UnitName></UnitName>
         </Unit>
         <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>
   <AutoProcessing>
      <Process></Process>
      <Approve></Approve>
      <Send></Send>
      <AddPayment>
         <MoneyAccountID></MoneyAccountID>
         <DatePaid></DatePaid>
      </AddPayment>
   </AutoProcessing>
</Sale>
```

--------------------------------

### Payload Format

Source: https://paytraq.com/api/direct.html

Supported formats for e-invoices include Peppol/UBL, Estonian E-invoice, and Paytraq XML.

```text
E-invoice in Peppol/UBL, Estonian E-invoice or Paytraq XML formats
```

--------------------------------

### POST /oauth/token (Authorization Code)

Source: https://paytraq.com/api/billing.html

Exchanges an authorization code for a JWT access token and a refresh token.

```APIDOC
## POST /oauth/token

### Description
Exchanges an authorization code for a JWT access token and a refresh token using PKCE.

### Method
POST

### Endpoint
https://go.paytraq.com/oauth/token

### Request Body
- **grant_type** (string) - Required - Must be 'authorization_code'
- **client_id** (string) - Required - The client ID
- **redirect_uri** (string) - Required - The redirect URI used in the authorization request
- **code** (string) - Required - The authorization code received
- **code_verifier** (string) - Required - The original random string used for the code challenge

### Response
#### Success Response (200)
- **access_token** (string) - The JWT access token
- **token_type** (string) - The type of token (Bearer)
- **expires_in** (integer) - Token expiration time in seconds
- **scope** (string) - Granted scopes
- **refresh_token** (string) - The refresh token
```

--------------------------------

### Set Content-Type Header

Source: https://paytraq.com/api/billing.html

Required header for all POST requests to ensure the server processes the body as JSON.

```HTTP
Content-Type: application/json
```

--------------------------------

### Set Content-Type Header

Source: https://paytraq.com/api/pos.html

Required header for all POST requests to the POS API.

```http
Content-Type: application/xml
```

--------------------------------

### POST /api/pos/{ConnectorID}/cashOut

Source: https://paytraq.com/api/pos.html

Records a cash out operation from the POS cash account.

```APIDOC
## POST /api/pos/{ConnectorID}/cashOut

### Description
Records a cash out operation from the POS cash account.

### Method
POST

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

### Parameters
#### Path Parameters
- **ConnectorID** (string) - Required - Unique identifier for the POS connector.

### Request Body
- **MoneyTransfer** (XML) - Required - The XML payload containing CashOut details (Amount, Date, Employee, Narration).

### Response
#### Success Response (200)
- **DocumentID** (string) - Unique system identifier for payment document
```

--------------------------------

### Billing Process Payload Structure

Source: https://paytraq.com/api/billing.html

The JSON payload required for the billing process, containing client details, invoice references, and line items.

```JSON
{
"billing": {
  "webhook_url": _webhook_url,
  "period": _period,
  "invoice_date": _invoice_date,
  "tax_inclusive": _tax_inclusive,
  "invoices": [
   {
    "client": {
      "client_correlation_id": _client_correlation_id,
      "client_id": _client_id,
      "client_name": _client_name,
      "client_email": _client_email,
      "client_phone": _client_phone,
      "client_details": _client_details,
      "client_reg_number": _client_reg_number,
      "client_vat_number": _client_vat_number,
      "client_contract": _client_contract,
      "client_project_name": _client_project_name,
      "client_group_name": _client_group_name,
      "is_company": _is_company,
      "send_to": _is_send_to,
      "billing_address": {
        "address": _address,
        "zip": _zip,
        "country_code": _country_code
       }
     },
     "invoice_ref": _invoice_ref,
     "invoice_correlation_id": _invoice_correlation_id,
     "custom_data": [
      {
        "field_name": _field_name,
        "field_value": _field_value
      }
      ],
      "comment": _comment,
      "items": [
       {
         "item_code": _item_code,
         "item_name": _item_name,
         "item_qty": _item_qty,
         "item_uom": _item_uom,
         "item_price": _item_price,
         "item_tax_rate": _item_tax_rate,
         "item_tax_name": _item_tax_name,
         "item_discount": _item_discount,
         "item_description": _item_description,
         "item_account_code": _item_account_code,
         "item_period": _item_period
        }
      ],
      "payment": {
         "money_account_id": _money_account_id,
         "date_paid": _date_paid
         },
      "footer": _footer
    }
   ]
  }
}
```

--------------------------------

### Token Exchange Response

Source: https://paytraq.com/api/billing.html

JSON response containing access and refresh tokens.

```json
{
    "access_token": ACCESS_TOKEN,
    "token_type": "Bearer",
    "expires_in": 86399,
    "scope": "api",
    "refresh_token": REFRESH_TOKEN
}
```

--------------------------------

### API Authorization Header

Source: https://paytraq.com/api/billing.html

Required HTTP header for authenticating API requests.

```http
Authorization: Bearer ACCESS_TOKEN
```

--------------------------------

### Billing API Success Response

Source: https://paytraq.com/api/billing.html

Standard JSON response returned when a billing request is processed successfully.

```json
{
  "run_id": _run_id,
  "status": "done",
  "created_at": _created_at
}
```

--------------------------------

### Minimum Billing Request Payload

Source: https://paytraq.com/api/billing.html

The minimal set of required fields to initiate an invoice generation request.

```json
{
    "billing": {
      "invoices": [
       {
         "client": {
           "client_name": _client_name
         },
       "items": [
         {
           "item_name": _item_name,
           "item_qty": _item_qty,
           "item_price": _item_price,
         }
        ]
       }
     ]
    }
  }
```

--------------------------------

### Sales Receipt Response

Source: https://paytraq.com/api/pos.html

XML response structure returned after a successful sales receipt submission.

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

--------------------------------

### POST Cash In Request Endpoint

Source: https://paytraq.com/api/pos.html

The endpoint URL for performing a cash in operation.

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

--------------------------------

### Request Endpoint

Source: https://paytraq.com/api/direct.html

The endpoint for delivering invoices. The {ChannelID} must be obtained from the PayTraq user.

```http
POST https://go.paytraq.com/ext/direct/inbox/{ChannelID}
```

--------------------------------

### POST Request API Call

Source: https://paytraq.com/api/connect.html

The HTTP POST request structure for sending order data to the PayTraq Sales Inbox.

```http
POST https://go.paytraq.com/ext/webhooks/inbox/{ChannelID}
```

--------------------------------

### Cash Out Response

Source: https://paytraq.com/api/pos.html

XML response structure returned after a successful cash out operation.

```XML
<Response>
   <DocumentID></DocumentID>
</Response>
```

--------------------------------

### Webhook Endpoint URL

Source: https://paytraq.com/api/connect.html

The base URL for the PayTraq Connect webhook, where {ChannelID} must be replaced with the specific channel identifier.

```text
https://go.paytraq.com/ext/webhooks/inbox/{ChannelID}
```

--------------------------------

### Cash Out XML Payload

Source: https://paytraq.com/api/pos.html

XML structure for defining cash out details.

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

--------------------------------

### Billing Process Webhook Payload

Source: https://paytraq.com/api/billing.html

Structure of the JSON payload sent to the configured webhook URL upon completion of the billing process.

```json
{
  "run_id": _run_id,
  "status": _status,
  "created_at": _created_at,
  "completed_at": _completed_at
}
```

--------------------------------

### Set CompanyID Header

Source: https://paytraq.com/api/billing.html

Include this header in all authenticated API requests to specify the target company.

```HTTP
CompanyID: COMPANY_ID
```

--------------------------------

### Cash In XML Payload

Source: https://paytraq.com/api/pos.html

The XML structure required for the cash in request.

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

--------------------------------

### Sales Receipt XML Payload

Source: https://paytraq.com/api/pos.html

XML structure for defining sales receipt details, including header, line items, adjustments, and payment information.

```XML
<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>
```
Tokens:
Raw