Hosted Payment Page
Hosted Payment page API Reference
Last updated
Was this helpful?
Hosted Payment page API Reference
Last updated
Was this helpful?
Zapper Hosted Payment Page is a quick set-up, PCI DSS compliant service that enables customers to complete transactions on a secure payment page hosted by Zapper.
Create Session and Receive RedirectUrl
The merchant initiates the payment process by using Zapper's API. The merchant receives a redirectUrl, which is used to redirect user to the Hosted Payment Page for payment processing.
Redirect User to Zapper's Hosted Payment Page
The merchant is required to redirect the user to the Hosted Payment Page, where they are presented with payment options, such as QR code or card payment.
User Completes the Payment
The user completes the payment process on the Hosted Payment Page.
Zapper Notifies Merchant via Webhook
After payment, Zapper sends a to the merchant's notificationUrl (provided by the merchant when the session is created). The merchant is required to implement a webhook endpoint to receive these payment notifications. It is recommended that the merchant.
Zapper Redirects User Back to Merchant's Store
Upon completing the payment process, Zapper redirects the user back to the merchant's store.
Integration Workflow
POST
https://gateway.zapper.com/api/v3.1/sessions
merchantId*
String
The Zapper merchant ID
merchantSiteId*
String
The Zapper merchant site ID
requestId*
String
The unique identifier for a given request.
merchantOrderId*
String
The identifier or reference of the order generated by the merchant. It provides a way to link the session to a specific order or transaction within the merchant's system.
amount*
Integer
The total value of the transaction in the smallest unit of the currency specified (eg in cents).
currencyISOCode*
String
The 3 letter currency code as per ISO 4217. Currently only 'ZAR' is supported.
notificationUrl*
String
returnUrl*
String
On completing a successful payment, the user is redirected to the provided returnUrl.
cancelUrl*
String
On clicking the back-to-store button, the user is redirected to the cancelUrl.
origin*
String
The site or domain that the request originated from.
siteName
String
The name or identifier of the site associated with the request.
customFields
Array
Additional information that is needed by the merchant in the payment details. See the model below.
GET
https://gateway.zapper.com/api/v3.1/payments
sessionId*
String
The unique identifier for the ecommerce session
merchantSiteId*
String
The Zapper Merchant Site ID
merchantId*
String
The Zapper Merchant ID
GET
https://gateway.zapper.com/api/v3.1/payments/{paymentReference}
paymentReference*
String
The unique identifier of the payment
merchantId*
String
The Zapper Merchant ID
merchantSiteId*
String
The Zapper Merchant Site ID
signature
string
The signature property represents a cryptographic value or digital signature associated with a payment notification webhook.
sessionId
string
The unique identifier for the sessionreference
amount
integer
The total value of the transaction in the smallest unit of the currency specified (eg in cents)
currencyISOCode
string
The 3 letter currency code as per ISO 4217. Currently only 'ZAR' is supported.
merchantOrderId
string
The identifier or reference of the order generated by the merchant. It provides a way to link the session to a specific order or transaction within the merchant's system.
paymentReference
string
A unique identifier assigned to a specific payment.
paymentStatus
The status or outcome of a payment transaction
userMessage
string
A user friendly message. Only populated when paymentStatus is not 'Success'.
paymentUTCDate
string
The UTC date and time of the payment.
status
The API response status. A response other than 'Success' indicates that there was an error on the API level (such as request validation, or errors interpreting the gateway response). Refer to the 'errors' list for more information.
errors
The list of errors if the status is not 'Success'.
Value
Type
Description
1
string
Success
2
string
Failed
Value
Type
Description
1
string
Success
2
string
BadRequest
3
string
NotFound
4
string
Unauthorized
5
string
InternalServer
Value
Type
Description
message
string
A human readable error message
Additional information that is needed by the merchant in the payment details.
Field
Datatype
Required
Description
key
String
Yes
Label or Title of the additional custom field
value
String
Yes
Value of the additional custom field
To ensure the authenticity and integrity of the payment notification data, validating the signature is recommended.
V3.1 - The PaymentNotificationWebhook is used along with the Merchant Site API Key when creating a SHA256 signature hash.
V3 - The PaymentNotificationWebhook is used along with the Merchant API Key when creating a SHA256 signature hash.
The following are an examples of signature validation:
C#
JavaScript:
Java:
Payments: The payment process is as follows:
When the user selects the Zapper payment option on checkout and proceeds to finalize their order, they will be presented with Zapper Hosted Payment page.
If the user prefers the familiar convenience of our dynamic QR code solution, they can proceed by using the Zapper mobile app to effortlessly scan the on-screen QR Code. For users accessing the store from a mobile device, the QR Code is seamlessly replaced with a deep-link button, ensuring a smooth transition to the Zapper application.
However, if the user prefers to use their credit or debit card for payment, they can now opt for the new card payment option. This straightforward method allows users to directly input their card details and complete the payment process right on the spot.
Once the payment is successfully processed – whether through QR code scanning or card payment – users will receive a confirmation in the form of a checkmark symbol. With this assurance of payment, they will then be seamlessly redirected back to the store's default payment confirmation page.
are sent to the provided notificationUrl.