WaafiPay

https://docs.waafipay.com/
Admin
WaafiPay is an East African payment gateway that enables merchants to seamlessly accept payments...
Tokens:18,432
Snippets:108
Trust Score:5.1
Update:6 months ago
Show doc for...
Tokens:
Raw
### Register Default Webhook (All Events) Example

Source: https://docs.waafipay.com/webhooks

This example demonstrates the JSON payload structure for registering a default webhook that will receive all types of transaction events.

```json
{
    "serviceParams": {
        "merchantUid": {{MERCHANT_UID}},
        "storeId": {{STORE_ID}},
        "hppKey": {{HPP_KEY}},
        "url": "https://api.example.com/webhook"
    }
}
```

--------------------------------

### Authorization Webhook Headers

Source: https://docs.waafipay.com/webhooks

Example headers for an authorization webhook. Ensure these are present for verification.

```text
X-Webhook-Timestamp: 1755045838
X-Webhook-Event-Id: 1151
X-Webhook-Signature: 19797b9fe0eaaa99e4ad509d53f3c91d1bb16d56de20b2252a21260a31913838
Content-Type: application/json
User-Agent: WPNotifyService
```

--------------------------------

### POST /asm - Get All Webhooks

Source: https://docs.waafipay.com/webhooks

Retrieve a list of all existing webhooks for a merchant.

```APIDOC
## POST /asm - Get All Webhooks

### Description
Retrieve a list of all existing webhooks.

### Method
POST

### Endpoint
/asm

### Request Body
```json
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_LIST",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}"
    }
}
```

### Response
#### Success Response (200)
- **params** (object) - Contains webhook data.
  - **data** (array) - List of webhooks.
    - **id** (string) - The webhook ID.
    - **url** (string) - The webhook URL.
    - **description** (string) - A description of the webhook.
    - **merchantId** (string) - The merchant ID associated with the webhook.
    - **partnerUid** (string) - The partner UID.
    - **merchantName** (string) - The name of the merchant.

#### Response Example
```json
{
    "params": {
        "data": [
            {
                "id": "25",
                "url": "https://app.sample.com/webhook",
                "description": "testing",
                "merchantId": "10165",
                "partnerUid": "400394",
                "merchantName": "WaafiPay Store"
            }
        ]
    }
}
```
```

--------------------------------

### Handle Webhook Test and Events

Source: https://docs.waafipay.com/webhooks

Example implementation for handling test pings and transaction events in a Node.js environment.

```json
{
  "event": "webhook.test",
  "message": "WaafiPay webhook validation ping",
  "merchant_uid": "your-merchant-uid"
}
```

```javascript
app.post('/webhook', async (req, res) => {
  const { event } = req.body;
 
  // Handle test event
  if (event === 'webhook.test') {
    console.log('Received webhook test ping');
    return res.status(200).send('OK');
  }
 
  // For real events, verify signature
  try {
    verifyWebhookSignature(req, process.env.WEBHOOK_SECRET);
 
    // Process authorization or refund events
    if (event === 'authorization') {
      await handleAuthorization(req.body);
    } else if (event === 'refund') {
      await handleRefund(req.body);
    }
 
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).send('Invalid webhook');
  }
});
```

--------------------------------

### Webhook Payload Example

Source: https://docs.waafipay.com/webhooks

This is an example of the JSON payload received for a transaction event. It includes the event type and payment status.

```json
{
  "event": "authorization",
  "payment": {
    "status": "APPROVED",
    "amount": 100.50,
    "reference_id": "ORDER-123"
  }
}
```

--------------------------------

### Node.js Webhook Handler Implementation

Source: https://docs.waafipay.com/webhooks

A complete Node.js example for handling and verifying Waafipay webhooks. It includes signature verification, timestamp checks, and idempotency handling.

