api-reference.md

Transaction Processor API reference

This reference covers the routes currently registered by TransactionProcessor (without host, port, or deployment path prefix). JSON property names are shown in CLR/PascalCase form; wire casing follows the shared serializer defaults configured at runtime. Guid values use UUID strings, decimals are JSON numbers, and date/time values are JSON strings accepted by the configured .NET converters.

Common behavior

• All endpoint groups below, except health checks and the domain-event controller, require authentication and the ClientCredentialsOnlyPolicy. Tokens use the configured OpenIddict validation issuer and API audience. Send Authorization: Bearer <token>.
• Handler outcomes pass through ResponseFactory. Generic success results serialize the mapped response DTO/model listed below. Successful non-generic command results return status-only responses with no JSON body. Failure status and problem bodies are centralized in Shared.Results.Web and can vary by result status.
• No pagination parameters are declared by these routes. Query parameters are listed only where the handler signature binds them.
• Nullable DTO fields may be omitted or null; the code does not declare per-property validation attributes for these request DTOs.

Endpoint index

Health

Method	Path	Parameters / body	Success response
GET	/health	None	Health check JSON from Shared.HealthChecks.HealthCheckMiddleware.WriteResponse.
GET	/healthui	None	Health check UI JSON.

Estates — /api/estates

Method	Path	Query	Request body	Success response
POST	/api/estates/	—	CreateEstateRequest	Result envelope/body from command result.
GET	/api/estates/{estateId}	—	—	EstateResponse
GET	/api/estates/{estateId}/all	—	—	EstateResponse[]
PATCH	/api/estates/{estateId}/users	—	CreateEstateUserRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/operators	—	Estate.AssignOperatorRequest	Result envelope/body from command result.
DELETE	/api/estates/{estateId}/operators/{operatorId}	—	—	Result envelope/body from command result.

Contracts — /api/estates/{estateId}/contracts

Method	Path	Query	Request body	Success response
GET	/api/estates/{estateId}/contracts/	—	—	ContractResponse[]
GET	/api/estates/{estateId}/contracts/{contractId}	—	—	ContractResponse
POST	/api/estates/{estateId}/contracts/	—	CreateContractRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/contracts/{contractId}/products	—	AddProductToContractRequest	Result envelope/body from command result. Product ID is generated by the server.
PATCH	/api/estates/{estateId}/contracts/{contractId}/products/{productId}/transactionFees	—	AddTransactionFeeForProductToContractRequest	Result envelope/body from command result. Fee ID is generated by the server.
DELETE	/api/estates/{estateId}/contracts/{contractId}/products/{productId}/transactionFees/{transactionFeeId}	—	—	Result envelope/body from command result.

Floats — /api/estates/{estateId}/floats

Method	Path	Query	Request body	Success response
POST	/api/estates/{estateId}/floats/	—	CreateFloatRequest	Result envelope/body from command result.
PUT	/api/estates/{estateId}/floats/	—	RecordFloatCreditPurchaseRequest	Result envelope/body from command result.

Merchants — /api/estates/{estateId}/merchants

