This step provides instructions for creating an HTML checkout form. The form should include all the necessary information required for the instaPay® WebPay gateway to process the payment, and its form fields should be hidden. Most e-commerce platforms will display a ‘Confirm Order’ or ‘Pay Now’ button. Upon selection, by the consumer, this button will submit the form, redirecting the user to the instaPay® WebPay gateway payment request page.
Form Fields
The checkout or order confirmation page typically serves as the final stage on the e-commerce website. Here, the buyer enters their details and reviews the order before making the payment.
All the necessary fields needed for processing the payment through the instaPay® WebPay gateway will be transferred from the checkout page to the instaPay® WebPay gateway payment request page. Once the form is received, the backend processes of the instaPay® WebPay gateway will be initiated, and the payment request page will be presented, displaying all the available payment options.
The following table provides details about the necessary fields expected to facilitate the payment process through the instaPay® WebPay gateway:
| Field name | Format | Presence | Description |
|---|---|---|---|
Merchant details |
|||
|
m_site_id |
string(20) |
M |
The unique Site ID as per the WebPay website regsitration on the InspaPay Money Manager portal. |
|
m_uuid |
string(36) |
M |
The Merchant’s member UUID as per the account settings on the InstaPay Money Manager portal. |
|
m_account_uuid |
string(36) |
M |
The Merchant’s account UUID as per the account settings on the InstaPay Money Manager portal where the payment is intended to be settled.
|
|
m_message |
string(120) |
O |
A custom message from the Merchant to the buyer |
|
m_category_1 |
string(50) |
O |
Custom field (1) to categorise the transaction |
|
m_category_2 |
string(50) |
O |
Custom field (2) to categorise the transaction |
|
m_category_3 |
string(50) |
O |
Custom field (3) to categorise the transaction |
|
m_site_name |
string(100) |
O |
Custom field to identify the site / location / subsystem where the transaction originated from |
|
m_site_reference |
string(36) |
O |
Custom field used to provide a site / location / subsystem related reference |
Transaction details |
|||
|
m_tx_order_nr |
string(20) |
M |
A unique order number used by the consumer/payer as a reference for the order on the e-commerce platform.
The first 3 characters MUST be set to the Merchant Short/Routing Code. The remaining 17 characters should be unique within the Merchant’s system |
|
m_tx_id |
string(36) |
M |
A unique transaction identifier that can be used to trace the transaction in the merchant system. Recommended UUID (ISO/IEC 9834-8:201) |
|
m_tx_currency |
string(3) |
M |
The currency code applicable to the payment request (ISO4217)
Currently only South African Rand is supported (ZAR) |
|
m_tx_amount |
decimal(33,2) |
M |
The total amount requested by the Merchant for the transaction/order placed by the buyer (e.g., R5.00 = 5.00). |
|
m_tx_item_name |
string(60) |
M |
Custom field to name the item(s) being ordered (e.g. ‘basket of goods’) |
|
m_tx_item_description |
string(60) |
M |
Custom field to describe the item(s) being ordered |
|
m_tx_invoice_nr |
string(50) |
O |
Custom field to specify the invoice number as per the e-commerce platform accounting system |
|
m_tx_document_ref |
string(255) |
O |
Optional user defined URL to provide a link to the underlying document, such as an order or invoice, hosted on an external system |
|
m_tx_due_date |
string(10) |
O |
Date by when Merchant expects payment must be completed. Take note that this is an information field only and cannot prevent payments after the specified date
(UTC Date – ISO8601 yyyy-mm-dd) |
Payment methods |
|||
|
m_card_allowed |
boolean |
O |
Indicator to specify if CREDIT & DEBIT CARD payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_ieft_allowed |
boolean |
O |
Indicator to specify if instantEFT payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_chips_allowed |
boolean |
O |
Indicator to specify if CHIPS iAccount payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_mpass_allowed |
boolean |
O |
Indicator to specify if Scan-to-Pay (previously Masterpass) payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_payat_allowed |
boolean |
O |
Indicator to specify if in-store Pay@ payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_zapper_allowed |
boolean |
O |
Indicator to specify if ZAPPER payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_snapscan_allowed |
boolean |
O |
Indicator to specify if SnapScan payments are allowed. If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
|
m_ozow_allowed |
boolean |
O |
Indicator to specify if instantEFT payments are allowed using OZOW (Capitec Pay included in interface). If not specified in the form, value specified in WebPay profile for website as per InstaPay Money Manager portal is used. |
Subscription card payment details |
|||
|
m_tx_sub_frequency |
enum() |
O |
EVERY, every so many days. 1 being every day, 2 being every 2nd day, and 30 being every 30 day. |
|
m_tx_sub_collection_day |
integer(3) |
C |
The collection day, based on the frequency, when the subscription should go off. If m_tx_sub_frequency specified, then mandatory |
|
m_tx_sub_start_date |
string(255) |
C |
This represents the start date of the subscription which should be at least one day ahead of the creation date.
(UTC Date – ISO8601 yyyy-mm-dd) |
|
m_tx_sub_end_date |
string(255) |
C |
This represents the end date of the subscription.
(UTC Date – ISO8601 yyyy-mm-dd) |
|
m_tx_sub_account_number |
string(255) |
C |
This is the clients account number. |
Payer/Buyer details |
|||
|
b_name |
string(80) |
O |
The payer/buyer’s first names. |
|
b_surname |
string(80) |
O |
The payer/buyer’s surname. |
|
b_email |
string(80) |
O |
The payer/buyer’s email address. |
|
b_mobile |
string(15) |
O |
The payer/buyer’s mobile number. |
|
b_details_required |
boolean |
O |
Indicator to specify the WebPay payment gateway must allow the buyer/payer to specify contact details during the payment process.
Default=’false’ |
Transaction notification options |
|||
|
m_return_url |
string(255) |
O |
Custom URL where the customer (buyer) should be redirected after payment has been successfully processed. |
|
m_notify_url |
string(255) |
O |
Custom URL (webhook) that is used to post the payment notification for this transaction.
If not specified in the form or in the WebPay website profile on InstaPay Money Manager portal, a notification message will not be sent |
|
m_process_url |
string(255) |
O |
Custom URL that is used to post notifications to indicate the process stage and status during the payment phase.
If not specified, process related notifications will not be sent. |
|
m_back2shop_url |
string(255) |
O |
Custom URL that is used to redirect user back to the shop when no payment is selected, and user wants to continue shopping. |
|
m_email_address |
string(80) |
O |
Custom email address where a payment confirmation can be sent to.
This option will only be available from a future version. |
Security check |
|||
|
checksum |
string(50) |
M |
Calculated hash value based on predefined field values and a security key to enable data integrity verification. |