```javascript
const crypto = require('crypto');

function verifyWebhook(request, secret) {
  const timestamp = request.headers['x-webhook-timestamp'];
  const eventId = request.headers['x-webhook-event-id'];
  const signature = request.headers['x-webhook-signature'];
  const rawBody = request.rawBody; // Must be raw bytes, not parsed JSON

  // Check timestamp (reject if older than 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    throw new Error('Webhook timestamp too old');
  }

  // Build signing string
  const signingString = `${timestamp}.${eventId}.${rawBody}`;

  // Compute HMAC
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(signingString)
    .digest('hex');

  // Compare using constant-time comparison
  if (!crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  )) {
    throw new Error('Invalid signature');
  }

  return true;
}

// Track processed events to prevent duplicates
const processedEvents = new Set();

app.post('/webhook', async (req, res) => {
  const { event, payment } = req.body;
  const eventId = req.headers['x-webhook-event-id'];

  try {
    // 1. Handle test events
    if (event === 'webhook.test') {
      return res.status(200).send('OK');
    }

    // 2. Verify signature
    verifyWebhook(req, process.env.WEBHOOK_SECRET);

    // 3. Check for duplicates
    if (processedEvents.has(eventId)) {
      return res.status(200).send('OK');
    }

    // 4. Process based on event and status
    if (event === 'authorization') {
      if (payment.status === 'APPROVED') fulfillOrder(payment.order_id);
      else if (['DECLINED', 'FAILED'].includes(payment.status)) cancelOrder(payment.order_id);
      else if (['EXPIRED', 'TIMEOUT', 'CANCELED'].includes(payment.status)) markAbandoned(payment.order_id);
    } else if (event === 'refund') {
      if (payment.status === 'APPROVED') processRefund(payment.transaction_id);
      else if (['DECLINED', 'FAILED', 'TIMEOUT'].includes(payment.status)) handleRefundFailure(payment.transaction_id);
    }

    // 5. Mark as processed
    processedEvents.add(eventId);

    // 6. Return success
    res.status(200).send('OK');
  } catch (error) {
    console.error('Webhook error:', error);
    res.status(400).send('Invalid webhook');
  }
});
```

--------------------------------

### Example Error Refund Response

Source: https://docs.waafipay.com/hpp-api

This example shows an error response for a refund request. Pay attention to 'responseCode', 'errorCode', and 'responseMsg' for diagnosing issues. An example error code is 'E10207' for a transaction that has already been cancelled.

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

--------------------------------

### Refund Webhook Headers

Source: https://docs.waafipay.com/webhooks

Example headers for a refund webhook. These are crucial for verifying the authenticity of the refund event.

```text
X-Webhook-Timestamp: 1729587478
X-Webhook-Event-Id: 1152
X-Webhook-Signature: a3b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d3e2f1a0b9
Content-Type: application/json
User-Agent: WPNotifyService
```

--------------------------------

### Handle Waafipay Events and Statuses

Source: https://docs.waafipay.com/webhooks

This JavaScript code demonstrates how to handle incoming webhooks by checking the event type and payment status. It provides example logic for fulfilling orders, canceling them, or handling refund outcomes.

```javascript
// Handle based on event type and status
if (event === 'authorization') {
  if (status === 'APPROVED') fulfillOrder(payment.order_id);
  else if (['DECLINED', 'FAILED'].includes(status)) cancelOrder(payment.order_id);
  else if (['EXPIRED', 'TIMEOUT', 'CANCELED'].includes(status)) markAbandoned(payment.order_id);
}
 
if (event === 'refund') {
  if (status === 'APPROVED') processRefund(payment.transaction_id);
  else if (['DECLINED', 'FAILED', 'TIMEOUT'].includes(status)) handleRefundFailure(payment.transaction_id);
}
```

--------------------------------

### Webhook Registration Response

Source: https://docs.waafipay.com/webhooks

This is an example of a successful response after registering a webhook. It includes a secret key for verifying incoming webhook requests.

```json
{
    "schemaVersion": "1.0",
    "timestamp": "2024-02-08 04:38:42.938",
    "responseId": "{{$guid}}",
    "responseCode": "2001",
    "errorCode": "0",
    "responseMsg": "Webhook created successfully",
    "params": {
        "secret": "your_secret"
    }
}
```

--------------------------------

### Authorization Transaction Payload

Source: https://docs.waafipay.com/webhooks

Example structure of an authorization event notification.

