Payments

Use the Zapper Platform to start receiving Zapper payments from your customers now.

The Zapper Platform enables Zapper payments at your business by taking in an invoice and giving you back a Zapper Code linked to the uploaded invoice. Customers can scan that Zapper code and make a payment to your business. The platform will also send through a Payment Notification to a URL that you specify whenever a Zapper payment is made, notifying you of payments so that open invoices can be closed.

Below are the API methods for the uploading and closure of invoices, as well as details on how to start receiving your Payment Notifications.

post
Upload invoice

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.
Request
Response
Headers
Content-Type
required
string
application/json
Accept
required
string
The data-type to be returned. Accepted types are: text/plain application/json image/svg+xml
Authorization
required
string
Bearer <integration authentication token>
Body Parameters
externalReference
optional
string
A merchant's reference for an invoice
siteReference
required
string
The identifier of the point of sale till. This is required for routing of Zapper payments and invoices.
currencyISOCode
required
string
The currency ISO code of the invoice.
amount
required
number
The invoice amount in cents.
lineItems
optional
array
A list of line items. See the model below.
origin
required
string
The provider of the invoice.
createdUTCDate
required
string
The date of the invoice creation.
originReference
optional
string
A unique reference code from the provider
200: OK
Invoice successfully uploaded.
// Request Header - Accept: application/json
{
"siteReference": "site_reference_1",
"currencyISOCode": "ZAR",
"amount": 1500,
"lineItems": [
{
"name": "coke",
"productCode": "ck",
"SKU": "coke1",
"unitPrice": 500,
"categories": [],
"quantity": 1
},
{
"name": "fanta",
"productCode": "fn",
"SKU": "fnta1",
"unitPrice": 500,
"categories": [],
"quantity": 2
}
],
"origin": "micros",
"createdUTCDate": "2019-02-15T13:30:48.9070611Z",
"originReference": "micros_129473",
"reference": "522ccadc-779b-475f-b87a-5410c0c43c3c",
"state": "open"
}
// Request Header - Accept: text/plain
// The base64 encoded Zapper Code string
dGhpcyB3aWxsIGJlIHRoZSBxciBjb2RlIGNvbnR...=
// Request Header - Accept: image/svg+xml
// The base64 encoded svg
data:image/png;base64,iVBORw0KGgoAAAANS...=
400: Bad Request
Validation failed; Client error
bad reqeust
500: Internal Server Error
Server side errors;
internal server error

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.

In the event that your business recycles invoices and communicates recycled invoice references to the Zapper Platform, payment notifications returned may vary.

LineItem

Line-items can be included in your invoices, allowing you to take advantage of Zapper's itemised vouchers and better promote specific items.

Product code or stock keeping unit (SKU) is required

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

delete
Close Invoice by Zapper's reference

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.
Request
Response
Path Parameters
reference
required
string
Zapper's unique reference to an invoice
Headers
Authorization
required
string
Bearer <integration authentication token>
200: OK
Invoice closed successfully.
success

delete
Close Invoice by Merchant's reference

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.
Request
Response
Headers
Authorization
required
string
Bearer <integration authentication token>
Query Parameters
externalReference
required
string
The merchant's reference for an invoice
200: OK
Invoice was successfully closed.
success

Payment Notifications via Webhook

To start receiving Payment Notifications, you need to register your notification URL with Zapper. To do this, please contact Zapper at support@zapper.co.za.

Once this has been registered, Payment Notifications will be sent out automatically by Zapper to your notification URL. This will allow you to reconcile Zapper payments to your open invoices. It may be useful to note that the notification URL can be configured per merchant site.

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

PaymentStatus

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

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

Customer

Field

Datatype

Required

Description

firstName

string

Yes

The name of the customer

lastName

string

Yes

The last name of the customer

Voucher

Field

Datatype

Required

Description

merchantLiable

bool

Yes

Is the merchant liable for the tender

amount

number

Yes

The redeemed amount in cents