# Invoices

## Upload invoice

<mark style="color:green;">`POST`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/sites/{siteId}/invoices`

This endpoint allows you to upload an invoice to the Zapper Platform and receive a Zapper Code for that invoice. Customers can use this code to scan and make Zapper payments to you. The siteReference parameter will be returned in Payment Notifications, allowing you to match uploaded invoices to payments.

#### Headers

| Name                | Type   | Description                                                                                                               |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------- |
| Representation-Type | string | <p>The representation-type to be returned. See Representation-Types below. Defaults to<br>"triggercode/transient"<br></p> |
| Content-Type        | string | application/json                                                                                                          |
| Accept              | string | <p>The data-type to be returned. Accepted types are:<br>text/plain<br>application/json<br>image/svg+xml</p>               |
| Authorization       | string | Bearer \<integration authentication token>                                                                                |

#### Request Body

| Name              | Type   | Description                                                                                             |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| subMerchant       | object | The submerchant details. This is required for aggregator merchants. See the model below.                |
| externalReference | string | A merchant's reference for an invoice                                                                   |
| siteReference     | string | The identifier of the point of sale till. This is required for routing of Zapper payments and invoices. |
| currencyISOCode   | string | The currency ISO code of the invoice.                                                                   |
| amount            | number | The invoice amount in cents.                                                                            |
| lineItems         | array  | A list of line items. See the model below.                                                              |
| origin            | string | The provider of the invoice.                                                                            |
| createdUTCDate    | string | The date of the invoice creation.                                                                       |
| originReference   | string | A unique reference code from the provider                                                               |

{% tabs %}
{% tab title="200 Invoice successfully uploaded." %}

```javascript
// Request Header - Accept: application/json
{
    "siteReference": "site_reference_1",
    "currencyISOCode": "ZAR",
    "amount": 1500,
    "lineItems": [
        {
            "name": "coke",
            "productCode": "ck",
            "SKU": "coke1",
            "unitPrice": 500,
            "categories": [],
            "quantity": 1
        },
        {
            "name": "fanta",
            "productCode": "fn",
            "SKU": "fnta1",
            "unitPrice": 500,
            "categories": [],
            "quantity": 2
        }
    ],
    "origin": "micros",
    "createdUTCDate": "2019-02-15T13:30:48.9070611Z",
    "originReference": "micros_129473",
    "reference": "522ccadc-779b-475f-b87a-5410c0c43c3c",
    "state": "open"
}

// Request Header - Accept: text/plain
// The Code string (to be used to create a QR Code) e.g:
https://zapper.com/lc?tcv=0260E041...

// Request Header - Accept: image/svg+xml
// Returns the Code as an SVG QR Code