```json
{
  "event": "authorization",
  "customer_identity": "252612345678",
  "cardholder_name": "John Doe",
  "merchant_id": 10165,
  "merchant_uid": "M400394",
  "user_id": "400394",
  "payment": {
    "transaction_id": "1303630",
    "order_id": "ORD-2024-001",
    "transfer_code": "ISR0011303630",
    "amount": 100.50,
    "currency": "USD",
    "payment_method": "MWALLET_ACCOUNT",
    "status": "APPROVED",
    "reference_id": "REF-2024-4567",
    "channel": "WEB",
    "description": "Payment for order ORD-2024-001",
    "date": "2025-08-13 15:04:05"
  }
}
```

--------------------------------

### Cancel Preauthorization Response

Source: https://docs.waafipay.com/preauthorization-api

Example response structure returned upon a successful cancellation request.

```json
{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:59:59.986",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "description": "success",
    "state": "approved",
    "transactionId": "1268665",
    "referenceId": "1234"
  }
}
```

--------------------------------

### Authorization Webhook Body

Source: https://docs.waafipay.com/webhooks

Example JSON payload for an authorization webhook. This contains details about the payment authorization event.

```json
{
    "event": "authorization",
    "customer_identity": "252612345678",
    "cardholder_name": "Ahmed Hassan",
    "merchant_id": 10165,
    "merchant_uid": "M400394",
    "user_id": "400394",
    "payment": {
        "transaction_id": "1303630",
        "order_id": "ORD-2024-001",
        "transfer_code": "ISR0011303630",
        "amount": 60.2,
        "currency": "USD",
        "payment_method": "MWALLET_ACCOUNT",
        "status": "APPROVED",
        "reference_id": "REF-2024-4567",
        "channel": "WEB",
        "description": "Payment for order ORD-2024-001",
        "date": "2025-08-12 17:59:15"
    }
}
```

--------------------------------

### Successful Refund Response Structure

Source: https://docs.waafipay.com/hpp-api

This is an example of a successful refund response. Always check the 'state' parameter within the 'params' object to confirm if the refund was 'approved'. Other states like 'declined' or 'failed' indicate an unsuccessful refund.

```json
{
    "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"
    }
}
```

--------------------------------

### Refund Transaction Webhook Example

Source: https://docs.waafipay.com/webhooks

This JSON object represents a webhook payload for a refund transaction. It includes details about the event, merchant, user, and the specific payment that was refunded.

```json
{
  "event": "refund",
  "merchant_id": 10165,
  "user_id": "400394",
  "merchant_uid": "M400394",
  "payment": {
    "transaction_id": "1314550",
    "transfer_code": "ISR0011314550",
    "amount": 50.25,
    "currency": "USD",
    "status": "APPROVED",
    "reference_id": "REFUND-2024-8901",
    "date": "2025-08-14 10:30:00"
  }
}
```

--------------------------------

### Refund Webhook Body

Source: https://docs.waafipay.com/webhooks

Example JSON payload for a refund webhook. This payload contains details related to a refund transaction.

```json
{
    "event": "refund",
    "merchant_id": 10165,
    "user_id": "400394",
    "merchant_uid": "M400394",
    "payment": {
        "transaction_id": "1314550",
        "transfer_code": "ISR0011314550",
        "amount": 30.5,
        "currency": "USD",
        "status": "APPROVED",
        "reference_id": "REFUND-2024-8901",
        "date": "2025-08-14 10:30:00"
    }
}
```

--------------------------------

### Webhook Security and Best Practices

Source: https://docs.waafipay.com/webhooks

Guidelines for implementing HMAC signature verification and handling common webhook integration issues.

```APIDOC
## Security: HMAC Signature Verification

### Description
Ensure the authenticity of incoming webhooks by verifying the HMAC signature provided in the request headers.

### Verification Steps
1. Capture the raw HTTP body before parsing JSON.
2. Use the shared secret to compute the HMAC signature.
3. Compare the computed signature with the header value.
4. Validate the timestamp (reject if > 5 minutes old to prevent replay attacks).

## Common Issues
- **Signature verification fails**: Capture raw HTTP body before parsing JSON.
- **Webhooks not received**: Ensure URL is publicly accessible.
- **Duplicate processing**: Track event IDs using `X-Webhook-Event-Id`.
- **Timeout errors**: Return 200 OK immediately and queue for async processing.
```

