Invoices
Upload invoice
POST
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
Representation-Type
string
The representation-type to be returned. See Representation-Types below. Defaults to "triggercode/transient"
Content-Type
string
application/json
Accept
string
The data-type to be returned. Accepted types are: text/plain application/json image/svg+xml
Authorization
string
Bearer <integration authentication token>
Request Body
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
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.
LineItems
Line-items can be included in your invoices, allowing you to take advantage of Zapper's itemised vouchers and better promote specific items.
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.
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
DELETE
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
reference
string
Zapper's unique reference to an invoice
Headers
Authorization
string
Bearer <integration authentication token>
Close Invoice by Merchant's reference
DELETE
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
externalReference
string
The merchant's reference for an invoice
Headers
Authorization
string
Bearer <integration authentication token>
Representations
Representation-Types
Representation-Type
Description
Limitations
Category
zappercode/v2
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)
Does not support line items
QR Code
zappercode/v6
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)
Can grow into a dense QR Code which may be difficult to scan with low end cameras.
QR Code
triggercode/transient
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. Ideal for use in restaurants when a code of limited length is printed onto a bill
Fetches Invoice from Zapper server before displaying to user
Only active for 1 hour
QR Code
triggercode/dynamic
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.
Invoice uploads will automatically update/clear the server side backing value. This is ideal for retail scenarios where physical codes are set up on the counters at each till.
Fetches Invoice from Zapper server before displaying to user
QR Code
deeplink/zappercode/v2
A special shareable link including a v2 Zapper Code that when clicked, takes the user to the pay screen of the Zapper App
Some older devices do not link directly through to app
Does not support line items.
Link
deeplink/zappercode/v6
A special shareable link including a v6 Zapper Code that when clicked, takes the user to the pay screen of the Zapper App
Some older devices do not link directly through to app
Link
________________________
Supported Accept Headers For Representation Categories
Representation Category
Supported Accept Headers
QR Code
Accept: text/plain
Accept: image/svg+xml
Accept: image/png
Link
Accept: text/plain
Last updated
Was this helpful?