PSPG eHDM API: Fiscal Receipt Examples

Get started with docs

How it works

1. Get WooCommerce order
2. Sync WooCommerce order items into eHDM
3. Get prepared items from eHDM storage
4. Call $eHDM->print()
5. Receive fiscal receipt response

Supported scenarios

Card payment — full payment by card
Cash payment — full payment in cash
Mixed payment — part by card, part in cash
Partial payment — payment goes into partialAmount
Prepayment usage — payment goes into prePaymentAmount

Base setup used in all examples:

$eHDM = apply_filters( 'planetstudio-payment-gateway-ehdm', null );

$wc_order_id = 2708;
$order       = wc_get_order( $wc_order_id );
$amount      = (float) $order->get_total();
$order_id    = '3b2a2c1b-a850-4edd-abf9-bb2a36e1078a';

$eHDM->getWoocommersOrderItems( $wc_order_id );
$items = $eHDM->getWoocommersOrderItemsFromDB( $wc_order_id );

Scenario 1: Card payment

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => $amount,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Expected result:

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "824",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363086000,
		"fiscal": "30247466",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 1, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Scenario 2: Cash payment

$result = $eHDM->print(
	array(
		'orderId'          => '',
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => $amount,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Expected result:

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "825",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363177000,
		"fiscal": "46682581",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 1, TOTAL_NONCASH: 0, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Scenario 3: Mixed payment

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0.6,
		'cashAmount'       => 0.4,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Expected result:

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "826",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363289000,
		"fiscal": "25105467",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0.4, TOTAL_NONCASH: 0.6, PREP_USAGE: 0, PARTIAL: 0, TOTAL: 1"
	}
}

Scenario 4: Partial payment

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => 0,
		'partialAmount'    => $amount,
		'prePaymentAmount' => 0,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Expected result:

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "827",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363388000,
		"fiscal": "35778064",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 0, PREP_USAGE: 0, PARTIAL: 1, TOTAL: 1"
	}
}

Scenario 5: Prepayment usage

$result = $eHDM->print(
	array(
		'orderId'          => $order_id,
		'wc_orderId'       => $wc_order_id,
		'cardAmount'       => 0,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => $amount,
		'cashierId'        => (int) get_option( 'ehdm_default_cashierId', 1 ),
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Expected result:

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "828",
		"crn": "52014201",
		"sn": "2FECD1F8",
		"tin": "00493113",
		"taxpayer": "...",
		"address": "...",
		"time": 1774363457000,
		"fiscal": "10900220",
		"total": 1,
		"change": 0,
		"qr": "TIN: ..., TOTAL_CASH: 0, TOTAL_NONCASH: 0, PREP_USAGE: 1, PARTIAL: 0, TOTAL: 1"
	}
}

Prepayment note

Prepayment usage (prePaymentAmount) can be processed without a goods list.

For standard sales, items list is required
For prepayment usage, items may be empty
This depends on fiscal rules and eHDM configuration

Prepayment without items

Prepayment usage (prePaymentAmount) can be processed without a goods list.

$result = $eHDM->print([
	'orderId'          => '',
	'wc_orderId'       => 0,
	'cardAmount'       => 0,
	'cashAmount'       => 0,
	'partialAmount'    => 0,
	'prePaymentAmount' => 1,
	'cashierId'        => 1,
	'mode'             => 3,
	'partnerTin'       => null,
	'items'            => [],
]);

Items source

You can provide items for print() in two different ways depending on your flow.

1. From WooCommerce order (real-time)

Use this method when you want to generate items directly from the WooCommerce order.

$items = $eHDM->getWoocommersOrderItems( $wc_order_id );

This will build the items list from the current order data without relying on previously saved receipts.

2. From eHDM database (saved receipt)

Use this method when items were already prepared and stored earlier.

$items = $eHDM->getWoocommersOrderItemsFromDB( $wc_order_id );

This is typically used when a receipt was already created before, and you want to reuse the same items list.

Custom items list

If you are not using WooCommerce order items, you can pass a custom items array manually.

$items = array(
	array(
		'adgCode'                => '9205',
		'dep'                    => 1,
		'goodCode'               => '9205-13',
		'goodName'               => 'երգեհոն',
		'quantity'               => 2,
		'unit'                   => 'հատ',
		'price'                  => 25000,
		'additionalDiscount'     => null,
		'additionalDiscountType' => null,
		'discount'               => null,
		'discountType'           => null,
	),
);

$result = $eHDM->print(
	array(
		'orderId'          => 'CUSTOM-ORDER-1',
		'wc_orderId'       => 0,
		'cardAmount'       => 50000,
		'cashAmount'       => 0,
		'partialAmount'    => 0,
		'prePaymentAmount' => 0,
		'cashierId'        => 1,
		'mode'             => 2,
		'partnerTin'       => null,
		'items'            => $items,
	)
);

Receipt returns

Use the return flow to create a fiscal return receipt for a previously issued receipt. First request the original receipt information, then create the return receipt using the returned item identifiers and quantities.

