Introduction

Our API (Application Programming Interface) enables client applications to securely communicate with WaafiPay servers using a predefined message format. The structure of our API responses includes key fields that facilitate this communication:

1. channelName: Indicates the request origin, such as WEB, which helps differentiate between various channels.

2. serviceName: Defines the requested operation, including:

   • API_PURCHASE
   • API_CANCELPURCHASE
   • API_PREAUTHORIZE
   • API_PREAUTHORIZE_COMMIT
   • API_PREAUTHORIZE_CANCEL

   This allows clear identification of the specific action being requested.

3. serviceParams: Common parameters within this section include:

   • merchantUid, apiUserId, and apiKey: Authenticate and link requests to the appropriate merchant and API user.
   • paymentMethod: Specifies the type of payment, such as MWALLET_ACCOUNT (payments from Wallet Accounts such as EVC or ZAAD) or MWALLET_BANKACCOUNT (from bank account).
   • referenceId and description: Provide tracking and context for transactions, ensuring consistency across related operations.

4. The referenceId parameter is a unique identifier provided by the merchant’s system. It represents the order ID or transaction ID associated with the transaction. This ID ensures accurate tracking and referencing of the transaction within the merchant’s records and is designed to be unique within the payment system to prevent any duplicate transactions.

Decimal Precision Policy

We accept amounts with up to two decimal places for all transactions. This includes both whole numbers and decimal values.

If a value has more than two decimal places, it will be automatically truncated (not rounded) to two decimal places during processing.

✅ Valid Examples:

• 10 (no decimal places)
• 10.2 (one decimal place)
• 10.23 (two decimal places)

🔄 Automatically Truncated:

• 10.237 → 10.23
• 99.999 → 99.99

Note: The amount used after truncation will be returned in the API response. Make sure to rely on this value for reconciliation and display purposes.

We recommend rounding or truncating the amount before submitting a transaction to ensure consistency and prevent unexpected discrepancies between submitted and processed values.

API Endpoint

• Testing Environment: http://sandbox.waafipay.net/asm
• Production Environment: https://api.waafipay.com/asm

Our API is available in various programming languages, enabling easy integration into a merchant's existing website or application. This structured approach ensures that each request is secure, identifiable, and traceable through a standardized framework.

Response Codes

• 2001 RCS_SUCCESS: Request/Transaction is approved/successful
• 5301 RCS_INVALID_HPPKEY: Transaction cannot be performed due to wrong hpp key
• 5302 RCS_INVALID_HPPTOKEN: Transaction cannot be performed due to wrong hpp Token
• 5303 RCS_INVALID_HPPRESULTTOKEN: Transaction cannot be performed due to wrong hpp Token result
• 5304 RCS_HPP_MERCHANT_REFERENCEID_MISMATCH: Transaction cannot be performed due to mismatch of Transaction Reference
• 5305 RCS_HPP_REQUESTID_MISMATCH: Transaction cannot be performed due to mismatch of Transaction RequestId
• 5306 RCS_HPP_USERACTION_CANCELLED: User cancelled the transaction
• 5307 RCS_HPPTOKEN_EXPIRED: Transaction cannot be performed due to Token expired
• 5308 RCS_HPP_SUBSCRIPTION_ISNOT_ENABLED: Merchant is not allowed for this service type
• 5309 RCS_HPP_USERACTION_TIMEOUT: User didn't process the transaction in 5 minutes