VAS request - K command
Overview
This command can be used to manage the VAS Services (APPs developed by Nexi) for alternative payment methods (APM) and other services. The protocol is a carrier for requests and responses from ECR to the corresponding APPs.
This feature is only available for Traditional POS.
VAS Request (from ECR)
| Pos | Length | Type | Content |
|---|---|---|---|
| 1 | 8 | N | Terminal ID (00000000-99999999) |
| 9 | 1 | N | Reserved (fixed at “0” 30 hex) |
| 10 | 1 | A | Message code: “K” (75 hex) |
| 11 | 8 | N | ECR Identifier |
| 19 | 3 | A | Reserved (fixed at “0” 30 hex) |
| 22 | 1 | N | Reserved (fixed at “0”) |
| 23 | 4 | N | Vas Request Length |
| 27 | max 1024 | A | Vas Request (XML Format). The length of message is specified in “VAS Request Length". |
VAS Response (from Terminal)
| Pos | Length | Type | Content |
|---|---|---|---|
| 1 | 8 | N | Terminal ID (00000000-99999999) |
| 9 | 1 | N | Reserved (fixed at “0” 30 hex) |
| 10 | 1 | A | Message code: “K” (75 hex) |
| 11 | 4 | A | Reserved (fixed at “0” 30 hex) |
| 15 | 1 | N | Concatenation Flag:
|
| 16 | 3 | N | ID message: identify the message in sequence. The first message is set to “001”. |
| 23 | 4 | N | Vas Response Length |
| 27 | max 1024 | A | Vas Response (XML Format) |
If the XML response is greater than 1024 bytes (in the form of a long Receipt Data), the response will be formulated in more concatenated messages so that it would be max 1024 bytes.
If the “concatenation Flag” is set to “1”, the ECR will queue more messages (after sending ACK).
The messages are characterized by the “ID Message” field, which is incremental from 001 to the number of messages that compose the response.
ECR will concatenate the messages and compose the final XML “VAS Response”.
The response XML can contain the receipt produced in response to the execution of the requested VAS. The receipt, also in XML format, can contain the following TAGs for print formatting:
| TAGs | Meaning | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
<t>…</t> | The text to be printed out | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<lf /> | Line feed | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<b /> | Start printing in bold | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<dh /> | Start printing in double height | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<dw /> | Start printing in double weight | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<n /> | Start printing in normal | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<nb /> | Switch from bold to normal | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<nh /> | Switch to normal height | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
<nw /> | Switch to normal weight | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
APM (BancomatPAY, ALIPAY, WECHAT)
APM management is based on the use of the VAS_CLIENT application. Services can be engaged by ECR using the “K” command.
The management of APMs involves a single delivery method. These are the supported functions:
| Function | Description |
|---|---|
Payment via QrCode | Triggers the flow for managing payment via QR-CODE on the terminal. The transaction amount is passed as an optional parameter. |
Last operation status | Triggers the flow on the terminal to verify the outcome of the last operation performed. |
Total or Partial Refund | Triggers the flow for managing the reversal of a payment on the terminal. The cancellation can be total or partial. |
Daily Totals | Triggers the request for totals (number of transactions and amount) from the last accounting close. |
Accounting Closure | Triggers the request for accounting closure with zeroing of the totals. |
Payment via QrCode - Request
Payment via QrCode - Request
<ecrreq> <p k="ECRVASID">BPAY_QR</p> <p k="SUBSMPARAMS"> <p k="AMOUNT">value</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_QR WECHAT_QR ALIPAY_QR |
AMOUNT | Amount to authorize | Numeric | |
PRINTER | Defines who prints the receipt. If omitted, print the POS. | Alphanumeric | POS ECR |
Payment via QrCode - Request
"<ecrreq> <p k=\"ECRVASID\">BPAY_QR</p><p k=\"SUBSMPARAMS\"><p k=\"AMOUNT\">10</p><p k=\"PRINTER\">ECR</p></p></ecrreq>"
Payment via QrCode - Response
Payment via QrCode - Response
<ecrres> <p k="ECRVASID">BPAY_QR</p> <p k="RESPID">0</p> <p k="RESPMSG">OK-APPROVED</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_QR WECHAT_QR ALIPAY_QR |
RESPID | Outcome of the Request | Numeric | 0 = OK 0 <> KO |
RESPMSG | Description Outcome | Alphanumeric | If OK –-> APPROVED If not OK –-> Description of the anomaly found |
ORDER_ID | Unique identifier attributed to the transaction | Alphanumeric, max 27 | Value returned by the circuit. Necessary for the management of any Refund request. |
Last operation status - Request
Last operation status - Request
<ecrreq> <p k="ECRVASID">BPAY_ INQUIRY</p> <p k="SUBSMPARAMS"> <p k="PRINTER">value</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_INQUIRY WECHAT_INQUIRY ALIPAY_INQUIRY |
PRINTER | Defines who prints the receipt. If omitted, print the POS. | Alphanumeric | POS ECR |
Last operation status - Request
"<ecrreq> <p k=\"ECRVASID\">BPAY_QR</p><p k=\"SUBSMPARAMS\"><p k=\"PRINTER\">ECR</p></p></ecrreq>"
Last operation status - Response
Last operation status - Response
<ecrres> <p k="ECRVASID">BPAY_ INQUIRY</p> <p k="RESPID">0</p> <p k="RESPMSG"> OK-APPROVED</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_INQUIRY WECHAT_INQUIRY ALIPAY_INQUIRY |
RESPID | Outcome of the Request | Numeric | 0 = OK 0 <> KO |
RESPMSG | Description Outcome | Alphanumeric | If OK –-> APPROVED If not OK –-> Description of the anomaly found |
ORDER_ID | Unique identifier attributed to the transaction | Alphanumeric, max 27 | Value returned by the circuit. Necessary for the management of any Refund request. |
Total or Partial Refund - Request
Total or Partial Refund - Request
<ecrreq> <p k="ECRVASID">BPAY_REFUND</p> <p k="SUBSMPARAMS"> <p k="AMOUNT">value</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_REFUND WECHAT_REFUND ALIPAY_ REFUND |
AMOUNT | Amount to authorize | Numeric | Amount to be reversed (less than or equal to the authorized amount) |
ORDER_ID | Unique identifier of the transaction to be refunded | Alphanumeric, max 27 | Assigned by the authorization system |
PRINTER | Defines who prints the receipt. If omitted, print the POS. | Alphanumeric | POS ECR |
Total or Partial Refund - Request
"<ecrreq> <p k=\"ECRVASID\">BPAY_REFUND</p><p k=\"SUBSMPARAMS\"><p k=\"AMOUNT\">10</p><p k=\"PRINTER\">ECR</p></p></ecrreq>"
Total or Partial Refund - Response
Total or Partial Refund - Response
<ecrres> <p k="ECRVASID">BPAY_REFUND</p> <p k="RESPID">0</p> <p k="RESPMSG"> OK-APPROVED</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_REFUND WECHAT_REFUND ALIPAY_ REFUND |
RESPID | Outcome of the Request | Numeric | 0 = OK 0 <> KO |
RESPMSG | Description Outcome | Alphanumeric | If OK –-> APPROVED If not OK –-> Description of the anomaly found |
ORDER_ID | Unique identifier attributed to the transaction | Alphanumeric, max 27 | Value echo |
Daily Totals - Request
Currently available only for BPAY.
Daily Totals - Request
<ecrreq> <p k="ECRVASID">BPAY_TOTAL</p> <p k="SUBSMPARAMS"> <p k="PRINTER">value</p>
| Name | Description | Type | Values |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_TOTAL |
PRINTER | Defines who prints the receipt. If omitted, print the POS. | Alphanumeric | POS ECR |
Daily Totals - Request
"<ecrreq> <p k=\"ECRVASID\">BPAY_TOTAL</p></ecrreq>"
Daily Totals - Response
Daily Totals - Response
<ecrres> <p k="ECRVASID">BPAY_TOTAL</p> <p k="RESPID">0</p> <p k="RESPMSG"> OK-APPROVED</p>
| Name | Description | Type | Value |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_REFUND |
RESPID | Outcome of the Request | Numeric | 0 = OK 0 <> KO |
RESPMSG | Description Outcome | Alphanumeric | If OK –-> APPROVED If not OK –-> Description of the anomaly found |
NUM_TR | Total number of transactions accounted for | Alphanumeric | Value calculated from the last closing |
TOT_TR | Total amount accounted for | Alphanumeric | Value calculated from the last closing |
Accounting Closure - Request
Currently available only for BPAY.
Accounting Closure - Request
<ecrreq> <p k="ECRVASID">BPAY_CHIUSURA</p> <p k="SUBSMPARAMS"> <p k="PRINTER">value</p>
| Name | Description | Type | Value |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_CHIUSURA |
PRINTER | Defines who prints the receipt. If omitted, print the POS. | Alphanumeric | POS ECR |
Accounting Closure - Request
"<ecrreq> <p k=\"ECRVASID\">BPAY_CHIUSURA</p></ecrreq>"
Accounting Closure - Response
Accounting Closure - Response
<ecrres> <p k="ECRVASID"> BPAY_CHIUSURA</p> <p k="RESPID">0</p> <p k="RESPMSG"> OK-APPROVED</p>
| Name | Description | Type | Value |
|---|---|---|---|
ECRVASID | Request Service ID | Alphanumeric | BPAY_CHIUSURA |
RESPID | Outcome of the Request | Numeric | 0 = OK 0 <> KO |
RESPMSG | Description Outcome | Alphanumeric | If OK –-> APPROVED If not OK –-> Description of the anomaly found |