Hosted Payment Page

WaafiPay provides a Hosted Payment Page (HPP) for handling purchases, refunds, and transaction inquiries through a secure, web-based interface. Use the serviceName parameter to specify the action for each transaction.

1. Initiate Purchase

serviceName: HPP_PURCHASE
Purpose: Redirects customers to a secure HPP to complete their transaction.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$randomUUID}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "HPP_PURCHASE",
    "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "storeId": {{STORE_ID}},
    "hppKey": "{{HPP_KEY}}",
    "paymentMethod": "MWALLET_ACCOUNT",
    "hppSuccessCallbackUrl": "{{redirect_callback_URL}}/hpp/success",
    "hppFailureCallbackUrl": "{{redirect_callback_URL}}/hpp/failure",
    "hppRespDataFormat": 1,
     "payerInfo": {
        "subscriptionId": "252611111111"
    },
    "transactionInfo": {
      "referenceId": "422334",
      "amount": 10,
      "currency": "USD",
      "description": "Payment for order #422334"
    }
  }
}

Request Parameters

Parameter	Data Type	Length	Presence	Description
`schemaVersion`	String	5	Constant	API schema version (e.g. "1.0")
`requestId`	String	36 (UUID)	Required	Unique request identifier (e.g. UUID)
`timestamp`	String	20	Required	Date and time of the request
`channelName`	String	3-10	Constant	The channel through which the request was made (e.g. WEB )
`serviceName`	String	15-25	Constant	The name of the service being called (e.g. HPP_PURCHASE)
`merchantUid`	String	7-15	Required	Unique identifier provided by WaafiPay upon merchant account setup
`storeId`	Number	10-50	Required	Unique identifier provided by WaafiPay store account setup
`hppKey`	String	20-40	Required	Unique alphanumeric string assigned by WaafiPay upon merchant account activation
`paymentMethod`	String	5-20	Required	Payment method being used (e.g. MWALLET_ACCOUNT from Waafi/EVCPlus, Zaad and Sahal)
`subscriptionId`	String	1-50	Required	Customer mobile number in full international format, starting with the country code (e.g., `252611111111`). Do not include `+` or leading zeros. This will pre-fill the HPP with the customer's phone number and will not be editable by the customer. Required for MWALLET_ACCOUNT payment method.
`hppSuccessCallbackUrl`	String	0-255	Required	URL we'll call after a successful payment. Must be reachable via HTTPS and return HTTP 200.
`hppFailureCallbackUrl`	String	0-255	Required	URL we'll call if the payment fails or is aborted. Must also be HTTPS.
`hppRespDataFormat`	Number	1-3	Required	Format of the data we include in our callback: 1= POST, 2= GET, 4= Result Token.
`transactionInfo.referenceId`	String	1-50	Required	Your unique internal transaction or order reference (e.g. order number, invoice ID, or bill number). Used for querying and reconciliation. Only letters, numbers, dashes, underscores, and dots are allowed.
`transactionInfo.amount`	Number	N/A	Required	Amount to be charged for the customer (numeric) in two decimal places
`transactionInfo.currency`	String	3	Required	ISO 4217 currency code for the transaction (e.g. USD, SLSH, DJF)
`transactionInfo.description`	String	0-255	Optional	A short description of the order or item being purchased by the customer, e.g. "Payment for order #422334" or "Subscription to premium plan".

Response Structure

{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 09:19:10.131",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "hppUrl": "https://sandbox.waafipay.net/hpp/token/4542676573566A5261366B6A485049715056534A45773D3D",
    "directPaymentLink": "https://sandbox.waafipay.net/hpp/token/4542676573566A5261366B6A485049715056534A45773D3D?r=10629",
    "orderId": "1185941",
    "referenceId": "OrderId_422334"
  }
}

Response Parameters

