Overview

The ADB Payment Webhook endpoint allows you to submit transaction data for ADB (Aeon Bank, originally ACS Digital Berhad) payments, including zakat transactions. This endpoint accepts POST requests with transaction data in JSON format.

The webhook accepts a JSON object containing an array of transactions, with each transaction containing fields as documented in the JSON schema (adb.json).

Purpose

The purpose of this webhook is to post payment transaction data to different Zakat Agencies, notably:

  • LZS (Lembaga Zakat Selangor)
  • PPZ (Pusat Pungutan Zakat-MAIWP)

Payments for these agencies are identified using the agency field in each transaction:

  • ADBLZS - Payments to LZS via ADB
  • ADBPPZ - Payments to PPZ via ADB
  • ADB - Live test transaction entries to ensure data is posted correctly

Endpoint Details

Base URL: https://pay.tulus.my

Endpoint: /api/adb/webhook

Full URL: https://pay.tulus.my/api/adb/webhook

Method: POST

Content-Type: application/json

Authentication: API Password (provided via X-API-Password header)

Authentication

The endpoint requires authentication using an API password. Include the password in the request header:

X-API-Password: YOUR_API_PASSWORD_HERE

Request Body Schema

The request body must contain a JSON object with the following structure:

Root Object

Field Type Required Description
$schema string No JSON Schema reference
transactions array Yes Array of transaction records

Transaction Object

Each transaction object in the transactions array must contain:

Field Type Required Description
agency string Yes Agency identifier. ADBLZS for payments to LZS (Lembaga Zakat Selangor) via ADB, ADBPPZ for payments to PPZ (Pusat Pungutan Zakat-MAIWP) via ADB, or ADB for live test transactions
orderno string Yes Unique order number for the transaction
amount number Yes Transaction amount in RM (must be >= 0)
name string Yes Customer name
email string Yes Customer email address (valid email format)
time string Yes Transaction timestamp in ISO 8601 format
status string Yes Transaction status: success, pending, or failed
data object Yes Additional transaction data (see below)

Data Object

The data object contains additional transaction details and supports the following optional fields:

Field Type Description
email string Email from data object (valid email format)
zakat_name string Name for zakat payment
zakat_ic_no string MyKad number for Malaysian citizen (12 digits)
zakat_state string Malaysian state for zakat payment (see allowed values below)
zakat_type string Type of zakat payment (see allowed values below)
zakat_year string Year for zakat payment (4 digits, e.g., "2025")
zakat_phone string Phone number for zakat payment (10-12 digits)
zakat_address string Address for zakat payment
zakat_postcode string Postcode for zakat payment (5 digits)
zakat_city string City for zakat payment
zakat_amount string Zakat amount as string (numeric with optional 2 decimal places)
zakat_rate string Rice price per kg for Zakat Fitrah (e.g., "7", "10"). Applicable for zakat_fitrah type only. The transaction amount should equal zakat_rate × zakat_dependant.
zakat_dependant string Number of dependants (tanggungan) for Zakat Fitrah payment (e.g., "1", "4"). Applicable for zakat_fitrah type only. The transaction amount should equal zakat_rate × zakat_dependant.

Allowed zakat_state Values

Allowed zakat_type Values

Example Request

Single Transaction

curl -X POST https://pay.tulus.my/api/adb/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Password: YOUR_API_PASSWORD_HERE" \
  -d '{
    "transactions": [
      {
        "agency": "ADB",
        "orderno": "122",
        "amount": 10,
        "name": "Ang Chee Hong",
        "email": "[email protected]",
        "time": "2025-01-01T10:10:10+08:00",
        "status": "success",
        "data": {
          "zakat_state": "johor",
          "zakat_type": "fitrah",
          "zakat_ic_no": "900101011234",
          "zakat_year": "2024",
          "zakat_phone": "01125293005",
          "zakat_address": "No 1, Jalan Bukit, 81100 Johor Bahru, Johor",
          "zakat_postcode": "81100",
          "zakat_city": "Johor Bahru",
          "zakat_amount": "10"
        }
      }
    ]
  }'

Multiple Transactions