--------------------------------

### Initiate Purchase with HPP

Source: https://docs.waafipay.com/hpp-api

Initiates a purchase by redirecting customers to a secure Hosted Payment Page (HPP) to complete their transaction. This endpoint is used for the `HPP_PURCHASE` service.

```APIDOC
## POST /asm

### Description
Initiates a purchase by redirecting customers to a secure Hosted Payment Page (HPP) to complete their transaction.

### Method
POST

### Endpoint
/asm

### Parameters
#### Request Body
- **schemaVersion** (String) - Constant - API schema version (e.g. "1.0")
- **requestId** (String) - Required - Unique request identifier (e.g. UUID)
- **timestamp** (String) - Required - Date and time of the request
- **channelName** (String) - Constant - The channel through which the request was made (e.g. WEB)
- **serviceName** (String) - Constant - The name of the service being called (e.g. HPP_PURCHASE)
- **serviceParams** (Object) - Required - Contains parameters specific to the service.
  - **merchantUid** (String) - Required - Unique identifier provided by WaafiPay upon merchant account setup
  - **storeId** (Number) - Required - Unique identifier provided by WaafiPay store account setup
  - **hppKey** (String) - Required - Unique alphanumeric string assigned by WaafiPay upon merchant account activation
  - **paymentMethod** (String) - Required - Payment method being used (e.g. MWALLET_ACCOUNT)
  - **hppSuccessCallbackUrl** (String) - Required - URL we'll call after a successful payment.
  - **hppFailureCallbackUrl** (String) - Required - URL we'll call if the payment fails or is aborted.
  - **hppRespDataFormat** (Number) - Required - Format of the data we include in our callback: 1= POST, 2= GET, 4= Result Token.
  - **payerInfo** (Object) - Optional - Information about the payer.
    - **subscriptionId** (String) - Required for MWALLET_ACCOUNT - Customer mobile number in full international format.
  - **transactionInfo** (Object) - Required - Information about the transaction.
    - **referenceId** (String) - Required - Your unique internal transaction or order reference.
    - **amount** (Number) - Required - Amount to be charged for the customer.
    - **currency** (String) - Required - ISO 4217 currency code for the transaction.
    - **description** (String) - Optional - A short description of the order or item being purchased.

### Request Example
```json
{
  "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"
      }
  }
}
```

### Response
#### Success Response (200)
- **schemaVersion** (String) - API schema version (e.g., "1.0")
- **timestamp** (String) - Date and time of the response
- **responseId** (String) - Unique response identifier
- **responseCode** (String) - Response code indicating the result of the request
- **errorCode** (String) - Error code (e.g., "0" for success)
- **responseMsg** (String) - Human-readable message for the response
- **params** (Object) - Contains response parameters.
  - **hppUrl** (String) - URL for the HPP page (to process the payment)
  - **directPaymentLink** (String) - Direct payment link for the HPP page.
  - **orderId** (String) - WaafiPay Order ID reference for the transaction
  - **referenceId** (String) - Merchant Reference for the transaction

#### Response Example
```json
{
  "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"
  }
}
```
```

--------------------------------

### WaafiPay Purchase Request

Source: https://docs.waafipay.com/purchase-api

Use this structure to initiate a purchase. Ensure `serviceName` is set to `API_PURCHASE` and populate `payerInfo` and `transactionInfo` with relevant details.

```json
POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "API_PURCHASE",
    "serviceParams": {
        "merchantUid": {{MERCHANT_UID}},
        "apiUserId": {{API_USER_ID}},
        "apiKey": {{API_KEY}},
        "paymentMethod": "MWALLET_ACCOUNT",
        "payerInfo": {
            "accountNo": "252611111111"
        },
        "transactionInfo": {
            "referenceId": "{{$randomBankAccount}}",
            "invoiceId": "154",
            "amount": "10",
            "currency": "USD",
            "description": "{{$randomLoremSentence}}"
        }
    }
}

```

--------------------------------

### POST /asm (Purchase)

Source: https://docs.waafipay.com/purchase-api