Method	Path	Query	Request body	Success response
GET	/api/estates/{estateId}/merchants/	—	—	MerchantResponse[]
POST	/api/estates/{estateId}/merchants/	—	CreateMerchantRequest	Result envelope/body from command result.
GET	/api/estates/{estateId}/merchants/{merchantId}	—	—	MerchantResponse
PATCH	/api/estates/{estateId}/merchants/{merchantId}	—	UpdateMerchantRequest	Result envelope/body from command result.
GET	/api/estates/{estateId}/merchants/{merchantId}/balance	—	—	MerchantBalanceResponse
GET	/api/estates/{estateId}/merchants/{merchantId}/livebalance	—	—	MerchantBalanceResponse
GET	/api/estates/{estateId}/merchants/{merchantId}/balancehistory	startDate (DateTime), endDate (DateTime)	—	MerchantBalanceChangedEntryResponse[]
GET	/api/estates/{estateId}/merchants/{merchantId}/contracts	—	—	ContractResponse[]
PATCH	/api/estates/{estateId}/merchants/{merchantId}/contracts	—	AddMerchantContractRequest	Result envelope/body from command result.
DELETE	/api/estates/{estateId}/merchants/{merchantId}/contracts/{contractId}	—	—	Result envelope/body from command result.
GET	/api/estates/{estateId}/merchants/{merchantId}/contracts/{contractId}/products/{productId}/transactionFees	—	—	ContractProductTransactionFee[]
PATCH	/api/estates/{estateId}/merchants/{merchantId}/operators	—	Merchant.AssignOperatorRequest	Result envelope/body from command result.
DELETE	/api/estates/{estateId}/merchants/{merchantId}/operators/{operatorId}	—	—	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/devices	—	AddMerchantDeviceRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/devices/{deviceIdentifier}	—	SwapMerchantDeviceRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/users	—	CreateMerchantUserRequest	Result envelope/body from command result.
POST	/api/estates/{estateId}/merchants/{merchantId}/deposits	—	MakeMerchantDepositRequest	Result envelope/body from command result.
POST	/api/estates/{estateId}/merchants/{merchantId}/withdrawals	—	MakeMerchantWithdrawalRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/addresses	—	Address	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/addresses/{addressId}	—	Address	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/contacts	—	Contact	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/contacts/{contactId}	—	Contact	Result envelope/body from command result.
POST	/api/estates/{estateId}/merchants/{merchantId}/statements	—	GenerateMerchantStatementRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/opening	—	MerchantOpeningRequest	Result envelope/body from command result.
GET	/api/estates/{estateId}/merchants/{merchantId}/schedules/{year}	—	—	MerchantScheduleResponse
GET	/api/estates/{estateId}/merchants/{merchantId}/schedules/{year}/readmodel	—	—	MerchantScheduleResponse
POST	/api/estates/{estateId}/merchants/{merchantId}/schedules	—	CreateMerchantScheduleRequest	Result envelope/body from command result.
PATCH	/api/estates/{estateId}/merchants/{merchantId}/schedules/{year}	—	UpdateMerchantScheduleRequest	Result envelope/body from command result.

Operators — /api/estates/{estateId}/operators

Method	Path	Query	Request body	Success response
POST	/api/estates/{estateId}/operators/	—	CreateOperatorRequest	Result envelope/body from command result.
POST	/api/estates/{estateId}/operators/{operatorId}	—	UpdateOperatorRequest	Result envelope/body from command result.
GET	/api/estates/{estateId}/operators/	—	—	OperatorResponse[]
GET	/api/estates/{estateId}/operators/{operatorId}	—	—	OperatorResponse

Settlements — /api/estates/{estateId}/settlements

Method	Path	Query	Request body	Success response
GET	/api/estates/{estateId}/settlements/	merchantId (optional Guid), start_date (string), end_date (string)	—	SettlementResponse[]
GET	/api/estates/{estateId}/settlements/{settlementId}	merchantId (Guid; bound by handler but absent from route)	—	Responses.Settlement.SettlementResponse
GET	/api/estates/{estateId}/settlements/{settlementDate}/merchants/{merchantId}/pending	—	—	Root SettlementResponse
POST	/api/estates/{estateId}/settlements/{settlementDate}/merchants/{merchantId}	—	—	Settlement ID (Guid)

settlementDate is bound as DateTime. start_date and end_date are passed to business logic as strings; their accepted formats are not constrained at the HTTP binding layer. The single-settlement GET handler also requires a merchantId argument not represented in its route, so callers must supply it as a query parameter.

Transactions — /api/transactions

Method	Path	Query	Request body	Success response
POST	/api/transactions/logon	—	LogonTransactionRequest	LogonTransactionResponse
POST	/api/transactions/sale	—	SaleTransactionRequest	SaleTransactionResponse
POST	/api/transactions/reconciliation	—	ReconciliationRequest	ReconciliationResponse
POST	/api/transactions/{transactionId}/resendreceipt	estateId (Guid; bound but absent from route)	—	Result envelope/body from command result.
POST	/api/{estateId}/transactions/{transactionId}/resendreceipt (legacy)	—	—	Result envelope/body from command result.

Vouchers — /api/vouchers

Method	Path	Query	Request body	Success response
PUT	/api/vouchers/	—	RedeemVoucherRequest	RedeemVoucherResponse
GET	/api/vouchers/	estateId (Guid), voucherCode (string), transactionId (optional Guid)	—	GetVoucherResponse

Voucher lookup uses voucherCode when non-empty; otherwise it looks up by non-empty transactionId. If neither is supplied, it returns an invalid-result response.

Domain event ingress

Method	Path	Query / headers	Request body	Success response
POST	/api/domainevents	eventType header (required to resolve event type); optional subscriptionId header selects a named resolver	Event JSON object matching the event identified by eventType	Empty 200 OK; failures may return 500 Problem Details with eventId, eventType, and failures.

