Operations

createFaultReport

Report a fault on a meter

POST /prepaidutility/v3/faultReports/{requestId}

Reports a technical fault on a specified meter. This resource is used when a customer wishes to report a technical fault to the utility with whom the meter is reqistered.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
requestId path yes The randomly generated UUID of this request. string
body body yes A fault report FaultReportRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created FaultReportResponse
400 Bad request ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

createKeyChangeTokenRequest

Request a key change token

POST /prepaidutility/v3/keyChangeTokenRequests/{requestId}

Requests a key change token for a specified meter. This resource is used when the utility has updated a meter's encryption key and the customer required a token to input the new key to the meter. Key change tokens are typically supplied as part of a normal purchase, so this operation is rarely used.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
requestId path yes The randomly generated UUID of this request. string
body body yes A key change token request KeyChangeTokenRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created KeyChangeTokenResponse
400 Bad request ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

createMeterLookup

Request information about a specified meter

POST /prepaidutility/v3/meterLookups/{lookupId}

Request information about a specified meter, including customer and utility details. This resource is used to verify that a meter number is valid and registered with the correct details. It also confirms whether the meter is recognised by a provider and that tokens can be issued against it.

Security

  • httpBasic

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
lookupId path yes The randomly generated UUID of this request. string
body body yes A meter information lookup request. MeterLookupRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created MeterLookupResponse
400 Bad request ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

createTokenPurchaseRequest

Requests a token purchase for a specified meter.

POST /prepaidutility/v3/tokenPurchases/{purchaseId}

Requests that the provider issue a token against the meter for a given monetary value. In the case that the meter and/or utility supports the issue of free tokens under a basic service support tariff scheme, then any free tokens due will also be returned. If the requested amount is 0 and a free token is due to the meter, then only this free token will be returned. A portion of the request amount may be used by the provider to offset outstanding debt or service charges owed by the customer, in which case the value of the token returned may be less than the request amount (see interface documentation for further details).

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
purchaseId path yes The randomly generated UUID of this request. string
body body yes A token purchase request. PurchaseRequest

Response

Content-Type: application/json

Status Code Reason Response Model
201 Created PurchaseResponse
400 Bad request ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

confirmTokenPurchase

Confirms that a purchase has been completed successfully.

POST /prepaidutility/v3/tokenPurchases/{purchaseId}/confirmations/{confirmationId}

Confirms that a purchase has been completed successfully (i.e. the tokens have been issued to the customer and payment has been received by the merchant). It is typical that token providers do not support confirmations (aka advices), but certain point-of-sale integrations may require support for these. A confirmation request must be sent repeatedly until an HTTP response code indicating a final state has been received (i.e. either 202 or 400).

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
purchaseId path yes The randomly generated UUID of the original purchase request. string
confirmationId path yes The randomly generated UUID of this confirmation. string
body body yes A token purchase confirmation ConfirmationAdvice

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted BasicAdviceResponse
400 Bad request ErrorDetail
404 Not found ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

retryPurchaseRequest

Retry a previously submitted purchase request.

POST /prepaidutility/v3/tokenPurchases/{purchaseId}/retry

If no response was received to a purchase request due to a timeout or temporary communications failure, PoS may retry the same purchase request by calling this resource. The original purchase request will be resubmitted to the provider. If the provider had received the original request, it will respond by returning any tokens that were already issued. If not, then either new tokens may be issued as per a normal purchase or the retry will be declined.

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
purchaseId path yes The randomly generated UUID of the original purchase request. string
body body yes The original token purchase request. PurchaseRequest

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted PurchaseResponse
400 Bad request ErrorDetail
404 Not found ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

reverseTokenPurchase

Notifies the provider that a purchase was not completed successfully.

POST /prepaidutility/v3/tokenPurchases/{purchaseId}/reversals/{reversalId}

Notifies that a purchase was not completed successfully. This can occur if the original request timed out or if payment was unsuccessful. Many providers, however, do not support reversals and once a token has been issued the merchant becomes liable for the cost irrespective of payment failure or timeout. The token may still be retrieved by a reprint request, which merchants may use to help accommodate this scenario. A reversal request must be sent repeatedly until an HTTP response code indicating a final state has been received (i.e. either 202 or 400).

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
purchaseId path yes The randomly generated UUID of the original purchase request. string
reversalId path yes The randomly generated UUID of this reversal. string
body body yes A token purchase reversal. ReversalAdvice

Response

Content-Type: application/json

Status Code Reason Response Model
202 Accepted BasicAdviceResponse
400 Bad request ErrorDetail
404 Not found ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail

requestTokenReprint

Requests a reprint of a token

POST /prepaidutility/v3/tokenReprints/{reprintId}

Requests a reprint of a token that was previously issued for a specified meter. The request can be for either the last token issued for that meter, or for a specific transaction reference, depending on what the provider supports.

Request

Content-Type: application/json

Parameters

Name Located in Required Description Default Schema
reprintId path yes The randomly generated UUID of this request. string
body body yes A token reprint request. TokenReprintRequest

Response

Content-Type: application/json

Status Code Reason Response Model
200 Success PurchaseResponse
400 Bad request ErrorDetail
500 Internal Server Error ErrorDetail
501 Not implemented ErrorDetail
503 Service Unavailable ErrorDetail
504 Gateway Timeout ErrorDetail