Payments

Payment retrieval API

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.

Getting Started

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

Models

Payment Notification

Field

DataType

Description

invoiceReference

string

Zapper's invoice reference

invoiceExternalReference

string

Merchant's invoice reference

currencyISOCode

string

The Currency ISO code of the invoice

invoicedAmount

number

The invoiced amount in cents

paymentReference

string

Zapper's payment reference (Zapper ID)

paymentUTCDate

string

The date of the payment

status

The outcome of the payment

tipAmount

number

The tip amount paid by the customer in cents

tenderedAmount

number

The total tender amount paid by customer (including tips and vouchers)

vouchers

Array<Voucher>

A list of voucher amounts and who is liable respectively

customer

The Customer's first and last name

siteReference

string

The identifier of the point of sale till. This is required for routing of Zapper payments and invoices.

PaymentStatus

Value

Description

1

Success

2

Failed

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

GET 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

[
    {
        "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"
        }
    }
]

Get Payments by Invoice Id for Merchant Site

GET 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

[
    {
        "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"
        }
    }
]

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

GET 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

[
    {
        "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"
        }
    }
]

Get Payments by Merchant Reference for a specific site

GET 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

[
    {
        "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"
        }
    }
]

Payments by Zapper ID

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

This method is intended to be used mainly as a support function or to assist with a customer query

These payments are available over a 3 month window.

Get Payment by Merchant Id and Zapper ID

GET 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

[
    {
        "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"
        }
    }
]

Get Payment by Merchant Id, Site Id and Zapper ID

GET 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

[
    {
        "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"
        }
    }
]

Last updated

Was this helpful?