This endpoint has no authorization metadata in its controller declaration. Event payload properties are event-type-specific and are not modeled by a single DTO; the body schema is therefore a generic object.

Request DTOs

Fields below are the declared DTO properties. Requiredness is not inferred from non-nullable C# reference annotations because runtime nullability/validation behavior is not consistently configured.

DTO	Fields
CreateEstateRequest	EstateId: Guid, EstateName: string
CreateEstateUserRequest / CreateMerchantUserRequest	EmailAddress: string, Password: string, GivenName: string, MiddleName: string, FamilyName: string
Estate.AssignOperatorRequest	OperatorId: Guid
CreateContractRequest	OperatorId: Guid, Description: string
AddProductToContractRequest	DisplayText: string, ProductName: string, Value: decimal?, ProductType: ProductType
AddTransactionFeeForProductToContractRequest	CalculationType: CalculationType, Description: string, FeeType: FeeType, Value: decimal
CreateFloatRequest	FloatId: Guid, CreateDateTime: DateTime
RecordFloatCreditPurchaseRequest	FloatId: Guid, PurchaseDateTime: DateTime, CreditAmount: decimal, CostPrice: decimal
CreateMerchantRequest	Address: Address, Contact: Contact, Name: string, SettlementSchedule: SettlementSchedule, MerchantId: Guid?, CreatedDateTime: DateTime?
Address	AddressLine1: string, AddressLine2: string, AddressLine3: string, AddressLine4: string, Country: string, PostalCode: string, Region: string, Town: string
Contact	ContactName: string, EmailAddress: string, PhoneNumber: string
UpdateMerchantRequest	Name: string, SettlementSchedule: SettlementSchedule
MerchantOpeningRequest	Sunday, Monday, Tuesday, Wednesday, Thursday, Friday, Saturday: each OpeningHours (Opening: string, Closing: string)
AddMerchantContractRequest	ContractId: Guid
Merchant.AssignOperatorRequest	MerchantNumber: string, OperatorId: Guid, TerminalNumber: string
AddMerchantDeviceRequest	DeviceIdentifier: string
SwapMerchantDeviceRequest	NewDeviceIdentifier: string
CreateMerchantScheduleRequest	Year: int, Months: MerchantScheduleMonthRequest[]
UpdateMerchantScheduleRequest	Months: MerchantScheduleMonthRequest[]
MerchantScheduleMonthRequest	Month: int, ClosedDays: int[]
MakeMerchantDepositRequest	Amount: decimal, DepositDateTime: DateTime, Reference: string
MakeMerchantWithdrawalRequest	Amount: decimal, WithdrawalDateTime: DateTime, Reference: string
GenerateMerchantStatementRequest	MerchantStatementDate: DateTime
CreateOperatorRequest	Name: string, OperatorId: Guid, RequireCustomMerchantNumber: bool?, RequireCustomTerminalNumber: bool?
UpdateOperatorRequest	Name: string, RequireCustomMerchantNumber: bool?, RequireCustomTerminalNumber: bool?
LogonTransactionRequest	Inherited TransactionRequest fields plus DeviceIdentifier: string, TransactionNumber: string; it redeclares the base TransactionType: string property
SaleTransactionRequest	Inherited TransactionRequest fields plus AdditionalTransactionMetadata: Dictionary<string,string>, ContractId: Guid, CustomerEmailAddress: string, DeviceIdentifier: string, OperatorId: Guid, ProductId: Guid, TransactionNumber: string, TransactionSource: int?
ReconciliationRequest	Inherited TransactionRequest fields plus DeviceIdentifier: string, OperatorTotals: OperatorTotalRequest[], TransactionCount: int, TransactionValue: decimal
TransactionRequest (base)	EstateId: Guid, MerchantId: Guid, TransactionDateTime: DateTime, TransactionType: string
OperatorTotalRequest	ContractId: Guid, OperatorId: Guid, TransactionCount: int, TransactionValue: decimal
RedeemVoucherRequest	VoucherCode: string, EstateId: Guid, RedeemedDateTime: DateTime?

Principal response DTOs

The following fields describe the DTO types explicitly returned by handlers or model conversion. Collections are JSON arrays; nested DTOs are described in this table as well.