Parameter	Data Type	Length	Description
`schemaVersion`	String	5	API schema version (e.g., "1.0")
`timestamp`	String	20	Date and time of the response
`responseId`	String	1-50	Unique response identifier
`responseCode`	String	1-10	Response code indicating the result of the request
`errorCode`	String	1-5	Error code (e.g., "0" for success)
`responseMsg`	String	0-255	Human-readable message for the response
`params.hppUrl`	String	0-255	URL for the HPP page (to process the payment)
`params.orderId`	String	1-50	WaafiPay Order ID reference for the transaction
`params.referenceId`	String	1-50	Merchant Reference for the transaction

Summary:

Request Key Parameters: Includes details for initiating an HPP purchase, such as paymentMethod, hppSuccessCallbackUrl, transactionInfo.referenceId, and transactionInfo.amount.
Response Key Parameters: Contains the result of the purchase request, including the URLs for the HPP page hppUrl, the order details (orderId, hppRequestId), and the referenceId of the transaction.

2. Refund Purchase

serviceName: HPP_REFUNDPURCHASE
Purpose: Processes a refund for a previously completed transaction by either using the transactionId or referenceId from the original purchase.

We allow partial refunds, meaning you can refund less than the original transaction amount.

Request Structure

POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$randomUUID}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "HPP_REFUNDPURCHASE",
  "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "storeId": {{STORE_ID}},
    "hppKey": "{{HPP_KEY}}",
    "amount": "10",
    "referenceId": "OrderId_422334",
    "description": "Order refund"
  }
}

Refund Request Parameters

Parameter	Data Type	Length	Presence	Description
`schemaVersion`	String	5	Constant	API schema version (e.g., "1.0")
`requestId`	String	36 (UUID)	Required	Unique request identifier (e.g., UUID)
`timestamp`	String	20	Required	Date and time of the request
`channelName`	String	3-10	Constant	The channel through which the request was made
`serviceName`	String	15-25	Constant	The name of the service being called (e.g., HPP_REFUNDPURCHASE)
`merchantUid`	String	7-15	Required	Unique identifier provided by WaafiPay upon merchant account setup
`storeId`	String	7-15	Required	Unique identifier provided by WaafiPay upon merchant account setup
`hppKey`	String	20-40	Required	Unique alphanumeric string assigned by WaafiPay upon merchant account activation
`amount`	Number	N/A	Required	Refund amount (numeric)
`transactionId`	Number	N/A	Required	Transaction ID being refunded
`referenceId`	String	1-50	Optional	Merchant Reference ID from the original transaction (e.g., "OrderId_422334")
`description`	String	0-255	Optional	Description of the refund request (e.g., "Hpp refund")

Refund Response Structure

{
    "schemaVersion": "1.0",
    "timestamp": "2025-05-05 01:54:47.571",
    "responseId": "e69b9629-4aa3-46e1-b7ce-97e7ebc7a099",
    "responseCode": "2001",
    "errorCode": "0",
    "responseMsg": "RCS_SUCCESS",
    "params": {
        "description": "success",
        "state": "approved",
        "transactionId": "XXX",
        "referenceId": "OrderId_422334"
    }
}

state parameter should be checked to ensure the refund was successful. If state is "approved", the refund was successful; if it is "declined" or "failed", the refund failed.

Example Error Response

  {
    "schemaVersion": "1.0",
    "timestamp": "2024-11-05 09:24:48.347",
    "responseId": "12314",
    "responseCode": "5202",
    "errorCode": "E10207",
    "responseMsg": "RCS_TRAN_ALREADY_CANCELLED",
  }

Refund Response Parameters

Parameter	Data Type	Length	Description
`schemaVersion`	String	5	API schema version (e.g., "1.0")
`timestamp`	String	20	Date and time of the response
`responseId`	String	1-50	Unique response identifier
`responseCode`	String	1-10	Response code indicating the result of the request
`errorCode`	String	1-5	Error code (e.g., "E10207" for an error)
`responseMsg`	String	0-255	Human-readable message for the response
`params`	Object	N/A	Empty object, as there is no further data in this response

