API reference · Meter charges

Read a meter charge

GET/v1/meter-charges/{operationId}

Read progress, all charging tokens after success, or the failure and whether money has returned.

Permissionmeter_charges:read

AuthenticationSigned read

Anis’s answerSigned

Staff-set limits it counts towardAll requests

.NET SDKanis.MeterCharges.GetAsync(operationId)

Every processing 202 contains exactly operationId, operationType and status: "processing"; operationType is meterCharge. Full operation reads use 200.
A create that was refused and recorded as refused never produced a charge: the read answers that recorded refusal (409 or 422) with Idempotency-Replayed: true, and nothing was charged. On a read, idempotency_conflict means no meter charge of this application exists under the id.

Parameters

Name	In	Type	Notes
`operationId`required	`path`	UUID	A UUID, lower-case with hyphens.

Request

Signed with your key. No body, no nonce.

Headers: Signature-Input, Signature, X-Anis-Date, Accept-Language (optional). The SDKs set all of them for you.

Body: none.

Responses

Status	Meaning	Body
200	Success.	MeterCharge
202	Accepted — no outcome yet.	MeterChargeAccepted
400	Refused: the signed request is badly built.	Problem
401	Refused: not authenticated.	Problem
403	Refused: not allowed.	Problem
404	Refused: not found, or not yours.	Problem
409	Refused: conflicts with the current state.	Problem
422	Refused: the request breaks a rule.	Problem
429	Refused: a limit was reached.	Problem
503	No decision: a dependency was unavailable.	Problem

Every answer of this call is signed by Anis — success and every refusal. Require the signature and verify it before you act on the answer; an answer without one is a failure, never an answer (how).

Refusals

Every refusal of this call is a signed problem. Branch on its code; each links to what it means and what to do.

Error	Code	Status
Invalid credentials	`invalid_credentials`	401
Malformed signed request	`malformed_signed_request`	400
Insufficient scope	`insufficient_scope`	403
Source address not allowed	`source_ip_not_allowed`	403
Rate limited	`rate_limited`	429
Validation failed	`validation_failed`	422
Service unavailable	`dependency_unavailable`	503
Request timeout	`request_timeout`	504
Internal error	`internal_error`	500
Not found	`resource_not_found`	404
Insufficient balance	`insufficient_balance`	409
Price changed	`price_changed`	409
Package unavailable	`package_unavailable`	409
Meter refused	`meter_rejected`	422
Operation id already used	`idempotency_conflict`	409

Types

MeterCharge

Field	Type	Notes
`operationId`always present	UUID	The same UUID sent as Idempotency-Key for this purchase.
`status`always present	MeterChargeStatus	processing, succeeded or failed. A failed read still needs refund.status to explain the money outcome.
`walletId`always present	string	The wallet used for this purchase.
`meterNumber`always present	string	The meter number as text; preserve leading zeros.
`package`always present	MeterChargePackage	The package recorded for this charge.
`total`always present	Money	The frozen total wallet cost in every state, as LYD Money.
`personalPrice`always present	Money	The frozen retail display price in every state; do not substitute it for the payable total.
`externalReference`	string	Your reference, included when supplied.
`createdAt`always present	string (date-time)	When the charge was recorded, in UTC.
`completedAt`	string (date-time)	When the charge succeeded; omitted in processing and failed states.
`receipt`	MeterReceipt	Present after successful charging; includes the full token list.
`failure`	MeterFailure	The charge failure and localized display message; present for a failed charge.
`refund`	MeterRefund	For a failed charge, whether money returned, was not taken or is still pending.

MeterChargeStatus

MeterChargePackage

Field	Type	Notes
`id`always present	UUID	The meter package identifier.
`name`always present	string	One stored package name, not a bilingual text object.
`gecolPackageName`always present	string	The electricity supplier's package name.

Money

Field	Type	Notes
`amount`always present	string	A decimal string, never a JSON number. Wallet balances may be negative while allowed debt is used. Prices and totals follow each route's amount rules.
`currency`always present	string	An uppercase three-letter currency code, such as `LYD`. Read a wallet’s currency from `balance.currency`.
`asOf`	string (date-time)	When this price or balance was read.

MeterReceipt

Field	Type	Notes
`receiptNumber`	string	The receipt number supplied by the electricity supplier.
`creditedAmount`	string	The supplier's credited amount string, passed through unchanged; not the wallet total.
`tokens`always present	list of MeterToken	Every supplier token in sequence order, including key changes before credit.
`taxes`always present	list of MeterTax	The supplier receipt's tax lines.

MeterToken

Field	Type	Notes
`sequence`always present	integer	Supplier token order; preserve gaps rather than renumbering.
`label`always present	string	The supplier's token label.
`code`always present	string	The complete token string, including spaces and leading zeros.
`description`	string	The token's display description when supplied.

MeterTax

Field	Type	Notes
`description`always present	string	The electricity company's original Arabic tax description, unchanged.
`amount`always present	string	The original supplier amount string; no Money-scale conversion.

MeterFailure

Field	Type	Notes
`code`always present	string	A charge-read failure value, not an HTTP problem code. Values: `meter_number_invalid`, `meter_not_whitelisted`, `meter_not_linked`, `meter_removed`, `meter_inactive`, `meter_account_blocked`, `meter_data_incomplete`, `meter_debt_exceeds_package`, `package_unavailable`, `package_limit_reached`, `token_not_written`, `insufficient_balance`, `gecol_unavailable`, `charge_failed`
`message`	LocalizedText	Arabic and English messages matching the charging result.

LocalizedText

Field	Type	Notes
`ar`	string	The Arabic text; omitted when empty.
`en`	string	The English text; omitted when empty.

MeterRefund

Field	Type	Notes
`status`always present	MeterRefundStatus	refunded means returned; notCharged means nothing taken; pending means money has not returned yet.
`amount`	any	The refund Money value when present; never infer settlement from this amount alone.

MeterRefundStatus

MeterChargeAccepted

Field	Type	Notes
`operationId`always present	UUID	The same UUID sent as Idempotency-Key for this purchase.
`operationType`always present	string	Always meterCharge. Values: `meterCharge`
`status`always present	string	Always processing; the outcome is not final. Values: `processing`