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.
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.
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.
Getting Started
There are four distinct ways in which payments can be retrieved via the payment API.
Using the invoice reference returned from the invoice API.
Using the merchant invoice reference supplied to the invoice API.
Using the ZapperId of the payment itself.
Using the Date range of the transaction.
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
tipAmount
number
The tip amount paid by the customer in cents
tenderedAmount
number
The total tender amount paid by customer (including tips and vouchers)
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
siteId
number
the merchant site identifier
merchantId
number
the merchant identifier
invoiceId
string
the invoice reference returned from the invoice api
Headers
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
siteId
number
the merchant site identifier
merchantId
number
the merchant identifier
invoiceId
string
the invoice reference returned from the invoice api
Headers
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
merchantId
number
the merchant identifier
Query Parameters
externalReference
string
The merchants invoice reference
Headers
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
siteId
string
the merchant site identifier
merchantId
number
the merchant identifier
Query Parameters
externalReference
string
The merchants invoice reference
Headers
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.
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
merchantId
number
the merchant identifier
zapperId
string
the Zapper payment identifier
Headers
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
siteId
number
the merchant site identifier
merchantId
number
the merchant identifier
zapperId
string
the Zapper payment identifier
Headers
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?