Initiates a purchase transaction to charge a payer's account.

```APIDOC
## POST /asm

### Description
Charges the payer's account, completing the payment.

### Method
POST

### Endpoint
/asm

### Parameters
#### Request Body
- **schemaVersion** (String) - Constant - API schema version (e.g., "1.0")
- **requestId** (String) - Required - Unique request identifier (e.g., UUID)
- **timestamp** (String) - Required - Date and time of the request
- **channelName** (String) - Constant - The channel through which the request was made
- **serviceName** (String) - Constant - Set to "API_PURCHASE"
- **merchantUid** (String) - Required - Unique identifier provided by WaafiPay
- **apiUserId** (String) - Required - API user identifier
- **apiKey** (String) - Required - API key for authentication
- **paymentMethod** (String) - Required - Payment method (e.g., "MWALLET_ACCOUNT")
- **payerInfo.accountNo** (String) - Required - Payer's mobile number in international format
- **transactionInfo.referenceId** (String) - Required - Unique internal transaction reference
- **transactionInfo.invoiceId** (String) - Required - Invoice ID
- **transactionInfo.amount** (Number) - Required - Transaction amount in two decimal places
- **transactionInfo.currency** (String) - Required - ISO 4217 currency code
- **transactionInfo.description** (String) - Optional - Transaction description

### Request Example
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PURCHASE",
  "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "apiUserId": "{{API_USER_ID}}",
    "apiKey": "{{API_KEY}}",
    "paymentMethod": "MWALLET_ACCOUNT",
    "payerInfo": {
      "accountNo": "252611111111"
    },
    "transactionInfo": {
      "referenceId": "{{$randomBankAccount}}",
      "invoiceId": "154",
      "amount": "10",
      "currency": "USD",
      "description": "{{$randomLoremSentence}}"
    }
  }
}

### Response
#### Success Response (200)
- **responseCode** (String) - Response code
- **responseMsg** (String) - Response message
- **params.transactionId** (String) - The generated transaction ID

#### Response Example
{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 09:04:44.741",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "accountNo": "252611****1111",
    "accountType": "MWALLET_ACCOUNT",
    "state": "APPROVED",
    "merchantCharges": "0.1",
    "referenceId": "1234",
    "transactionId": "1268666",
    "issuerTransactionId": "ISR0011268666",
    "txAmount": "10.0"
  }
}
```

--------------------------------

### Initiate Purchase Request

Source: https://docs.waafipay.com/hpp-api

The POST request structure for initiating a payment transaction via the HPP_PURCHASE service.

```json
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"
    }
  }
}
```

--------------------------------

### Retrieve All Webhooks

Source: https://docs.waafipay.com/webhooks

Request to list all existing webhooks for a merchant.

```json
POST /asm
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_LIST",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}",
    }
}
```

```json
{
    "params": {
        "data": [
            {
                "id": "25",
                "url": "https://app.sample.com/webhook",
                "description": "testing",
                "merchantId": "10165",
                "partnerUid": "400394",
                "merchantName": "WaafiPay Store"
            }
        ]
    }
}
```

--------------------------------

### WaafiPay API Overview

Source: https://docs.waafipay.com/api-introduction

General information regarding the API request structure, authentication parameters, and decimal precision handling.

```APIDOC
## WaafiPay API Request Structure

### Description
All API requests must follow a standardized format to ensure secure communication and proper transaction tracking.

### Parameters
- **channelName** (string) - Required - Indicates the request origin (e.g., "WEB").
- **serviceName** (string) - Required - Defines the operation (API_PURCHASE, API_CANCELPURCHASE, API_PREAUTHORIZE, API_PREAUTHORIZE_COMMIT, API_PREAUTHORIZE_CANCEL).
- **serviceParams** (object) - Required - Contains authentication and transaction details:
  - **merchantUid** (string) - Required - Merchant identifier.
  - **apiUserId** (string) - Required - API user identifier.
  - **apiKey** (string) - Required - Authentication key.
  - **paymentMethod** (string) - Required - Type of payment (e.g., MWALLET_ACCOUNT, MWALLET_BANKACCOUNT).
  - **referenceId** (string) - Required - Unique alphanumeric identifier for the transaction (supports alphanumeric, dash, underscore, dot).
  - **description** (string) - Optional - Context for the transaction.

### Decimal Precision Policy
- Amounts are accepted with up to two decimal places.
- Values with more than two decimal places are automatically truncated (not rounded) to two decimal places.
- Example: 10.237 becomes 10.23.
```