DTO	Fields
EstateResponse	EstateId, EstateReportingId, EstateName, EstateReference, Operators: EstateOperatorResponse[], SecurityUsers: SecurityUserResponse[]
EstateOperatorResponse	Name, OperatorId, RequireCustomMerchantNumber, RequireCustomTerminalNumber, IsDeleted
SecurityUserResponse	EmailAddress, SecurityUserId
ContractResponse	ContractId, ContractReportingId, Description, EstateId, EstateReportingId, OperatorId, OperatorName, Products: ContractProduct[]
ContractProduct	DisplayText, Name, ProductId, ProductReportingId, TransactionFees: ContractProductTransactionFee[], Value, ProductType
ContractProductTransactionFee	CalculationType, FeeType, Description, TransactionFeeId, TransactionFeeReportingId, Value
MerchantResponse	Addresses: AddressResponse[], Contacts: ContactResponse[], Devices: Dictionary<Guid,string>, EstateId, EstateReportingId, MerchantId, MerchantReportingId, MerchantName, MerchantReference, NextStatementDate, Operators: MerchantOperatorResponse[], SettlementSchedule, Contracts: MerchantContractResponse[], OpeningHours, Schedules: MerchantScheduleResponse[]
AddressResponse	AddressId, AddressLine1, AddressLine2, AddressLine3, AddressLine4, Country, PostalCode, Region, Town
ContactResponse	ContactEmailAddress, ContactId, ContactName, ContactPhoneNumber
MerchantOperatorResponse	Name, OperatorId, MerchantNumber, TerminalNumber, IsDeleted
MerchantContractResponse	ContractId, IsDeleted, ContractProducts: Guid[]
MerchantScheduleResponse	Year, Months: MerchantScheduleMonthResponse[]
MerchantScheduleMonthResponse	Month, ClosedDays: int[]
OperatorResponse	Name, OperatorId, RequireCustomMerchantNumber, RequireCustomTerminalNumber
MerchantBalanceResponse	EstateId, MerchantId, AvailableBalance, Balance
MerchantBalanceChangedEntryResponse	OriginalEventId, EstateId, MerchantId, ChangeAmount, DateTime, Reference, DebitOrCredit, Balance
SettlementResponse (root DTO, pending endpoint)	EstateId, MerchantId, SettlementDate, NumberOfFeesPendingSettlement, NumberOfFeesSettled, SettlementCompleted
Responses.Settlement.SettlementResponse	IsCompleted, NumberOfFeesSettled, SettlementDate, SettlementFees: SettlementFeeResponse[], SettlementId, ValueOfFeesSettled
SettlementFeeResponse	CalculatedValue, FeeDescription, IsSettled, MerchantId, MerchantName, SettlementDate, SettlementId, TransactionId, OperatorIdentifier
TransactionResponse (base)	EstateId, MerchantId, ResponseCode, ResponseMessage, TransactionId, TransactionType
LogonTransactionResponse	Inherits TransactionResponse
SaleTransactionResponse	Inherits TransactionResponse, plus AdditionalTransactionMetadata: Dictionary<string,string>
ReconciliationResponse	Inherits TransactionResponse
GetVoucherResponse	VoucherId, ExpiryDate, Value, Balance, VoucherCode, IsGenerated, IsIssued, IsRedeemed, IssuedDateTime, GeneratedDateTime, RedeemedDateTime, TransactionId
RedeemVoucherResponse	ExpiryDate, VoucherCode, RemainingBalance

Contract enums

ProductType, CalculationType, and FeeType are enum properties in the DTOs. The project does not configure an enum-to-string JSON converter in JsonSerializerConfiguration; confirm the deployed serializer defaults before sending enum values as strings. Merchant SettlementSchedule and day-of-week keys are likewise enum-backed.

Source and known contract caveats

• Minimal API handlers infer body binding for their DTO parameters and query binding for unmatched scalar parameters. Only handler parameters explicitly present in the route are path values.
• The settlement GET-by-ID route handler accepts merchantId in addition to estateId and settlementId; it is not part of the route template and is therefore a query parameter.
• The primary transaction receipt route similarly binds estateId as a query parameter because it is omitted from that route. A legacy route carries both IDs in its path.
• DomainEventController.GetDomainEvent expects eventType in a header and the body to serialize as the dynamically selected domain-event type. Its invalid/unrecognized-event paths are not represented as a stable response DTO.
• Some command success bodies are produced indirectly by ResponseFactory and business result types, rather than an endpoint-specific response mapping. Those are documented as result-factory responses instead of guessing a DTO.