From ff9fee3cdc70c05d162fee14842bd0501ff253eb Mon Sep 17 00:00:00 2001 From: ecunado Date: Wed, 22 Jul 2026 14:56:31 +0200 Subject: [PATCH 1/2] docs: add Billing object for MoTo AVS support Documents the new billing field (zipCode, address) accepted by POST /transactions for moToSale and moToPreAuthorization, used for Address Verification Service. Matches the cloudapi implementation on feature/avs-moto and the terminal-side support shipped in hapi-android. --- restapi/restobjects.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/restapi/restobjects.md b/restapi/restobjects.md index a5d5043..56f452e 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -49,6 +49,30 @@ Balance available on the card. } ```` +## Billing + +`Billing` Object + +Billing address used for Address Verification Service (AVS). The billing object is optional and can only be used with the `moToSale` and `moToPreAuthorization` operations; it is ignored for `moToRefund` and `moToReversal`. When present, it is forwarded to the payment terminal as-is and included by the terminal in the authorization request sent to the acquirer. When omitted and AVS is enabled on the device's configuration template, the terminal prompts the operator for the billing details instead. + +**Properties** + +| Property | Description | +| ----------- | ----------- | +| `zipCode` Required
*String* | Billing postal/ZIP code of the cardholder. | +| `address`
*String* | Billing street address of the cardholder. | + +**Code example** + +````json +{ + "billing": { + "zipCode": "SW1A 1AA", + "address": "10 Downing Street" + } +} +```` + ## Bypass Options @@ -601,6 +625,7 @@ An object to store information about the request sent to the payment terminal. | `receipt`
*String* | HTML receipt, following the format defined in Html Print Format, or url to locate the receipt, it can be found in the response of a Transaction Request, in the fields merchantReceipt or customerReceipt. **REQUIRED** for operations: printReceipt. The receipts are usually received as URLs in the transaction result from the terminal but note that if the terminal is not able to upload the receipt to the Handpoint cloud servers and generate a URL then the HTML formatted receipt will be delivered to your software. It is important to be able to manage both formats. | | `tipConfiguration`
[*TipConfiguration*](#tip-configuration) | Configuration to enable tipping. At the time of sale, a tip menu will be shown to the cardholder with the predefined configuration. The tip configuration is optional and can only be used with the sale and saleAndTokenize operations. | | `bypassOptions`
[*ByPassOptions*](#bypass-options) | Configuration to enable the possibility of bypassing signature or pin. The bypass configuration is optional and can only be used with the sale, saleAndTokenize and refund operations. | +| `billing`
[*Billing*](#billing) | Billing address used for Address Verification Service (AVS). The billing object is optional and can only be used with the moToSale and moToPreAuthorization operations; it is ignored for moToRefund and moToReversal. When omitted and AVS is enabled on the device's configuration template, the terminal prompts the operator for the billing details instead. | | `merchantAuth`
[*MerchantAuth*](#merchant-auth) |Object used to store merchant authentication. it allows a transaction to be funded to a specific merchant account other than the default one. It is useful if a terminal is shared between multiple merchants, for example at an Hair Salon or a Doctor's office. The merchantAuth is optional and can only be used with the sale, saleAndTokenize and refund operations. For reversals, the credentials passed for the original sale will be automatically looked up by Handpoint and used to process the reversal. | | `duplicate_check`
*Boolean* |Used to disable the duplicate payment check functionality. When a merchant is not 100% sure of the transaction outcome, they will reprocess the transaction leading to the cardholder being charged twice. In order to avoid this scenario, we are flagging the duplicate transaction and prompting a menu to the cardholder/merchant to confirm/cancel the second charge. This menu will automatically be prompted on the payment terminal if a suspicious charge is detected. We are only prompting the duplicate check menu in case the same card is used twice in a row to process a transaction for the same amount within a 5 minutes timeframe.



** The duplicate_check functionality is available for the following transaction types:** Sale, Sale and Tokenize, Sale Reversal, Refund, Refund Reversal, MoTo Sale, MoTo Refund and MoTo Reversal.


The `duplicate_check` service is **enabled to "true" by default**, if you want to disable it, you must explicitly pass the `duplicate_check` flag as part of the transaction request with the value "false".| | `metadata`
[*Metadata*](#metadata) | Object used to store metadata, this data will be echoed in the transaction result.
Valid characters: `a-z A-Z 0-9 - ( ) @ : % _ \ + . ~ # ? & / = { } " ' ,`| From 3c5b4607a0dd8ee2dabaca98beda2ea18409635a Mon Sep 17 00:00:00 2001 From: ecunado Date: Thu, 23 Jul 2026 00:02:10 +0200 Subject: [PATCH 2/2] docs: add billing (AVS) field to MotoSaleRequest POST /moto/sale now accepts the same optional billing address used for Address Verification Service (AVS) as the Transaction Request Object, matching Viscus's ecomm API support for AVS on MOTO sale. --- restapi/restobjects.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/restapi/restobjects.md b/restapi/restobjects.md index 56f452e..bc9992f 100644 --- a/restapi/restobjects.md +++ b/restapi/restobjects.md @@ -904,6 +904,7 @@ Object used by the [`POST /moto/sale`](restendpoints#moto-operations-no-reader) | `cardToken` Required
*String* | Token that represents the card stored securely in the gateway. This token is obtained in a previous operation (for example, `saleAndTokenizeCard`) and allows the integrator to avoid handling PAN/CVV directly. | | `customerReference`
*String* | Merchant-defined reference for the operation. Useful for back-office reconciliation and reporting. | | `transactionReference`
*String* | Unique identifier for the transaction (for example, a UUID v4) generated by the integrator for traceability and reconciliation. | +| `billing`
[*Billing*](#billing) | Billing address used for Address Verification Service (AVS). Optional; only applied when AVS is enabled on the merchant's agreement with the acquirer, otherwise the request is rejected. | **Code example** @@ -913,7 +914,11 @@ Object used by the [`POST /moto/sale`](restendpoints#moto-operations-no-reader) "currency": "EUR", "cardToken": "665630867", "customerReference": "order-12345", - "transactionReference": "b7b2360d-3e9e-4b62-9a3a-2e6ef6c5cd01" + "transactionReference": "b7b2360d-3e9e-4b62-9a3a-2e6ef6c5cd01", + "billing": { + "zipCode": "SW1A 1AA", + "address": "10 Downing Street" + } } ```