// Request Header - Representation-Type: deeplink/zappercode/v2
// This Representation-Type always returns a string
// Returns the deeplink (string) e.g:
https://zapper.com/payWithZapper?qr=http...
```

{% endtab %}

{% tab title="400 Validation failed; Client error" %}

```
bad reqeust
```

{% endtab %}

{% tab title="500 Server side errors;" %}

```
internal server error
```

{% endtab %}
{% endtabs %}

#### Headers

| Name                | Type   | Description  |
| ------------------- | ------ | ------------ |
| Representation-Type | string | MyrLlAOalLVQ |
| Content-Type        | string | MFlk4F9Kc2fE |
| Accept              | string | oMKc9XVijAW1 |
| Authorization       | string | vuvDo6lyllkY |

#### Request Body

| Name              | Type   | Description  |
| ----------------- | ------ | ------------ |
| subMerchant       | object | 0hIcQRxrEVqM |
| externalReference | string | suV6HajIMDHb |
| siteReference     | string | a60yVvvVba4D |
| currencyISOCode   | string | AAN1JV6v7hnH |
| amount            | number | KOJ9HjCk2Oja |
| lineItems         | array  | yTLR4lOSs5uY |
| origin            | string | pUiIaKU5XquR |
| createdUTCDate    | string | vO91NIhmUGLG |
| originReference   | string | OfwcWr8avZPv |

{% hint style="info" %}
The upload invoice endpoint will return a "reference" response header which is used to identify the invoice in subsequent requests.

This is useful in scenarios where an image is returned instead of the invoice response model.
{% endhint %}

{% hint style="warning" %}
Invoices sent by merchants are typically short-lived, and are expected to be recycled various times throughout a business day. This often means that invoice references used by a business are not unique to a single invoice.

The default representation will only be active for 1 hour.

In the event that your business recycles invoices and communicates recycled invoice references to the Zapper Platform, payment notifications returned may vary.
{% endhint %}

### LineItems

Line-items can be included in your invoices, allowing you to take advantage of Zapper's itemised vouchers and better promote specific items.&#x20;

{% hint style="info" %}
Product code or stock keeping unit (SKU) is required
{% endhint %}

| Field       | Datatype       | Required    | Description                                        |
| ----------- | -------------- | ----------- | -------------------------------------------------- |
| name        | string         | No          | The friendly name of the line item                 |
| productCode | string         | Conditional | The product identifier                             |
| SKU         | string         | Conditional | The stock keeping unit code                        |
| unitPrice   | number         | Yes         | The price for a single unit in cents               |
| categories  | array\<string> | No          | A list of names or codes used to group items       |
| quantity    | number         | No          | The number of items, defaults to 1 if not supplied |

### SubMerchant

Submerchant information is required for aggregator partners with their own merchants.&#x20;

| Field    | Datatype | Required | Description                                                 |
| -------- | -------- | -------- | ----------------------------------------------------------- |
| id       | string   | Yes      | The identifier for the submerchant.                         |
| name     | string   | Yes      | The name of the submerchant.                                |
| mcc      | string   | Yes      | The merchant category code.                                 |
| msisdn   | string   | Yes      | The MSISDN of the submerchant or aggregator.                |
| location | object   | Yes      | The location data for the submerchant. See the model below. |

### Location

Location information that must be submitted with the submerchant information

| Field       | Datatype | Required | Description                                                                                                                                                                   |
| ----------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| address     | string   | Yes      | The submerchant address. Only letters, numbers and spaces will be accepted. All other characters such as commas, periods, hyphens etc. should be removed prior to submission. |
| state       | string   | Yes      | The state province. Only allows up to a 3 letter code. e.g KZN                                                                                                                |
| countryCode | string   | Yes      | The country code. Only the three letter ISO Alpha-3 code is accepted. e.g. ZAF                                                                                                |
| postalCode  | string   | Yes      | The postal code. Only numbers accepted.                                                                                                                                       |
| city        | string   | Yes      | The city name. Only letters and spaces accepted.                                                                                                                              |

## Close Invoice by Zapper's reference

<mark style="color:red;">`DELETE`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/sites/{siteId}/invoices/{reference}`

This endpoint allows you to close an open invoice on the Zapper Platform using the Zapper reference for the invoice. To ensure your customers receive the Zapper Code that is relevant to their payment, it is important that previous invoices are closed off once payments for those invoices has been received.

#### Path Parameters

| Name      | Type   | Description                             |
| --------- | ------ | --------------------------------------- |
| reference | string | Zapper's unique reference to an invoice |

#### Headers

| Name          | Type   | Description                                |
| ------------- | ------ | ------------------------------------------ |
| Authorization | string | Bearer \<integration authentication token> |

{% tabs %}
{% tab title="200 Invoice closed successfully." %}

```
success
```

{% endtab %}
{% endtabs %}

## Close Invoice by Merchant's reference

