Transaction History

Transaction history provides the ability to retrieve a list of all transactions that have been processed.

Please note that the authentication is as per API Authentication.

Get List Payment History by Date range

GET https://apps.zapper.com/api/v1/merchants/{merchantId}/payments

This endpoint will fetch all payments (merchant transaction) for a Zapper merchant using the date range.

Path Parameters

Name	Type	Description
merchantId	number	A merchant must provide their merchant id for the transactions that they request

Query Parameters

Name	Type	Description
startDate	string	A merchant must provide a start date for the transactions that they request UTC Date (2020-12-03T16:54:34.600Z)
endDate	string	A merchant must provide an end date for the transactions that they request UTC Date (2020-12-07T16:54:34.600Z)
merchantSiteId	number	A merchant may provide a merchant site id for the transactions that they request

Headers

Name	Type	Description
Authorization	string	Bearer authorization (Integration token)

200

[
    {
        "merchantId": 12345,
        "merchantName": "Central Perk",
        "merchantSiteId": 12345,
        "merchantSiteName": "Central Perk bar",
        "transactionUTCDate": "2020-12-07T08:02:23.253Z",
        "paymentReference": "GFGFEWG39HF3",
        "customer": "John Smith",
        "currencySymbol": "R",
        "currencyISOCode": "ZAR",
        "paymentStatus": "success",
        "invoicedAmount": 100.00,
        "customerInvoicedAmount": 70.00,
        "tipAmount": 10.00,
        "serviceChargeAmount": 5.00,
        "redeemedVouchers": [
            {
                "name": "50% Off",
                "amount": 42.50,
                "liable": "merchant"
            },
            {
                "name": "Lunch voucher",
                "amount": 20.00,
                "liable": "zapper"
            }
        ],
        "processedAmount": 85.00,
        "customerPaidAmount": 22.50,
        "processingFeeAmount": 1.87,
        "processingPercentageFee": 2.20,
        "processingFixedFee": 0.50,
        "processingFeeTax": 0.28,
        "settlementAmount": 40.35,
        "settlementStatus": "settled",
        "settlementUTCDate": "2020-12-08T08:02:23.253Z",
        "paymentMethodType": "visa",
        "invoiceExternalReference": "Bill123456Bill123456",
        "externalTransactionId": "12345-1864d-49dsfs-dfs4e",
        "invoiceReference": "HKEWR373",
        "otherReferences": [
            {
                "name": "SiteNameOverride",
                "value": "Y29vbE5hbWU="
            }
        ]
    }
]

400

401

Get Payment by Merchant Id and Zapper ID

GET https://apps.zapper.com/api/v1/merchants/{merchantId}/payments/{zapperId}

This endpoint will fetch a single payment using the Payment Reference (Zapper ID) for a specific merchant.

Path Parameters

Name	Type	Description
merchantId	number	The merchant identifier
zapperId	string	The payment reference (Zapper ID)

Headers

Name	Type	Description
Authorization	string	Bearer authorization (Integration token)

200

[
    {
        "merchantId": 12345,
        "merchantName": "Central Perk",
        "merchantSiteId": 12345,
        "merchantSiteName": "Central Perk bar",
        "transactionUTCDate": "2020-12-07T08:02:23.253Z",
        "paymentReference": "GFGFEWG39HF3",
        "customer": "John Smith",
        "currencySymbol": "R",
        "currencyISOCode": "ZAR",
        "paymentStatus": "success",
        "invoicedAmount": 100.00,
        "customerInvoicedAmount": 70.00,
        "tipAmount": 10.00,
        "serviceChargeAmount": 5.00,
        "redeemedVouchers": [
            {
                "name": "50% Off",
                "amount": 42.50,
                "liable": "merchant"
            },
            {
                "name": "Lunch voucher",
                "amount": 20.00,
                "liable": "zapper"
            }
        ],
        "processedAmount": 85.00,
        "customerPaidAmount": 22.50,
        "processingFeeAmount": 1.87,
        "processingPercentageFee": 2.20,
        "processingFixedFee": 0.50,
        "processingFeeTax": 0.28,
        "settlementAmount": 40.35,
        "settlementStatus": "settled",
        "settlementUTCDate": "2020-12-08T08:02:23.253Z",
        "paymentMethodType": "visa",
        "invoiceExternalReference": "Bill123456Bill123456",
        "externalTransactionId": "12345-1864d-49dsfs-dfs4e",
        "invoiceReference": "HKEWR373",
        "otherReferences": [
            {
                "name": "SiteNameOverride",
                "value": "Y29vbE5hbWU="
            }
        ]
    }
]

400

401

Response Model

Version 2

Payment Notification

FIeld	DataType	Description
merchantId	number	The ID of the Merchant (MID)
merchantName	string	Name of merchant
merchantSiteId	number	The ID of the site where the transaction was made
transactionUTCDate	string	UTC Date and time of the transaction
paymentReference	string	Zapper's payment reference (Zapper ID)
customer	string	Name of the customer who made the transaction
currencySymbol	string	The currency symbol that was paid by the customer
currencyISOCode	string	The currency ISO code that was paid by the customer
paymentStatus	string	The outcome of the payment
invoicedAmount	decimal	The amount of the bill (Bill Amount)
customerInvoicedAmount	decimal	The amount the customer is electing to pay to the merchant(Customer Bill Amount)
tipAmount	decimal	The tip amount paid by the customer
serviceChargeAmount	number	An additional amount added to a bill by a merchant
redeemedVouchers	List<RedeemedVouchers>	A list of redeemed vouchers amounts and who is liable respectively
processedAmount	decimal	The amount that was processed by Zapper on behalf of the merchant
customerPaidAmount	decimal	The Amount that goes off the customer payment methods (excluding vouchers)
processingFeeAmount	number	The processing fee that was charged by Zapper for the transaction
processingPercentageFee	decimal	The percentage rate charged by Zapper for processing the transaction
processingFixedFee	decimal	The fixed amount charged by Zapper for processing the transaction
processingFeeTax	decimal	The Tax amount that is included in the processing fee
settlementAmount	decimal	The amount that was settled to the merchant for the transaction
settlementStatus	string	Status to indicate whether the transaction has been settled to the merchant
settlementUTCDate	string	UTC date that the transaction was settled to a merchants account
paymentMethodType	string	The type of payment used by the customer (Payment Method)
invoiceExternalReference	string	Merchant's invoice reference
externalTransactionId	string	The brand id of the payment gateway.
invoiceReference	string	A Unique identifier that is sent by the merchant
otherReferences	List<OtherReferences>	Custom fields that are completed by merchants customers

RedeemedVouchers

Field	DataType	Description
name	string	Name of the voucher that was redeemed
amount	decimal	The amount that was redeemed
liable	string	liability of the redeemed voucher (zapper | merchant)

OtherReferences

Field	DataType	Description
name	string	The name of the reference
value	string	The value of the reference

SettlementStatus

Value	Description
pending	The payment not yet settled
settled	The payment has been settled to the merchant
void	The transaction has been void
not applicable	The payment is not applicable for settlement (processing | Failed)

PaymentMethodType

Value	Description
mastercard	The type of payment used by the customer
visa	The type of payment used by the customer
voucher	The voucher is used as the payment method
external	The payment was processed by an external entity