🧾 Simulating Bill Payment with Dummy Products (OperatorId: 9992 & 9989)

This guide explains how to simulate bill payment flows using dummy products in the CSQ API. These products allow developers to test invoice queries, payment logic, and error handling — without contacting real providers or executing actual transactions.

📦 Dummy Products for Bill Payment

Product ID	Product Name	Behavior Summary
`9992`	DummyBills	Full flow: invoice query + payment simulation
`9989`	DummyBills2	Simplified flow: direct payment without invoice query

🔁 Simulation Flow

Product `9992` (Full Flow)

Get Parameters

Query Pending Invoices

Execute Payment

Product `9989` (Simplified Flow)

Get Parameters

Execute Payment (no invoice query)

🔹 Step 1: Get Parameters

Method
GET /bill-payment/parameters/{terminalId}/{operatorId}

Use operatorId = 9992 or 9989

Response Example

{
  "rc": 0,
  "message": "OK",
  "front": [
    {
      "name": "account",
      "label": "Contract or Account Number",
      "type": "INPUT",
      "list": [],
      "minLength": 6,
      "maxLength": 12
    }
  ],
  "query": [
    "account"
  ],
  "pay": [
    "account"
  ]
}

✅ The required field is account, which determines both the invoice type and the simulated payment result.

🔸 Step 2: Query Pending Invoices (Only for 9992)

Method
POST /bill-payment/invoices/{terminalId}/{operatorId}

Payload Example

[
  {
    "key": "account",
    "value": "123002"
  }
]

🧪 Siumlated Behavior Based on Last 3 Digits of `account`

Ends With	Payment Type	Customer Name	Transaction Code
`000`	OPEN	James May	ABC123XYZ2
`001`	DISCRETE	Jeremy Clark	ABC123XYZ
`002`	TOTAL	Richard Hammond	ABC123XYZ3
Other	No invoices	—	—

This step simulates invoice discovery and returns metadata in additionalData.

🧪 Example of Siumlated Behavior Based on Last 3 Digits of `account`

{
  "rc": 0,
  "message": "OK",
  "additionalData": [
    {
      "key": "customerName",
      "value": "Richard Hammond"
    },
    {
      "key": "transactionCode",
      "value": "ABC123XYZ3"
    }
  ],
  "pendingInvoices": 1,
  "amountToSendX100": 7000,
  "destinationAmountX100": 7000,
  "serviceFeeX100": 0,
  "totalAmountX100": 7000,
  "destinationCurrency": "EUR",
  "items": [
    {
      "amountToSendX100": 7000,
      "destinationAmountX100": 7000,
      "serviceFeeX100": 0,
      "totalAmountX100": 7000,
      "destinationCurrency": "EUR",
      "date": "2025-07-08",
      "expirationDate": "2025-08-08",
      "invoiceReference": "INV-XYZ-0003",
      "isElegible": true
    }
  ],
  "paymentType": "TOTAL"
}

📄 Explanation of `isElegible` and `paymentType` in Invoice Query Response

When simulating bill payments using dummy product 9992, the invoice query response provides two key fields that influence the logic of the payment flow: isElegible and paymentType. Here's what they mean and how to handle them in your integration:

🟢 `isElegible`

Location: Inside each element of the items[] array
Type: boolean

✅ If `isElegible: true`

The invoice is valid and can be paid.

Should be considered for payment submission in /bill-payment/payment.

The UI may allow the user to confirm or proceed with this invoice.

❌ If `isElegible: false`

The invoice is not payable.

Reasons may include expiration, invalid data, or provider restrictions (simulated).

It should be displayed as unavailable and excluded from final payment.

Example:
"isElegible": true
→ Invoice is selectable and may be paid.

🧾 `paymentType`

Location: Top-level field of the response
Type: string

Purpose

Defines the payment strategy required for the listed invoices. It determines how the frontend and backend should structure the payment flow.

Value	Meaning
`"OPEN"`	Amount is flexible. Payment can be partial or undefined.
`"DISCRETE"`	Specific invoices must be selected individually and paid separately.
`"TOTAL"`	The entire balance must be paid in a single transaction.