curl -X POST https://pay.tulus.my/api/adb/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Password: YOUR_API_PASSWORD_HERE" \
  -d '{
    "transactions": [
      {
        "agency": "ADB",
        "orderno": "124",
        "amount": 20,
        "name": "Ahmad Bin Ali",
        "email": "[email protected]",
        "time": "2025-01-01T11:10:11+08:00",
        "status": "success",
        "data": {
          "email": "[email protected]",
          "zakat_name": "Ahmad Bin Ali",
          "zakat_type": "zakat_pendapatan",
          "zakat_state": "selangor",
          "zakat_year": "2025",
          "zakat_phone": "0123456789",
          "zakat_address": "No 25, Jalan Mawar, Taman Seri Indah, 40000 Shah Alam, Selangor",
          "zakat_postcode": "40000",
          "zakat_city": "Shah Alam",
          "zakat_amount": "20"
        }
      },
      {
        "agency": "ADB",
        "orderno": "125",
        "amount": 7,
        "name": "Siti Nurhaliza",
        "email": "[email protected]",
        "time": "2025-01-02T09:15:30+08:00",
        "status": "success",
        "data": {
          "email": "[email protected]",
          "zakat_name": "Siti Nurhaliza",
          "zakat_type": "zakat_fitrah",
          "zakat_state": "kuala_lumpur",
          "zakat_year": "2025",
          "zakat_phone": "0198765432",
          "zakat_address": "Blok A-12-5, Pangsapuri Seri Wilayah, 50480 Kuala Lumpur",
          "zakat_postcode": "50480",
          "zakat_city": "Kuala Lumpur",
          "zakat_amount": "7",
          "zakat_rate": "7",
          "zakat_dependant": "1"
        }
      }
    ]
  }'

Pending Transaction Example

curl -X POST https://pay.tulus.my/api/adb/webhook \
  -H "Content-Type: application/json" \
  -H "X-API-Password: YOUR_API_PASSWORD_HERE" \
  -d '{
    "transactions": [
      {
        "agency": "ADB",
        "orderno": "126",
        "amount": 12,
        "name": "Muhammad Hafiz",
        "email": "[email protected]",
        "time": "2025-01-02T14:22:45+08:00",
        "status": "pending",
        "data": {
          "email": "[email protected]",
          "zakat_name": "Muhammad Hafiz",
          "zakat_type": "zakat_emas",
          "zakat_state": "pulau_pinang",
          "zakat_year": "2025",
          "zakat_phone": "0135678901",
          "zakat_address": "No 88, Jalan Gurney, Georgetown, 10250 Pulau Pinang",
          "zakat_postcode": "10250",
          "zakat_city": "Pulau Pinang",
          "zakat_amount": "12"
        }
      }
    ]
  }'

Response Format

The API will return appropriate HTTP status codes:

Important Notes

  1. Agency Code:
    • ADBLZS - Use for payments to LZS (Lembaga Zakat Selangor) via ADB
    • ADBPPZ - Use for payments to PPZ (Pusat Pungutan Zakat-MAIWP) via ADB
    • ADB - Use for live test transactions to ensure data is posted correctly
  2. Order Number: The orderno field must be unique for each transaction to prevent duplicates.
  3. Date Format: The time field must be in ISO 8601 format with timezone information (e.g., 2025-01-01T10:10:10+08:00).
  4. Email Validation: Email addresses must be valid and properly formatted.
  5. Phone Number Format: Phone numbers should be 10-12 digits without spaces or special characters.
  6. Postcode Format: Malaysian postcodes must be exactly 5 digits.
  7. Amount Format:
    • The amount field accepts numeric values
    • The zakat_amount field in the data object is a string that must match the pattern for numeric values with up to 2 decimal places

Testing

For testing purposes, you can use the ADB agency code for live test transactions to ensure your data is being posted correctly. Replace YOUR_API_PASSWORD_HERE with the actual API password provided to you.

Support

For technical support or API password requests, please contact the Tulus development team at [email protected]

Schema Reference

The complete JSON schema for the webhook data is available at:
https://developers.tulus.my/schema/adb.json