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": "CREDIT_CARD",
    "hppSuccessCallbackUrl": "http://localhost:3000/api/hpp/success",
    "hppFailureCallbackUrl": "http://localhost:3000/api/hpp/failure",
    "hppRespDataFormat": 4,
    "transactionInfo": {
      "referenceId": "WS_{{$randomBankAccount}}",
      "invoiceId": "WS_{{$randomBankAccount}}",
      "amount": 10,
      "currency": "EUR",
      "description": "payment"
    }
  }
}

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_PURCHASE)
`merchantUid`	String	7-15	Required	Unique merchant identifier
`storeId`	Number	N/A	Required	The store ID where the purchase is made
`hppKey`	String	20-40	Required	HPP key for secure purchase initiation
`paymentMethod`	String	5-20	Required	Payment method being used (e.g., CREDIT_CARD)
`hppSuccessCallbackUrl`	String	0-255	Required	URL for success callback from the HPP system
`hppFailureCallbackUrl`	String	0-255	Required	URL for failure callback from the HPP system
`hppRespDataFormat`	Number	1-3	Required	Response data format for the HPP system
`transactionInfo.referenceId`	String	1-50	Required	Reference ID for the transaction
`transactionInfo.invoiceId`	String	1-50	Required	Invoice ID for the transaction
`transactionInfo.amount`	Number	N/A	Required	Transaction amount (numeric)
`transactionInfo.currency`	String	3	Required	Currency code (e.g., "EUR")
`transactionInfo.description`	String	0-255	Optional	Description of the transaction (e.g., "payment")

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",
    "hppRequestId": "10629",
    "referenceId": "WS_123"
  }
}

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.hppUrl`	String	0-255	URL for the HPP page (to process the payment)
`params.directPaymentLink`	String	0-255	Direct link for processing the payment
`params.orderId`	String	1-50	Order ID for the transaction
`params.hppRequestId`	String	1-50	HPP request ID
`params.referenceId`	String	1-50	Reference ID 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, directPaymentLink), 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.

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",
    "transactionId": 1255515,
    "description": "Hpp 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 merchant identifier
`storeId`	String	7-15	Required	Store ID associated with the refund
`hppKey`	String	20-40	Required	HPP key for secure refund initiation
`amount`	Number	N/A	Required	Refund amount (numeric)
`transactionId`	Number	N/A	Required	Transaction ID being refunded
`description`	String	0-255	Optional	Description of the refund request (e.g., "Hpp refund")

Refund Response Structure

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

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.

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": "WS:6671753970"
  }
}

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 merchant identifier
`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	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",
    "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