Dynamic Field Requirements

info

Dynamic fields define the input requirements and expected output for VAS product purchases. These fields are derived from the meta property of product categories.

What Are Dynamic Fields?

Dynamic fields allow the Pagamio VAS platform to support multiple products with different input requirements without hardcoding them. Each category specifies:

1. fields – the inputs required to complete a purchase.

   • Each field has:
     • name – the field identifier (e.g., amount, mobileNumber)
     • type – the data type (string, number, etc.)
     • required – whether the field must be provided for the purchase

2. receiptFields – the fields returned in the purchase receipt.

   • These may include transaction details, voucher info, or product-specific metadata.

---

Category Meta Examples

Below are the required payload meta for each major category:

Voucher Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "voucher.pin",
    "voucher.serialNumber",
    "voucher.amount",
    "voucher.expiryDate",
    "voucher.content.redemptionInstructions",
    "voucher.content.termsAndConditions",
    "details[0].productInstructions",
    "details[0].tokens[0].token",
    "details[0].tokens[0].serialNumber",
    "details[0].productAmount"
  ]
}

SMS Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "mobileNumber", "type": "string", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "rechargeDetails.rechargeType",
    "rechargeDetails.callCentre",
    "rechargeDetails.rechargeVendor",
    "amount",
    "reference"
  ]
}

Airtime Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "mobileNumber", "type": "string", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "rechargeDetails.rechargeType",
    "rechargeDetails.callCentre",
    "rechargeDetails.rechargeVendor",
    "amount"
  ]
}

Data Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "mobileNumber", "type": "string", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "rechargeDetails.rechargeType",
    "rechargeDetails.callCentre",
    "rechargeDetails.rechargeVendor",
    "amount"
  ]
}

Gaming Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "voucher.pin",
    "voucher.serialNumber",
    "voucher.amount",
    "voucher.expiryDate",
    "voucher.content.redemptionInstructions",
    "voucher.content.termsAndConditions",
    "details[0].productInstructions",
    "details[0].tokens[0].token",
    "details[0].tokens[0].serialNumber",
    "details[0].productAmount"
  ]
}

Entertainment Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "voucher.pin",
    "voucher.serialNumber",
    "voucher.amount",
    "voucher.expiryDate",
    "voucher.content.redemptionInstructions",
    "voucher.content.termsAndConditions",
    "details[0].productInstructions",
    "details[0].tokens[0].token",
    "details[0].tokens[0].serialNumber",
    "details[0].productAmount"
  ]
}

Electricity Category

{
  "fields": [
    { "name": "meterNumber", "type": "string", "required": true },
    { "name": "amount", "type": "number", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "billingInfo.unitType",
    "billingInfo.units",
    "billingInfo.transactionNumber",
    "billingInfo.receiptNumber",
    "billingInfo.taxAmount",
    "billingInfo.exclusiveAmount",
    "meterInfo.customerInfo.name",
    "meterInfo.customerInfo.address",
    "meterInfo.meterNumber",
    "meterInfo.utilityInfo.name",
    "tokens[0].token",
    "tokens[0].tokenDescription",
    "tokens[1].token",
    "tokens[1].tokenDescription",
    "amount"
  ]
}

Minutes Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "mobileNumber", "type": "string", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "rechargeDetails.rechargeType",
    "rechargeDetails.callCentre",
    "rechargeDetails.rechargeVendor",
    "amount"
  ]
}

Lifestyle Category

{
  "fields": [
    { "name": "amount", "type": "number", "required": true },
    { "name": "paymentMethod", "type": "string", "required": true }
  ],
  "receiptFields": [
    "voucher.pin",
    "voucher.serialNumber",
    "voucher.amount",
    "voucher.expiryDate",
    "voucher.content.redemptionInstructions",
    "voucher.content.termsAndConditions",
    "details[0].productInstructions",
    "details[0].tokens[0].token",
    "details[0].tokens[0].serialNumber",
    "details[0].productAmount"
  ]
}

---

How to Use Dynamic Fields

• Input Validation: Use the type and required attributes to validate purchase requests dynamically.
• Form Generation: Build forms on the frontend automatically using the fields array.
• Receipt Parsing: After a successful purchase, only the fields listed in receiptFields are returned in the API response.

Note: Dynamic fields allow the system to handle any product category, ensuring flexibility and scalability without code changes for each new product.

---

Last updated: October 2025