Documentation

TalerMerchantClient
in package

TalerBarr

TalerMerchantClient

Thin HTTP client for the GNU Taler Merchant backend. Provides convenience wrappers for the inventory management API (categories & products).

This client expects an OAuth2 Bearer token with the appropriate permissions (e.g., categories-read, categories-write, products-read, products-write).

Notes:

$baseUrl should point to the merchant backend root (for example: "https://merchant.example.com/").
All methods throw \Exception on HTTP errors (non-2xx) or JSON encoding/decoding errors.
Uses Dolibarr's getURL() under the hood (curl mode).

Constants

USERNAME_REGEX = '~^[A-Za-z0-9][A-Za-z0-9_-]*$~'

Properties

$apiBase : string
$instance : string
$rootUrl : string
$token : string

Methods

__construct() : mixed: Constructor.
addProduct() : void: Add a product to the inventory.
createCategory() : int: Create a new category.
createOrder() : array{order_id: string, token?: string}: Create a new order that a wallet can pay for.
createWebhook() : void: Create a webhook.
delete() : array<string|int, mixed>: Perform a DELETE request.
deleteCategory() : void: Delete a category.
deleteOrder() : void: Delete an order from the backend.
deleteProduct() : void: Delete a product.
deleteWebhook() : void: Delete a webhook.
forgetOrderFields() : array<string, mixed>: Forget sensitive fields from an order contract.
get() : array<string|int, mixed>: Perform a GET request.
getBackendConfig() : array<string, mixed>: Fetch merchant /config from the root backend URL.
getCategory() : array{name: string, products: array, name_i18n?: array}: Get a single category with its product IDs.
getOrderStatus() : array<string, mixed>: Inspect a single order and its payment status.
getProduct() : array<string|int, mixed>: Get full details for a single product.
getWebhook() : array<string, mixed>: Fetch full details for a specific webhook.
listCategories() : array{categories: array}>}: List categories with product counts.
listOrders() : array{orders: array>}: List orders with optional filters (paid/refunded/wired/session/etc).
listProducts() : array{products: array}: List products in the inventory (summary).
listWebhooks() : array{webhooks: array}: List configured webhooks for the current instance.
patch() : array<string|int, mixed>: Perform a PATCH request with a JSON body.
post() : array<string|int, mixed>: Perform a POST request with a JSON body.
put() : array<string|int, mixed>: Perform a PUT request with a JSON body.
refundOrder() : array{taler_refund_uri: string, h_contract: string}: Request a refund for a paid order.
updateCategory() : void: Update (edit) a category.
updateProduct() : void: Update (patch) product details.
updateWebhook() : void: Update an existing webhook.
request() : array<string|int, mixed>: Low-level HTTP request helper around Dolibarr's getURL().

USERNAME_REGEX


    private
        mixed
    USERNAME_REGEX
    = '~^[A-Za-z0-9][A-Za-z0-9_-]*$~'

$apiBase


        private
            string
    $apiBase

Fully qualified API base (always ending with a trailing slash).

$instance


        private
            string
    $instance

Instance identifier carried around for debugging/logging.

$rootUrl


        private
            string
    $rootUrl

Base URL of the merchant backend as entered by the user (no trailing slash).

$token


        private
            string
    $token

OAuth2 bearer token used for Authorization header.

__construct()

Constructor.


    public
                    __construct(string $baseUrl, string $token[, string $instance = 'admin' ]) : mixed

Parameters

$baseUrl : string: Base URL of the Taler Merchant backend; trailing slash optional.
$token : string: OAuth2 Bearer token.
$instance : string = 'admin': Instance name for the $token and $baseUrl

addProduct()

Add a product to the inventory.


    public
                    addProduct(array<string|int, mixed> $product) : void

Required permission: products-write Returns 204 No Content on success.

Parameters