Summary:

Request Key Parameters: Includes details for initiating an HPP refund, such as amount, transactionId, and a description (e.g., "Hpp refund").
Response Key Parameters: Contains the result of the refund request, including an error code (E10207), message (RCS_TRAN_ALREADY_CANCELLED), and an empty params object indicating no additional data.

3. Retrieve Transaction Information

serviceName: HPP_GETTRANINFO
Purpose: Fetches transaction details for a specific transaction with either transactionId or referenceId.

Request Structure

{
  "schemaVersion": "1.0",
  "requestId": "{{$randomUUID}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "HPP_GETTRANINFO",
  "serviceParams": {
      "merchantUid": "{{MERCHANT_UID}}",
      "storeId": {{STORE_ID}},
      "hppKey": "{{HPP_KEY}}",
      "referenceId": "OrderId_422334"
  }
}

Request Parameters

Parameter	Data Type	Length	Presence	Description
`schemaVersion`	String	5	Constant	API schema version (e.g., "1.0")
`requestId`	String	36 (UUID)	Required	Unique request identifier (e.g., UUID)
`timestamp`	String	20	Required	Date and time of the request
`channelName`	String	3-10	Constant	The channel through which the request was made
`serviceName`	String	15-25	Constant	The name of the service being called (e.g., HPP_GETTRANINFO)
`merchantUid`	String	7-15	Required	Unique identifier provided by WaafiPay upon merchant account setup
`storeId`	String	7-15	Required	Store ID associated with the transaction
`hppKey`	String	20-40	Required	HPP key for secure transaction information fetch
`referenceId`	String	1-50	Required	WaafiPay Reference ID for the transaction

Response Structure

POST /asm
{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 12:19:05.05",
  "responseId": "123114",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "tranStatusDesc": "Approved",
    "amount": "2.0",
    "payerId": "252700000000",
    "paymentMethod": "mwallet_account",
    "description": "payment",
    "tranDate": "2024-11-05 10:58:50.0",
    "currency": "USD",
    "invoiceId": "16F7F28E21EC",
    "referenceId": "16F7F28E21EC",
    "tranAmount": "2.0",
    "transactionId": "126895",
    "tranStatusId": "3",
    "status": "Approved"
  }
}

Response Parameters

Parameter	Data Type	Length	Description
`schemaVersion`	String	5	API schema version (e.g., "1.0")
`timestamp`	String	20	Date and time of the response
`responseId`	String	1-50	Unique response identifier
`responseCode`	String	1-10	Response code indicating the result of the request
`errorCode`	String	1-5	Error code (e.g., "0" for no error)
`responseMsg`	String	0-255	Human-readable message for the response
`params.tranStatusDesc`	String	0-255	Description of the transaction status (e.g., "Approved")
`params.amount`	Number	N/A	Amount of the transaction
`params.payerId`	String	1-50	Payer's unique identifier
`params.paymentMethod`	String	1-50	Payment method used (e.g., "mwallet_account")
`params.description`	String	0-255	Description of the transaction (e.g., "payment")
`params.tranDate`	String	20	Date and time of the transaction
`params.currency`	String	3	Currency code (e.g., "USD")
`params.invoiceId`	String	1-50	Invoice ID for the transaction
`params.tranAmount`	Number	N/A	Amount of the transaction
`params.transactionId`	String	1-50	Transaction ID
`params.tranStatusId`	String	1-10	Status ID of the transaction
`params.status`	String	0-255	Status of the transaction (e.g., "Approved")

Summary:

Request Key Parameters: Includes details for fetching transaction information, such as referenceId, merchantUid, and hppKey.
Response Key Parameters: Contains detailed transaction information, including tranStatusDesc (e.g., "Approved"), payerId, amount, transactionId, and other transaction-specific details such as currency, status, and invoiceId.

On this page