1. Get return information

$receipt_id = 824;
$return_info = $eHDM->getReturnedReceiptInfo( $receipt_id );
if ( ! is_array( $return_info ) || 0 !== (int) ( $return_info['code'] ?? -1 ) ) {
	// The Tax Service did not return information for this receipt.
	return;
}
$receipt = $return_info['result'];
$items   = $receipt['items'] ?? array();

The result contains the original receipt data. For goods receipts, result.items contains the returnable items. Use each item’s receiptProductId and the quantity to be returned when creating the return receipt.

2. Print a return receipt

// Return one unit of the first item from the original receipt.
$return_item_list = array(
	array(
		'receiptProductId' => (int) $items[0]['receiptProductId'],
		'quantity'         => 1,
	),
);
$result = $eHDM->printReturnReceipt(
	array(
		'receiptId'           => $receipt_id,
		'cardAmountForReturn' => 0,
		'cashAmountForReturn' => 5000,
		'returnItemList'      => $return_item_list,
	)
);

For a card refund, set cardAmountForReturn and leave cashAmountForReturn as 0. For a cash refund, do the opposite. The refund amount must match the selected return items and must not exceed the original receipt amount.

For receipts without goods, such as a prepayment receipt, use the data returned by getReturnedReceiptInfo() and pass an empty returnItemList only when the Tax Service response does not contain returnable items.

Return result

{
	"code": 0,
	"message": "OK",
	"errorMessage": null,
	"result": {
		"receiptId": "829",
		"fiscal": "...",
		"total": 5000,
		"qr": "TIN: ..., TOTAL_CASH: 5000, TOTAL_NONCASH: 0, ..."
	}
}

A successful response has code = 0. The new return receipt identifier is available in result.receiptId. You can generate its QR image with $eHDM->getReceiptQR( $result['result']['receiptId'], true ).

Return parameters

Parameter	Type	Description
`receiptId`	int	Original fiscal receipt ID to return.
`cardAmountForReturn`	double	Amount returned to a card or another non-cash payment method.
`cashAmountForReturn`	double	Amount returned in cash.
`returnItemList`	array	Items to return. Each item contains `receiptProductId` from `getReturnedReceiptInfo()` and the return `quantity`.

Notes

Always call getReturnedReceiptInfo() before printReturnReceipt().
Do not create receiptProductId values manually; use the values returned by the Tax Service.
A return receipt is a new fiscal receipt and has its own receipt ID and QR data.

Receipt QR

You can generate a QR code for a printed receipt using getReceiptQR().

Usage

$url = $eHDM->getReceiptQR( 824, true );

Returns QR code image URL.

$html = $eHDM->getReceiptQR( 824 );

Returns ready-to-use HTML image tag.

Example result

https://api.qrserver.com/v1/create-qr-code/?data=...&size=300x300

<img class="ehdm-qr" src="https://api.qrserver.com/..." alt="eHDM QR Code">

How it works

Loads receipt from eHDM database by receiptId
Extracts qr field
Encodes data into QR format
Generates QR image via external service

Notes

receiptId must exist in eHDM
Returns false if receipt not found
QR contains full fiscal information
You can use URL or ready HTML depending on your needs

Discount usage

To register an electronic HMD and integrate its encoding, it is possible to apply different types of discounts, which in turn have two subtypes:

1. Product price / discount
- % PERCENT — percentage value, discountType = 1
- PRICE (AMD) — value applied per product / unit, discountType = 2. Calculation: (initial_price – discount) * quantity
- TOTAL (AMD) — value applied to total quantity, discountType = 4. Calculation: (price * quantity) – discount
2. Additional product value / additionalDiscount
- Type additionalDiscountType = 16 — amount is calculated as: (price * quantity) – discount
- % — this value is applied up to 8 characters

What the response means

code = 0 — success
message = OK — receipt was printed successfully
errorMessage = null — no error
result.receiptId — receipt ID
result.fiscal — fiscal number
result.total — total receipt amount
result.change — change amount
result.qr — fiscal QR string with payment breakdown

QR fields

TOTAL_CASH — cash amount
TOTAL_NONCASH — card amount
PREP_USAGE — used prepayment amount
PARTIAL — partial payment amount
TOTAL — final total

Notes

mode = 2 – Goods mode / 3 – Prepayment mode
orderId is required for card and mixed scenarios
WooCommerce items must be prepared first via getWoocommersOrderItems()
Then load them via getWoocommersOrderItemsFromDB()
All receipts are stored inside eHDM

Parameters

Parameter	Type	Description
`cardAmount`	double	Non-cash (card) payment amount
`cashAmount`	double	Cash payment amount
`partialAmount`	double	Partial payment amount
`prePaymentAmount`	double	Used prepayment amount
`cashierId`	int	Cashier ID
`mode`	int	Receipt mode: `2` – Goods / `3` – Prepayment
`partnerTin`	string	Buyer tax identification number (TIN)
`items`	array	List of goods (items array)