$product : array<string|int, mixed>: ProductAddDetail structure: [ 'product_id' => string (required), 'product_name' => string, // v20+, should be treated as required going forward 'description' => string, 'description_i18n' => array<string,string>, 'categories' => int[], // v16+ 'unit' => string, 'price' => array, // Amount {currency:string, value:string} or backend-specific 'image' => string, // data URL 'taxes' => array, // Tax[] 'total_stock' => int, // -1 for infinite 'address' => array, // Location 'next_restock' => int, // Timestamp 'minimum_age' => int, ]

createCategory()

Create a new category.


    public
                    createCategory(string $name[, array<string, string> $nameI18n = [] ]) : int

Required permission: categories-write

Parameters

$name : string: Category name.
$nameI18n : array<string, string> = []: Optional translations (lang_tag => name).

Return values

int —

The newly created category_id.

createOrder()

Create a new order that a wallet can pay for.


    public
                    createOrder(mixed $postOrderRequest) : array{order_id: string, token?: string}

Required permission: orders-write

Parameters

$postOrderRequest : mixed: payload per Taler merchant API.

Return values

array{order_id: string, token?: string}

createWebhook()

Create a webhook.


    public
                    createWebhook(array<string, mixed> $webhook) : void

Required permission: webhooks-write Returns 204 No Content on success.

Parameters

$webhook : array<string, mixed>: WebhookAddDetails payload.

delete()

Perform a DELETE request.


    public
                    delete(string $path[, null|array<string|int, mixed> $query = null ]) : array<string|int, mixed>

Parameters

$path : string: Relative path (may start with '/').
$query : null|array<string|int, mixed> = null: Optional key=>value query parameters.

Return values

array<string|int, mixed> —

Decoded JSON response as associative array (if any).

deleteCategory()

Delete a category.


    public
                    deleteCategory(int $categoryId) : void

Required permission: categories-write Returns 204 No Content on success.

Parameters

$categoryId : int: Category identifier.

deleteOrder()

Delete an order from the backend.


    public
                    deleteOrder(string $orderId) : void

Required permission: orders-write

Parameters

$orderId : string: Order identifier.

deleteProduct()

Delete a product.


    public
                    deleteProduct(string $productId) : void

Required permission: products-write Returns 204 No Content on success.

Parameters

$productId : string: Product identifier.

deleteWebhook()

Delete a webhook.


    public
                    deleteWebhook(string $webhookId) : void

Required permission: webhooks-write Returns 204 No Content on success.

Parameters

$webhookId : string: Webhook identifier.

forgetOrderFields()

Forget sensitive fields from an order contract.


    public
                    forgetOrderFields(string $orderId, array<int, string> $fields) : array<string, mixed>

Required permission: orders-write

Parameters

$orderId : string: Order identifier.
$fields : array<int, string>: JSON-path-like entries referencing forgettable fields.

Return values

array<string, mixed>

get()

Perform a GET request.


    public
                    get(string $path[, null|array<string|int, mixed> $query = null ]) : array<string|int, mixed>

Parameters

$path : string: Relative path (may start with '/').
$query : null|array<string|int, mixed> = null: Optional key=>value query parameters.

Return values

array<string|int, mixed> —

Decoded JSON response as associative array.

getBackendConfig()

Fetch merchant /config from the root backend URL.


    public
                    getBackendConfig() : array<string, mixed>

Return values

array<string, mixed>

getCategory()

Get a single category with its product IDs.


    public
                    getCategory(int $categoryId) : array{name: string, products: array, name_i18n?: array}

Required permission: categories-read

Parameters

$categoryId : int: Category identifier.

Return values

array{name: string, products: array, name_i18n?: array}

getOrderStatus()

Inspect a single order and its payment status.


    public
                    getOrderStatus(string $orderId[, array<string, mixed> $query = [] ]) : array<string, mixed>

Required permission: orders-read

Parameters

$orderId : string: Order identifier.
$query : array<string, mixed> = []: Optional query parameters (session_id, timeout_ms, allow_refunded_for_repurchase).

Return values

array<string, mixed>

getProduct()

Get full details for a single product.


    public
                    getProduct(string $productId) : array<string|int, mixed>

Required permission: products-read

Parameters

$productId : string: Product identifier.

Return values

array<string|int, mixed> —

ProductDetail structure per API (description, categories, price, stocks, etc.).

getWebhook()

Fetch full details for a specific webhook.


    public
                    getWebhook(string $webhookId) : array<string, mixed>

Required permission: webhooks-read

Parameters

$webhookId : string: Identifier of the webhook.

Return values

array<string, mixed>

listCategories()

List categories with product counts.


    public
                    listCategories() : array{categories: array}>}

Required permission: categories-read

Return values

array{categories: array}>}

listOrders()

List orders with optional filters (paid/refunded/wired/session/etc).


    public
                    listOrders([array<string, mixed> $query = [] ]) : array{orders: array>}

Required permission: orders-read

Parameters

$query : array<string, mixed> = []: Optional query string parameters (leave values null to skip).

Return values

array{orders: array>}

listProducts()

List products in the inventory (summary).


    public
                    listProducts([int $limit = 20 ][, int|null $offset = null ]) : array{products: array}

Required permission: products-read

Parameters

$limit : int = 20: Optional limit. Negative => descending by row ID, positive => ascending. Default 20.
$offset : int|null = null: Optional starting product_serial_id for iteration.

Return values

array{products: array}

listWebhooks()

List configured webhooks for the current instance.


    public
                    listWebhooks() : array{webhooks: array}

Required permission: webhooks-read

Return values

array{webhooks: array}

patch()

Perform a PATCH request with a JSON body.


    public
                    patch(string $path, array<string|int, mixed> $json[, null|array<string|int, mixed> $query = null ]) : array<string|int, mixed>

Parameters

