# Xero Integration Configuration Guide
[TOC]
## What is ZGo PmtService
ZGo PmtService is an online service that provides Xero Accounting users with an additional invoice payment method using Zcash (ZEC).
### How it Works
ZGo PmtService is available mainly for business customers that want to offer their customers an option to pay invoices using Zcash (ZEC). The payment flow is showed below:
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/758c8c40-9375-4393-ba44-7533cb79bd2c.png" />
<br>
<br>
Figure 1 – ZGo Payment Service Flow
</div>
The payment flow shown in _Figure 1_ includes ZGo confirming the transaction and also reporting the invoice as paid in Xero. These steps are optional and do not affect the payment transaction as it takes place in the blockchain. The payment can be confirmed in Alice’s Zcash wallet at the shielded address linked to ZGo.
### Process description
* Alice creates an new invoice using Xero Accounting.
* The new invoice is sent to her customer, Bob, by e-mail.
* Bob receives the invoice and select the Zcash payment method using the link inside the invoice.
* Once Zcash payment method is selected, ZGo will present a payment order on Bob’s browser with the invoice amount and the Alice’s Zcash wallet shielded address.
* Bob transfers the requested amount that will appear in Alice’s wallet when confirmed.
* Once the ZGo Payment Order’s window is closed, ZGo will start monitoring the transaction until it has at least 5 (five) confirmations in the Zcash blockchain.
* ZGo accesses the invoice in Xero Accounting and marks it as paid.
## Xero to ZGo Integration
### Configuring ZGo
If you have not created your ZGo shop yet, please follow the instructions on the [ZGo setup guide](https://hedgedoc.vergara.tech/p/u24QCb0Gd#/).
#### Link to Xero
Once you have set your account in ZGo, on the Shop screen, press or click on Settings button as shown in the following image
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/256fa159-3953-4ab6-b984-2459e1d6a8bd.png" />
<br>
<br>
Figure 2 – Shop Menu
</div>
This will open the settings form, that allows user to set required parameters to activate ZGo payment service. The Settings form has two tabs, `Main` and `Integrations`.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<table align="center" >
<tr>
<td>
<img src="https://hedgedoc.vergara.tech/uploads/fde416c3-5dd8-4f7d-aef2-feba62ded9f8.png" />
</td>
<td>
<img src="https://hedgedoc.vergara.tech/uploads/b3ddef71-8396-4741-b0af-0c6e086f5e84.png" />
</td>
</tr>
</table>
<br>
Figure 3 – ZGo Settings Form
</div>
Clicking on the `Link to Xero` button will prompt you for your Xero credentials as shown below in _Figure 4_.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
">
<table align="center" >
<tr>
<img src="https://hedgedoc.vergara.tech/uploads/40afad77-1e82-4c7d-8a6e-8c4f0456b523.png" height="420"/>
</tr>
<tr>
<img src="https://hedgedoc.vergara.tech/uploads/758bd553-ef3f-40f7-b710-babfc3243e42.png" height="420"/>
</tr>
</table>
<br>
Figure 4 – Xero Login Form and Authorization Form
</div>
Enter your credentials and press _Login_ to open Xero Authorization form. In this example, we have used the _Demo Company_ provided by Xero (you have to use your company name).
Press `Allow Access Button` to provide access for ZGo. Upon successful connection, you will be redirected back to the ZGo main shop page.
Now, access the Integrations tab in Settings, wich should look as shown in _Figure 5_.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/b5b92b9b-67b5-42a3-8643-be0ee6d6ff8e.png" height="420"/>
<br>
<br>
Figure 5 – ZGo Settings Linked to Xero
</div>
Click on the `Copy URL` button on the left of _Payment Service URL_ field. This will copy the URL to the clipboard which will be used in the next step.
#### Add a New Payment Service to Xero
In order to offer Zcash payment as an option to customers, the Xero User needs to create an _Additional Payment Service_.
To do this, click on `Company`->`Settings`->`Payment Services`->`Additional Payment Services`->`Add Other`->`Custom Payment URL`, giving you the following dialog:
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/26311af5-0695-40aa-9e35-bb7e59cb0a73.png" />
<br>
<br>
Figure 6 – Xero Add custom URL connection Form
</div>
| Parameter | Value |
| -------- | -------- |
| `Account Name` | ZGo (recommended). The name for this payment service. |
| `Your Custom URL` | The custom URL provided by ZGo. To obtain this, follow the instructions on the [next section](#Get-ZGo-payment-URL). See [an example here](#Xero-Payment-Request-Structure) |
| `Pay now button text` | Pay with Zcash (recommended) |
You can now paste in _Your custom URL_ field the URL copied in previous step.
#### Add Link To ZGo option in Invoice
Finally, it is necessary to add the newly created payment option into each invoice template you have defined in Xero for the company.
To do this, click on `Company`->`Settings`->`Invoice settings`. The invoice template list will be displayed. Select the invoice you want to modify and click on the `Options` -> `Edit` button on the top right corner and a form like the one shown in _Figure 7_ and scroll down to the field _Payment services_ (Credit Card) and open the drop down list. Select the ZGo PmtService just created and press the `Save` button.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/085b2b81-81cd-45f6-a7ea-141fa264e0b8.png" />
<br>
<br>
Figure 7 – Xero Invoice Payment Services
</div>
Repeat the same process for all invoice templates you need.
### Enable Payment Confirmation in Xero
When Payment Confirmation is enabled, ZGo will use the Xero API library to mark invoices paid in the user's accounting.
The steps to enable this feature are described bellow.
#### Create an Account in Xero Accounting
:::info
If you do not wish to enable payment confirmations, you may skip this step.
:::
Open the Xero Accounting application, go to `Accounting` → `Chart of Accounts` → `Add Account`, and the form to create a new account will be displayed as shown below.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/879608f9-6a30-4299-b280-11d14ecaed00.png" />
<br>
<br>
Figure 8 – Xero Add Account form
</div>
Create a new Account, using the following parameters:
<table>
<th>Parameter</th>
<th>Value</th>
<tr>
<td style="width:40%">
Account Type
</td>
<td>
Current Asset
</td>
</tr>
<tr>
<td>
Code
</td>
<td>
222[^note]
</td>
</tr>
<tr>
<td>
Name
</td>
<td>
Zcash Wallet[^note]
</td>
</tr>
<tr>
<td>
Description
</td>
<td>
Payments received[^note]
</td>
</tr>
<tr>
<td>
Tax
</td>
<td>
As required
</td>
</tr>
<tr>
<td>
Enable payments to this account
</td>
<td>
:ballot_box_with_check: Checked
</td>
</tr>
</table>
[^note]: Values are suggested, use your own values.
This account will record the payments in the currency configured in Xero as soon as they are confirmed by ZGo on the Zcash blockchain. ZGo uses the latest price of Zcash available at the time the customer clicks on "Pay with Zcash".
The new account’s Code is required by ZGo to report these payments.
### Enable Payment Confirmation in ZGo
Finally, to enable payment confirmation you need to set the Account Code in ZGo.
Open the Integrations tab in ZGo Settings Form, which will be as in _Figure 5_, in the field Account Code, type or paste the account code you created in Xero. and hit the `Save` button as shown in _Figure 9_.
<div style="font-size: 12px;
text-align: center;
border: lightgray solid 1px;
margin-top: 40px;
margin-bottom: 40px;
">
<img src="https://hedgedoc.vergara.tech/uploads/32c09419-8e82-4637-a783-8f1ebf85117c.png" />
<br>
<br>
Figure 9 – ZGo Account Code
</div>
## Additional Information
### User Support
If you have any issues, questions or comments, please join us on [#zgo-support:vergara.tech](https://matrix.to/#/#zgo-support:vergara.tech).
### Xero Payment Request Structure
The following URL must be configured in Xero as a link to the ZGo Payment Service component (inside Xero’s Payment template generation)
`https://app.zgo.cash/pmtservice?owner={ZGo_accces_owner_id}&invoiceNo=[INVOICENUMBER]¤cy=[CURRENCY]&amount=[AMOUNTDUE]&shortCode=[SHORTCODE]`
### Payment Request Example
`https://app.zgo.cash/pmtservice?owner=62xxxxxxxxxxxxxxxxxxxx8e&invoiceNo=INV-0034¤cy=USD&amount=753.95&shortCode=!w8T62`
### Fixed elements in URL
<table>
<tr>
<td>
`http://app.zgo.cash`
</td>
<td>
ZGo’s URL
</td>
</tr>
<tr>
<td>
`/pmtservice`
</td>
<td>
ZGo Payment service entry point
</td>
</tr>
<tr>
<td>
`owner`
</td>
<td>
Owner id assigned to client
</td>
</tr>
</table>
### Variable elements provided by Xero
<table>
<tr >
<td>
`amount`
</td>
<td>
Invoice total value (amount due), corresponds to field named `amountDue` in Xero’s invoice structure
</td>
</tr>
<tr>
<td>
`currency`
</td>
<td>
Currency used - International alphanumeric code for currency (3 characters)
</tr>
<tr>
<td>
`invoiceNo`
</td>
<td>
Invoice number, corresponds to field named `invoiceNumber` in Xero’s invoice structure
</td>
</tr>
<tr>
<td>
`shortCode`
</td>
<td>
This is a unique identifier of a Xero organisation. The `shortCode` is less than 10 characters and contains a string with numbers, letters and special characters. It is not part of Invoice structure.
</td>
</tr>
</table>