--------------------------------

### PreAuthorization API

Source: https://docs.waafipay.com/preauthorization-api

Initiates a preauthorization by placing a hold on the user's account without deducting funds. This is the first step in a two-step transaction process.

```APIDOC
## POST /asm

### Description
Authorizes the specified amount on the user's account without executing the actual deduction.

### Method
POST

### Endpoint
/asm

### Parameters
#### Request Body
- **schemaVersion** (String) - Constant - API schema version (e.g., "1.0")
- **requestId** (String) - Required - Unique request identifier (e.g., UUID)
- **timestamp** (String) - Required - Date and time of the request
- **channelName** (String) - Constant - Channel of the request (e.g., "WEB")
- **serviceName** (String) - Constant - The name of the service being called (e.g., `API_PREAUTHORIZE`)
- **serviceParams** (Object) - Required
  - **merchantUid** (String) - Required - Unique merchant identifier provided by WaafiPay upon merchant account setup
  - **apiUserId** (String) - Required - Unique identifier provided by WaafiPay store account setup
  - **apiKey** (String) - Required - Unique alphanumeric string assigned by WaafiPay store account setup
  - **paymentMethod** (String) - Required - Payment method being used (e.g., MWALLET_ACCOUNT)
  - **payerInfo** (Object) - Required
    - **accountNo** (String) - Required - Payer's mobile number in full international format, starting with the country code (e.g., `252611111111`). Do not include `+` or leading zeros.
  - **transactionInfo** (Object) - Required
    - **referenceId** (String) - 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.
    - **amount** (Number) - Required - Transaction Amount to be charged for the customer (numeric) in two decimal places
    - **currency** (String) - Required - ISO 4217 currency code for the transaction (e.g. USD, SLSH, DJF)
    - **description** (String) - Optional - A short description of the order or item being purchased by the customer, e.g. "Payment for order #22043" or "Subscription to premium plan".

### Request Example
```json
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PREAUTHORIZE",
  "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "apiUserId": {{API_USER_ID}},
    "apiKey": "{{API_KEY}}",
    "paymentMethod": "MWALLET_ACCOUNT",
    "payerInfo": {
      "accountNo": "25261111111"
    },
    "transactionInfo": {
      "referenceId": "22043",
      "amount": "1",
      "currency": "USD",
      "description": "Payment for order #22043"
    }
  }
}
```

### Response
#### Success Response (200)
- **schemaVersion** (String) - API schema version
- **timestamp** (String) - Date and time of the response
- **responseId** (String) - Unique identifier for the response
- **responseCode** (String) - Response code indicating success or failure
- **errorCode** (String) - Error code, if any
- **responseMsg** (String) - Message describing the response
- **params** (Object)
  - **state** (String) - The state of the transaction (e.g., "APPROVED")
  - **referenceId** (String) - The reference ID of the transaction
  - **transactionId** (String) - The unique ID of the transaction
  - **txAmount** (String) - The amount of the transaction

#### Response Example
```json
{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:52:06.287",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "state": "APPROVED",
    "referenceId": "1234",
    "transactionId": "1268664",
    "txAmount": "1.0"
  }
}
```
```

--------------------------------

### Refund Purchase Request Structure

Source: https://docs.waafipay.com/hpp-api

Use this structure to initiate a refund for a completed transaction. Ensure all required parameters like merchantUid, storeId, hppKey, and amount are provided. The referenceId or transactionId can be used to identify the transaction to be refunded.

```json
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"
  }
}
```

--------------------------------

### POST /asm (Register Webhook)

Source: https://docs.waafipay.com/webhooks

Registers a webhook URL to receive transaction notifications. Supports default URLs for all events or specific URLs for refund events.