$path : string: Relative path (may start with '/').
$json : array<string|int, mixed>: Request payload to be JSON-encoded.
$query : null|array<string|int, mixed> = null: Optional key=>value query parameters.

Return values

array<string|int, mixed> —

Decoded JSON response as associative array (if any).

post()

Perform a POST request with a JSON body.


    public
                    post(string $path, array<string|int, mixed> $json[, null|array<string|int, mixed> $query = null ]) : array<string|int, mixed>

Parameters

$path : string: Relative path (may start with '/').
$json : array<string|int, mixed>: Request payload to be JSON-encoded.
$query : null|array<string|int, mixed> = null: Optional key=>value query parameters.

Return values

array<string|int, mixed> —

Decoded JSON response as associative array (if any).

put()

Perform a PUT request with a JSON body.


    public
                    put(string $path, array<string|int, mixed> $json[, null|array<string|int, mixed> $query = null ]) : array<string|int, mixed>

Parameters

$path : string: Relative path (may start with '/').
$json : array<string|int, mixed>: Request payload to be JSON-encoded.
$query : null|array<string|int, mixed> = null: Optional key=>value query parameters.

Return values

array<string|int, mixed> —

Decoded JSON response as associative array (if any).

refundOrder()

Request a refund for a paid order.


    public
                    refundOrder(string $orderId, array<string|int, mixed> $refundRequest) : array{taler_refund_uri: string, h_contract: string}

Required permission: orders-refund

Parameters

$orderId : string: Order identifier.
$refundRequest : array<string|int, mixed>: RefundRequest payload (refund amount and reason).

Return values

array{taler_refund_uri: string, h_contract: string}

updateCategory()

Update (edit) a category.


    public
                    updateCategory(int $categoryId, string $name[, array<string, string> $nameI18n = [] ]) : void

Required permission: categories-write Returns 204 No Content on success.

Parameters

$categoryId : int: Category identifier.
$name : string: New name.
$nameI18n : array<string, string> = []: Optional translations (lang_tag => name).

updateProduct()

Update (patch) product details.


    public
                    updateProduct(string $productId, array<string|int, mixed> $patch) : void

Required permission: products-write Returns 204 No Content on success.

Parameters

$productId : string: Product identifier.
$patch : array<string|int, mixed>: ProductPatchDetail structure (all fields optional but validated by backend): [ 'product_name' => string, 'description' => string, 'description_i18n' => array<string,string>, 'unit' => string, 'categories' => int[], 'price' => array, // Amount 'image' => string, // data URL 'taxes' => array, // Tax[] 'total_stock' => int, 'total_lost' => int, 'address' => array, // Location 'next_restock' => int, // Timestamp (use special values per API) 'minimum_age' => int, ]

updateWebhook()

Update an existing webhook.


    public
                    updateWebhook(string $webhookId, array<string, mixed> $patch) : void

Required permission: webhooks-write Returns 204 No Content on success.

Parameters

$webhookId : string: Webhook identifier.
$patch : array<string, mixed>: WebhookPatchDetails payload.

request()

Low-level HTTP request helper around Dolibarr's getURL().


    private
                    request(string $verb, string $path[, null|array<string|int, mixed> $body = null ][, null|array<string|int, mixed> $query = null ][, int $timeoutSeconds = 30 ]) : array<string|int, mixed>

Parameters

$verb : string: HTTP verb ('GET','POST','PUT','PATCH','PATCHALREADYFORMATED','DELETE').
$path : string: Relative path (may start with '/').
$body : null|array<string|int, mixed> = null: If given, JSON-encoded into request body.
$query : null|array<string|int, mixed> = null: Optional query parameters to append to URL.
$timeoutSeconds : int = 30: Request timeout in seconds (default 30).

Return values

array<string|int, mixed> —

Decoded JSON body as associative array (empty array on empty body).

TalerMerchantClient in package TalerBarr

Tags

Table of Contents

Constants

Properties

Methods

Constants

USERNAME_REGEX

Properties

$apiBase

$instance

$rootUrl

$token

Methods

__construct()

Parameters

addProduct()

Parameters

Tags

createCategory()

Parameters

Tags

Return values

createOrder()

Parameters

Tags

Return values

createWebhook()

Parameters

Tags

delete()

Parameters

Tags

Return values

deleteCategory()

Parameters

Tags

deleteOrder()

Parameters

Tags

deleteProduct()

Parameters

Tags

deleteWebhook()

Parameters

Tags

forgetOrderFields()

Parameters

Tags

Return values

get()

Parameters

Tags

Return values

getBackendConfig()

Tags

Return values

getCategory()

Parameters

Tags

Return values

getOrderStatus()

Parameters

Tags

Return values

getProduct()

Parameters

Tags

Return values

getWebhook()

Parameters

Tags

Return values

listCategories()

Tags

Return values

listOrders()

Parameters

Tags

Return values

TalerMerchantClient
in package

TalerBarr