# Payments

## Before you start

The intention of the payment API is to fetch payments upon a user action, often by means of a tender button on a point of sale system, as well as provide the ability to retrieve a historical list of all transactions that have been processed.

{% hint style="warning" %}
The payment API will return **all** relevant payments and does not provide an acknowledgement mechanism. Therefore, subsequent requests with the same parameters will return payments that were included in the previous request, and it is up to the client to ensure that these payments are applied correctly. If an acknowledgement mechanism is required, please use the preferred real-time payment notification solutions documented in the [Payment Notifications section](https://zapper.gitbook.io/integrations/payment-notifications/http-webhook).  
{% endhint %}

{% hint style="danger" %}
Payment polling should only be considered as last resort and may result in request throttling. The preferred alternative is to use the real-time payment notification solutions documented in the [Payment Notifications section](https://zapper.gitbook.io/integrations/payment-notifications/http-webhook).
{% endhint %}

## Getting Started

There are four distinct ways in which payments can be retrieved via the payment API.

* Using the [invoice reference](#payments-by-invoice-reference) returned from the invoice API.
* Using the [merchant invoice reference](#payments-by-merchant-reference) supplied to the invoice API.
* Using the [ZapperId](#payments-by-zapper-id) of the payment itself.
* Using the [Date range](#get-list-payment-history-by-date-range) of the transaction.

## Models

### Payment Notification

<table data-header-hidden><thead><tr><th width="282.3333333333333">Field</th><th>DataType</th><th>Description</th></tr></thead><tbody><tr><td>Field</td><td>DataType</td><td>Description</td></tr><tr><td>invoiceReference</td><td>string</td><td>Zapper's invoice reference</td></tr><tr><td>invoiceExternalReference</td><td>string</td><td>Merchant's invoice reference</td></tr><tr><td>currencyISOCode</td><td>string</td><td>The Currency ISO code of the invoice</td></tr><tr><td>invoicedAmount</td><td>number</td><td>The invoiced amount in cents</td></tr><tr><td>paymentReference</td><td>string</td><td>Zapper's payment reference (Zapper ID) </td></tr><tr><td>paymentUTCDate</td><td>string</td><td>The date of the payment</td></tr><tr><td>status</td><td><a href="#paymentstatus">PaymentStatus</a></td><td>The outcome of the payment</td></tr><tr><td>tipAmount</td><td>number</td><td>The tip amount paid by the customer in cents</td></tr><tr><td>tenderedAmount</td><td>number</td><td>The total tender amount paid by customer (including tips and vouchers)</td></tr><tr><td>vouchers</td><td>Array&#x3C;<a href="#voucher">Voucher</a>></td><td>A list of voucher amounts and who is liable respectively</td></tr><tr><td>customer</td><td><a href="#customer">Customer</a></td><td>The Customer's first and last name</td></tr><tr><td>siteReference</td><td>string</td><td>The identifier of the point of sale till. This is required for routing of Zapper payments and invoices.</td></tr></tbody></table>

### PaymentStatus

<table data-header-hidden><thead><tr><th width="365">Value</th><th>Description</th></tr></thead><tbody><tr><td>Value</td><td>Description</td></tr><tr><td>1</td><td>Success</td></tr><tr><td>2</td><td>Failed</td></tr></tbody></table>

### Voucher

| Field          | Datatype | Required | Description                           |
| -------------- | -------- | -------- | ------------------------------------- |
| merchantLiable | bool     | Yes      | Is the merchant liable for the tender |
| amount         | number   | Yes      | The redeemed amount in cents          |

### Customer

| Field     | Datatype | Required | Description                   |
| --------- | -------- | -------- | ----------------------------- |
| firstName | string   | Yes      | The name of the customer      |
| lastName  | string   | Yes      | The last name of the customer |

## Endpoints

### Payments by Invoice Reference

Using the reference returned from the invoice API, payments can be retrieved using the following endpoints.

Payments are limited to a rolling 24 hour window based on the time of a call.

## Get Payments by Invoice Id for Merchant

<mark style="color:blue;">`GET`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/invoices/{invoiceId}/payments`

This endpoint will fetch all payments for a Zapper merchant invoice across all merchant sites

#### Path Parameters

| Name       | Type   | Description                                         |
| ---------- | ------ | --------------------------------------------------- |
| siteId     | number | the merchant site identifier                        |
| merchantId | number | the merchant identifier                             |
| invoiceId  | string | the invoice reference returned from the invoice api |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| x-api-key | string | merchant API key |
| Accept    | string | application/json |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

## Get Payments by Invoice Id for Merchant Site

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

This endpoint will fetch all payments for a Zapper merchant invoice limited to the merchant site.

#### Path Parameters

| Name       | Type   | Description                                         |
| ---------- | ------ | --------------------------------------------------- |
| siteId     | number | the merchant site identifier                        |
| merchantId | number | the merchant identifier                             |
| invoiceId  | string | the invoice reference returned from the invoice api |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| Accept    | string | application/json |
| x-api-key | string | merchant API key |

{% tabs %}
{% tab title="200 " %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

### Payments by Merchant Reference

Fetch all payments using the external merchant reference provided to the invoice API.

Payments are limited to a rolling 24 hour window based on the time of a call.

## Get Payments by Merchant Reference for all sites

<mark style="color:blue;">`GET`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/payments`

This endpoint will fetch all payments for a merchant reference across all merchant sites.

#### Path Parameters

| Name       | Type   | Description             |
| ---------- | ------ | ----------------------- |
| merchantId | number | the merchant identifier |

#### Query Parameters

| Name              | Type   | Description                     |
| ----------------- | ------ | ------------------------------- |
| externalReference | string | The merchants invoice reference |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| Accept    | string | application/json |
| x-api-key | string | merchant API key |

{% tabs %}
{% tab title="200 Payments successfully retrieved." %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

## Get Payments by Merchant Reference for a specific site

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

This endpoint will fetch all payments for a merchant reference for a specific merchant site.

#### Path Parameters

| Name       | Type   | Description                  |
| ---------- | ------ | ---------------------------- |
| siteId     | string | the merchant site identifier |
| merchantId | number | the merchant identifier      |

#### Query Parameters

| Name              | Type   | Description                     |
| ----------------- | ------ | ------------------------------- |
| externalReference | string | The merchants invoice reference |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| Accept    | string | application/json |
| x-api-key | string | merchant API key |

{% tabs %}
{% tab title="200 Payments successfully retrieved." %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

### Payments by Zapper ID

Using the Zapper ID, a single payment can be retrieved using the following endpoints.

{% hint style="info" %}
This method is intended to be used mainly as a support function or to assist with a customer query
{% endhint %}

These payments are available over a 3 month window.

## Get Payment by Merchant Id and Zapper ID

<mark style="color:blue;">`GET`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/payments/{zapperId}`

This endpoint will fetch a single payment using the Zapper ID for a specific merchant.

#### Path Parameters

| Name       | Type   | Description                   |
| ---------- | ------ | ----------------------------- |
| merchantId | number | the merchant identifier       |
| zapperId   | string | the Zapper payment identifier |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| Accept    | string | application/json |
| x-api-key | string | merchant API key |

{% tabs %}
{% tab title="200 Payments successfully retrieved." %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

## Get Payment by Merchant Id, Site Id and Zapper ID

<mark style="color:blue;">`GET`</mark> `https://api.zapper.com/business/api/v1/merchants/{merchantId}/sites/{siteId}/payments/{zapperId}`

This endpoint will fetch a single payment using the Zapper ID for a specific merchant and site.

#### Path Parameters

| Name       | Type   | Description                   |
| ---------- | ------ | ----------------------------- |
| siteId     | number | the merchant site identifier  |
| merchantId | number | the merchant identifier       |
| zapperId   | string | the Zapper payment identifier |

#### Headers

| Name      | Type   | Description      |
| --------- | ------ | ---------------- |
| Accept    | string | application/json |
| x-api-key | string | merchant API key |

{% tabs %}
{% tab title="200 Payments successfully retrieved." %}

```javascript
[
    {
        "vouchers": [],
        "status": 1,
        "invoiceReference": "fbcd55dd-fc56-440b-ba87-2e8286265edc",
        "invoiceExternalReference": "12345",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "269673MQY3NV7DGQDY",
        "paymentUTCDate": "2020-03-04T12:10:21.8994481Z",
        "tipAmount": 0,
        "tenderedAmount": 1000,
        "customer": {
            "firstName": "John",
            "lastName": "Snow"
        }
    }
]
```

{% endtab %}
{% endtabs %}

###