```APIDOC
## POST /asm

### Description
Registers a public URL to receive real-time transaction notifications from WaafiPay. You can register a default URL for all events or a specific URL for refund events by providing the eventType parameter.

### Method
POST

### Endpoint
/asm

### Request Body
- **schemaVersion** (String) - Constant - API schema version (e.g., "1.0").
- **requestId** (UUID String) - Required - Unique request identifier.
- **timestamp** (String) - Required - Date and time of the request.
- **channelName** (String) - Constant - The channel through which the request was made.
- **serviceName** (String) - Constant - The name of the service (WEBHOOK_REGISTER).
- **merchantUid** (String) - Required - Unique identifier provided by WaafiPay.
- **storeId** (String) - Required - API store/user identifier.
- **hppKey** (String) - Required - API key for request authentication.
- **url** (String) - Required - Publicly accessible URL endpoint for webhooks.
- **eventType** (String) - Optional - Specifies event type (e.g., "refund"). If omitted, defaults to all events.
- **partnerUid** (String) - Optional - WAAFI Merchant Number.
- **description** (String) - Optional - Description of webhook usage.

### Request Example
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_REGISTER",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": "{{STORE_ID}}",
        "hppKey": "{{HPP_KEY}}",
        "url": "https://api.example.com/webhook",
        "eventType": "refund",
        "description": "a description"
    }
}

### Response
#### Success Response (200)
- **responseCode** (String) - Status code (e.g., "2001").
- **responseMsg** (String) - Success message.
- **secret** (String) - Secret key used to verify webhook authenticity.

#### Response Example
{
    "schemaVersion": "1.0",
    "timestamp": "2024-02-08 04:38:42.938",
    "responseId": "{{$guid}}",
    "responseCode": "2001",
    "errorCode": "0",
    "responseMsg": "Webhook created successfully",
    "params": {
        "secret": "your_secret"
    }
}
```

--------------------------------

### POST /asm - Refund Purchase

Source: https://docs.waafipay.com/hpp-api

Processes a refund for a previously completed transaction. Refunds can be partial, meaning you can refund less than the original transaction amount. You can initiate a refund using either the `transactionId` or `referenceId` from the original purchase.

```APIDOC
## POST /asm - Refund Purchase

### Description
Processes a refund for a previously completed transaction by either using the `transactionId` or `referenceId` from the original purchase. Partial refunds are allowed.

### Method
POST

### Endpoint
/asm

### Parameters
#### Request Body
- **schemaVersion** (String) - Constant - API schema version (e.g., "1.0")
- **requestId** (String) - Required - Unique request identifier (e.g., UUID)
- **timestamp** (String) - Required - Date and time of the request
- **channelName** (String) - Constant - The channel through which the request was made
- **serviceName** (String) - Constant - The name of the service being called (e.g., HPP_REFUNDPURCHASE)
- **serviceParams** (Object) - Required
  - **merchantUid** (String) - Required - Unique identifier provided by WaafiPay upon merchant account setup
  - **storeId** (String) - Required - Unique identifier provided by WaafiPay upon merchant account setup
  - **hppKey** (String) - Required - Unique alphanumeric string assigned by WaafiPay upon merchant account activation
  - **amount** (Number) - Required - Refund amount (numeric)
  - **transactionId** (Number) - Required - Transaction ID being refunded
  - **referenceId** (String) - Optional - Merchant Reference ID from the original transaction (e.g., "OrderId_422334")
  - **description** (String) - Optional - Description of the refund request (e.g., "Hpp refund")

### Request Example
```json
{
  "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"
  }
}
```

### Response
#### Success Response (200)
- **schemaVersion** (String) - API schema version (e.g., "1.0")
- **timestamp** (String) - Date and time of the response
- **responseId** (String) - Unique response identifier
- **responseCode** (String) - Response code indicating the result of the request
- **errorCode** (String) - Error code (e.g., "E10207" for an error)
- **responseMsg** (String) - Human-readable message for the response
- **params** (Object) - Empty object, as there is no further data in this response
  - **description** (String) - Description of the refund status
  - **state** (String) - Status of the refund (e.g., "approved", "declined", "failed")
  - **transactionId** (String) - Transaction ID of the refunded transaction
  - **referenceId** (String) - Reference ID of the refunded transaction

#### Response Example
```json
{
    "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"
    }
}
```

#### Error Response Example
```json
{
    "schemaVersion": "1.0",
    "timestamp": "2024-11-05 09:24:48.347",
    "responseId": "12314",
    "responseCode": "5202",
    "errorCode": "E10207",
    "responseMsg": "RCS_TRAN_ALREADY_CANCELLED"
}
```

* * *

### Note
Check the **state** parameter in the response to ensure the refund was successful. If `state` is "**approved**", the refund was successful; if it is "**declined**" or "**failed**", the refund failed.
```