Example:
"paymentType": "TOTAL"
→ The frontend should prompt payment of the full amount listed in amountToSendX100. Invoice deselection or partial payment is not allowed.

💡 Integration Tip

Make sure your UI and validation logic interpret isElegible correctly:

Disable checkbox or payment action if false.

Display invoice metadata from additionalData for clarity.

Adapt behavior based on paymentType:

For OPEN, allow user to enter amount.

For DISCRETE, show individual invoices.

For TOTAL, display single pay button for full amount.

Let me know if you want full examples for each paymentType or how to simulate multiple invoices within items[] 🧾✨

🔸 Step 3: Execute Payment

Method
POST /bill-payment/payment/{terminalId}/{operatorId}/{localReference}

Payload Example

{
  "amountToSendX100": 7000,
  "localDateTime": "2025-07-08T10:00:00Z",
  "beneficiaryPhoneNumber": "+34600000000",
  "additionalData": [
    {
      "key": "account",
      "value": "123002"
    }
  ]
}

✅ Payload Tips

This payload is designed for a bill payment simulation using dummy product 9992, where the paymentType determined during the invoice query was "TOTAL".

🔍 Key Behaviors

💳 The full amount must be paid in a single transaction. No partial or selective payment is allowed.

✅ You should not include invoiceNumbers, since individual item selection is disabled.

🔒 The additionalData array contains the "account" as a key-value pair, which is required to identify the payment context:

[
  {
    "key": "account",
    "value": "123002"
  }
]

💶 amountToSendX100 = 7000 → this simulates a payment of €70.00

⏰ localDateTime marks the timestamp of the simulated payment request:

"localDateTime": "2025-07-08T10:00:00Z"

This configuration ensures your system handles TOTAL-type payments correctly — by enforcing full payment logic and suppressing invoice item selection. Let me know if you'd like example responses for approved or

🔍 Behavior Based on First Digit of `account`

Starts With	Simulated Result	Description
`1`	✅ Approved	Payment accepted
`2`	❌ DENIED_FROM_PROVIDER	Simulated rejection
`3`	⚠ TIMEOUT_OR_COMMUNICATION	Simulated network error
Other	❗ SYSTEM_ERROR	Generic failure

Example:
account = "234567" → starts with 2 → triggers DENIED_FROM_PROVIDER

🧪 Test Scenarios Summary

Product ID	Account Value	Invoice Type	Payment Result
`9992`	`123000`	OPEN	Approved (starts with `1`)
`9992`	`456001`	DISCRETE	Rejected (starts with `2`)
`9992`	`789002`	TOTAL	Timeout (starts with `3`)
`9989`	`345678`	—	Timeout (starts with `3`)

🧠 Developer Notes

Always use Get Parameters to detect required fields dynamically.

For 9992, invoice query is mandatory before payment.

For 9989, payment can be executed directly.

Use account suffix to simulate invoice type, and prefix to simulate payment result.

Log and handle resultcode, resultmessage, and finalstatus in responses.

Bill Payment Simulation

🧾 Simulating Bill Payment with Dummy Products (OperatorId: 9992 & 9989)#

📦 Dummy Products for Bill Payment#

🔁 Simulation Flow#

Product 9992 (Full Flow)#

Product 9989 (Simplified Flow)#

🔹 Step 1: Get Parameters#

🔸 Step 2: Query Pending Invoices (Only for 9992)#

🧪 Siumlated Behavior Based on Last 3 Digits of account#

🧪 Example of Siumlated Behavior Based on Last 3 Digits of account#

📄 Explanation of isElegible and paymentType in Invoice Query Response#

🟢 isElegible#

✅ If isElegible: true#

❌ If isElegible: false#

🧾 paymentType#

Purpose#

💡 Integration Tip#

🔸 Step 3: Execute Payment#

✅ Payload Tips#

🔍 Key Behaviors#

🔍 Behavior Based on First Digit of account#

🧪 Test Scenarios Summary#

🧠 Developer Notes#