<mark style="color:red;">`DELETE`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/sites/{siteId}/invoices`

This endpoint allows you to close an open invoice on the Zapper Platform using the external reference for the invoice. To ensure your customers receive the Zapper Code that is relevant to their payment, it is important that previous invoices are closed off once payments for those invoices has been received.

#### Query Parameters

| Name              | Type   | Description                             |
| ----------------- | ------ | --------------------------------------- |
| externalReference | string | The merchant's reference for an invoice |

#### Headers

| Name          | Type   | Description                                |
| ------------- | ------ | ------------------------------------------ |
| Authorization | string | Bearer \<integration authentication token> |

{% tabs %}
{% tab title="200 Invoice closed successfully." %}

```
success
```

{% endtab %}
{% endtabs %}

## Representations

### Representation-Types

<table data-header-hidden><thead><tr><th width="208">Representation-Type</th><th width="232">Description</th><th>Limitations</th><th>Category</th></tr></thead><tbody><tr><td>Representation-Type</td><td>Description</td><td>Limitations</td><td>Category</td></tr><tr><td>zappercode/v2</td><td>A legacy Invoice Representation which includes the merchant Info, invoice amount and other metadata such as instructions to enable/disable certain client features (e.g. show tip and split bill options)</td><td><ul><li>Does not support line items</li></ul></td><td>QR Code</td></tr><tr><td>zappercode/v6</td><td>Similar to v2 in that the code includes some of the invoice information within it, however, the invoice details are encoded and compressed which allows the inclusion of line-items (facilitating line-item voucher support)</td><td><ul><li>Can grow into a dense QR Code which may be difficult to scan with low end cameras.</li></ul></td><td>QR Code</td></tr><tr><td>triggercode/transient</td><td>A short string with only an identifier to a backing value on server side, i.e. No other information is stored within the code. QR Codes are less dense and easier to scan as a result. <strong>Ideal for use in restaurants</strong> when a code of limited length is printed onto a bill</td><td><p></p><ul><li>Fetches Invoice from Zapper server before displaying to user</li><li>Only active for 1 hour</li></ul></td><td>QR Code</td></tr><tr><td>triggercode/dynamic</td><td><p>A physical printed code with only an identifier to a backing value. This code is pre-provisioned on a stand and provided to the merchant. The merchant can then assign the code to a specific site/till.</p><p>Invoice uploads will automatically update/clear the server side backing value. This is <strong>ideal for retail scenarios</strong> where physical codes are set up on the counters at each till.</p></td><td><p></p><ul><li>Fetches Invoice from Zapper server before displaying to user</li></ul><p></p></td><td>QR Code</td></tr><tr><td>deeplink/zappercode/v2</td><td>A special shareable link including a v2 Zapper Code that when clicked, takes the user to the pay screen of the Zapper App</td><td><p></p><ul><li>Some older devices do not link directly through to app</li><li>Does not support line items.</li></ul></td><td>Link</td></tr><tr><td>deeplink/zappercode/v6</td><td>A special shareable link including a v6 Zapper Code that when clicked, takes the user to the pay screen of the Zapper App</td><td><ul><li>Some older devices do not link directly through to app</li></ul></td><td>Link</td></tr></tbody></table>

### Supported Accept Headers For Representation Categories

{% hint style="info" %}
If the Accept header is set to "application/json", the Representation-Type header is ignored
{% endhint %}

{% hint style="info" %}
If the Accept header is set as "text/plain", but the caller requires a QR Code, either generate the QR Code from the string that is returned or change the accept header to "image/svg+xml" or "image/png" to have the QR Code generated by the invoice service.
{% endhint %}

{% hint style="info" %}
For Representations categorized as "Link", only the text/plain header is supported.
{% endhint %}

| Representation Category | Supported Accept Headers                                                                     |
| ----------------------- | -------------------------------------------------------------------------------------------- |
| QR Code                 | <ul><li>Accept: text/plain</li><li>Accept: image/svg+xml</li><li>Accept: image/png</li></ul> |
| Link                    | <p></p><ul><li>Accept: text/plain</li></ul>                                                  |