> For the complete documentation index, see [llms.txt](https://zapper.gitbook.io/zapper-platform/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zapper.gitbook.io/zapper-platform/payment-details.md).

# Payment Details

This endpoint allows for the partner to retrieve the status of a Zapper processed payment.

## Status

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

Retrieves the payment details for the payment reference.

#### Path Parameters

| Name             | Type   | Description                  |
| ---------------- | ------ | ---------------------------- |
| paymentReference | string | The reference of the payment |

#### Headers

| Name          | Type   | Description                                                                                   |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| Authorization | String | <p>Bearer \<Identity Token><br>The identity token received from the service account login</p> |
| x-api-key     | string | Authentication Key                                                                            |

{% tabs %}
{% tab title="200 Payment details returned for the payment reference and the customer." %}

```javascript
{
    "reference": "00000000-0000-0000-0000-000000000000",
    "paymentReference": "4G3GR707EW0QZ0G1M0",
    "merchantName": "Zapper Merchant",
    "status": 1,
    "paymentMethodLabel": "**** 0002",
    "currencyISOCode": "ZAR",
    "invoicedAmount": 1000,
    "amount": 1000,
    "tipAmount": 200,
    "processedAmount": 1200,
    "modifiedUTCDate": "0001-01-01T00:00:00.000Z",
    "errors": [{
            "errorReference": 10,
            "message": "Your transaction has been declined by your bank",
        }]
}
```

{% endtab %}

{% tab title="404 Payment details not found for the provided reference for the customer." %}

```
```

{% endtab %}
{% endtabs %}

## History

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

Retrieves the payment history for the identity provided. The result set will be ordered by the latest order first.

#### Query Parameters

| Name              | Type   | Description                                                                                                                           |
| ----------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| customerReference | string | Filter on customer reference.                                                                                                         |
| page              | string | <p>The page number.<br><em>Default: 1</em></p>                                                                                        |
| pageSize          | string | <p>The number of items to be returned in the response.<br><em>Default: 50</em><br><em>Results are limited to 50 per request.</em></p> |

#### Headers

| Name          | Type   | Description                                                                                   |
| ------------- | ------ | --------------------------------------------------------------------------------------------- |
| Authorization | string | <p>Bearer \<Identity Token><br>The identity token received from the service account login</p> |
| x-api-key     | string | Authentication Key                                                                            |

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

```javascript
{
    "payments": [{
        "reference": "00000000-0000-0000-0000-000000000000",
        "invoiceReference": "00000000-0000-0000-0000-000000000000",
        "invoiceExternalReference": "00000000-0000-0000-0000-000000000000",
        "merchantName": "SyliviaBiller548655",
        "currencyISOCode": "ZAR",
        "invoicedAmount": 1000,
        "paymentReference": "XGKGE3020Q2E8Y4NRD",
        "paymentUTCDate": "2020-10-06T00:00:00.0Z",
        "paymentMethodType": "Card",
        "paymentMethodDescription": "**** 0002",
        "status": "success",
        "tipAmount": 200,
        "processedAmount": 1200,
        "customer": {
            "id": "14c5c567-b062-47ea-b448-06b1a296900a"
        },
        "siteReference": "24054",
    	  "errors": null
    }],
    "previousPage": "/v1/payments?customerReference=14c5c567-b062-47ea-b448-06b1a296900a&page=1&pageSize=20",
    "nextPage": "/v1/payments?customerReference=14c5c567-b062-47ea-b448-06b1a296900a&page=3&pageSize=20",        
}
```

{% endtab %}

{% tab title="204 No payment details found." %}

```
```

{% endtab %}

{% tab title="401 Invalid identity token." %}

```
```

{% endtab %}
{% endtabs %}

### History

| Field        | DataType                              | Description                                                                                                   |
| ------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| payments     | array                                 | List of [payments](/zapper-platform/payment-details.md#payment-details).                                      |
| previousPage | <p>string</p><p><em>optional</em></p> | <p>Link to the previous page.</p><p><em>The link is provided when then page number is greater than 1</em></p> |
| nextPage     | <p>string</p><p><em>optional</em></p> | <p>Link to the next page.</p><p><em>The link is provided when there a next page.</em></p>                     |

### Payment Details

| Field                    | DataType                              | Description                                                                                                 |
| ------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| reference                | string                                | A unique reference for the payment.                                                                         |
| invoiceReference         | <p>string</p><p><em>optional</em></p> | Zapper's invoice reference.                                                                                 |
| invoiceExternalReference | <p>string</p><p><em>optional</em></p> | Merchant's invoice reference.                                                                               |
| merchantName             | string                                | Merchant name.                                                                                              |
| currencyISOCode          | string                                | The Currency ISO code of the invoice.                                                                       |
| invoicedAmount           | number                                | The invoiced amount in cents.                                                                               |
| paymentReference         | string                                | Zapper's payment reference.                                                                                 |
| paymentUTCDate           | string                                | The date of the payment.                                                                                    |
| paymentMethodType        | string                                | Payment method type for processing the payment.                                                             |
| paymentMethodDescription | string                                | The masked value of the payment method.                                                                     |
| status                   | string                                | The [status ](/zapper-platform/payment-details.md#payment-status)of the payment.                            |
| verificationUrl          | <p>string</p><p><em>optional</em></p> | The URL to invoke additional verification when the status is *3 - VerificationRequired.*                    |
| tipAmount                | number                                | The tip amount paid by the customer in cents.                                                               |
| processedAmount          | number                                | <p>The amount processed for the request.<br><em>Including tip.</em></p>                                     |
| customer                 | object                                | The [customer's ](/zapper-platform/payment-details.md#customer)details.                                     |
| siteReference            | string                                | The identifier of the point of sale till. This is required for the routing of Zapper payments and invoices. |
| errors                   | array                                 | List of [errors ](/zapper-platform/payment-details.md#error)related to the transaction.                     |

### Payment Status

| Value                | Description                                                           |
| -------------------- | --------------------------------------------------------------------- |
| processing           | The transaction is processing.                                        |
| success              | The transaction completed successfully.                               |
| failed               | The transaction failed during processing.                             |
| verificationRequired | The transaction verification. A URL will be returned in the response. |

### Customer

| Field     | Datatype                              | Required | Description                         |
| --------- | ------------------------------------- | -------- | ----------------------------------- |
| id        | string                                | yes      | A unique reference for the customer |
| firstName | <p>string</p><p><em>optional</em></p> | Yes      | Name of the customer.               |
| lastName  | <p>string</p><p><em>optional</em></p> | Yes      | Last name of the customer           |

### **Error**

| Field          | Type   | Description                                                                                                                                  |
| -------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| errorReference | string | <p>The error <a href="/zapper-platform/other/errors.md">identifier</a>.</p><p><em>This value can be quoted when contacting support.</em></p> |
| message        | string | The message regarding the error.                                                                                                             |