--------------------------------

### Receiving a Webhook on Your Server

Source: https://docs.waafipay.com/webhooks

Details on the structure of webhook payloads for transaction notifications.

```APIDOC
## Receiving a Webhook on Your Server

### Description
Once registered, your webhook URL will receive transaction notifications. The payload structure indicates the transaction type and outcome.

### Payload Structure
- The `event` field indicates the **transaction type** (e.g., `authorization`, `refund`).
- The `payment.status` field indicates the **transaction outcome** (e.g., `APPROVED`, `FAILED`).

Note: The payload structure may differ between event types, and some fields might be optional.

### Authorization Transaction Example
```json
{
  "event": "authorization",
  "customer_identity": "252612345678",
  "cardholder_name": "John Doe",
  "merchant_id": 10165,
  "merchant_uid": "M400394",
  "user_id": "400394",
  "payment": {
    "transaction_id": "1303630",
    "order_id": "ORD-2024-001",
    "transfer_code": "ISR0011303630",
    "amount": 100.50,
    "currency": "USD",
    "payment_method": "MWALLET_ACCOUNT",
    "status": "APPROVED",
    "reference_id": "REF-2024-4567",
    "channel": "WEB",
    "description": "Payment for order ORD-2024-001",
    "date": "2025-08-13 15:04:05"
  }
}
```
```

--------------------------------

### PreAuthorization Request and Response

Source: https://docs.waafipay.com/preauthorization-api

Initiate a hold on a user's account using the API_PREAUTHORIZE service name.

```JSON
POST /asm
{
  "schemaVersion": "1.0",
  "requestId": "{{$guid}}",
  "timestamp": "{{$timestamp}}",
  "channelName": "WEB",
  "serviceName": "API_PREAUTHORIZE",
  "serviceParams": {
    "merchantUid": "{{MERCHANT_UID}}",
    "apiUserId": {{API_USER_ID}},
    "apiKey": "{{API_KEY}}",
    "paymentMethod": "MWALLET_ACCOUNT",
    "payerInfo": {
      "accountNo": "25261111111"
    },
    "transactionInfo": {
      "referenceId": "22043",
      "amount": "1",
      "currency": "USD",
      "description": "Payment for order #22043"
    }
  }
}
```

```JSON
{
  "schemaVersion": "1.0",
  "timestamp": "2024-11-05 08:52:06.287",
  "responseId": "12314",
  "responseCode": "2001",
  "errorCode": "0",
  "responseMsg": "RCS_SUCCESS",
  "params": {
    "state": "APPROVED",
    "referenceId": "1234",
    "transactionId": "1268664",
    "txAmount": "1.0"
  }
}
```

--------------------------------

### POST /asm - Update Webhook

Source: https://docs.waafipay.com/webhooks

Update the URL and description of an existing webhook.

```APIDOC
## POST /asm - Update Webhook

### Description
You can update the `url` and `description` properties of an existing webhook.

### Method
POST

### Endpoint
/asm

### Request Body
```json
{
    "schemaVersion": "1.0",
    "requestId": "{{$guid}}",
    "timestamp": "{{$timestamp}}",
    "channelName": "WEB",
    "serviceName": "WEBHOOK_UPDATE",
    "serviceParams": {
        "merchantUid": "{{MERCHANT_UID}}",
        "storeId": {{STORE_ID}},
        "hppKey": "{{HPP_KEY}}",
        "url": "https://api.sample.so/webhook/v2",
        "webhookId": 10,
        "description": "another description"
    }
}
```

### Response
(Success response details not provided in the source text)
```
Tokens:
Raw