Skip to main content

​
Multi-bill fee - 23 September 2026

Pricing change for billIds. A multi-bill order’s fee is now the sum of the fee quoted on each selected bill in bills[] — the same as paying those bills one by one. It replaces the single fee on the combined total announced below. billIds with more than one id is accepted for SEAAL only.

​
Multi-bill payment - September 2026

New optional parameter, no breaking changes. billId still works exactly as it does today. billIds is an alternative to it, never a replacement.
POST /v3/bills/pay now accepts billIds — up to 50 factures from the same READY transaction, settled as one order at the biller, one card payment and one service fee on the combined total.

​
🟢 What’s New

billId or billIds — exactly one of the two

  • billId — one facture, a string of at most 100 characters. Unchanged.
  • billIds — 1 to 50 ids, each at most 100 characters, with no id repeated.
Sending both, or neither, answers 400 ERR_VALIDATION — “Provide exactly one of billId or billIds”. A repeated id answers “billIds must not repeat the same bill id”.

One fee, on the combined total

The fee is computed once, on the sum of the factures you selected — never as the sum of the per-bill fees quoted in bills[]. Under SEAAL’s 0.5% rule with its 30 DZD minimum and 60 DZD maximum, three quarters of 327.00, 480.00 and 767.81 DZD total 1574.81 DZD: 0.5% of that is 7.87, below the floor, so the order carries a single fee of 30.00 DZD and a total of 1604.81 DZD. Paid one at a time those same three would carry the floor three times — 90.00 DZD. A five-facture water order costs 30.00 DZD in fees instead of 150.00 DZD.The transaction reports the order as one aggregate selected bill: amount is the sum of the factures chosen, fee the single fee on that sum. Sandbox does the same arithmetic as production, so the figures you validate there are the figures production will charge.

A list is never partly settled

Every id you send must still be on that READY transaction; one stale or unknown id refuses the whole call and nothing is paid. The already-paid and payment-in-flight guards then run for every id in the list, and they recognise a facture that was settled earlier as one line of a larger order — so a quarter paid inside a group still answers 409 BILL_ALREADY_PAID on its own.

Where it helps: SEAAL

Grouping only means something where the biller’s own portal settles several documents in one transaction. Today that is SEAAL, where water is billed quarterly and an account routinely owes many unpaid quarters at once — 25 on one verified production account. Every other biller returns a single bill anyway, so billIds with one entry is simply equivalent to billId.SEAAL’s 200 DA order minimum applies to the selected total, not to each line, so grouping only makes it easier to clear.

Paying Bills

The worked example

Pay a Bill

The endpoint reference

​
SEAAL bill payment - September 2026

New biller, no breaking changes. SEAAL is live on the /v3/bills endpoints you already call. Nothing you send today changes.
SEAAL — the water utility for Algiers and Tipaza — is integrated and settling real payments. It reports ACTIVE in the availability map alongside ADE, SONELGAZ, AADL and Algérie Télécom. Earlier releases described SEAAL as unreachable and permanently UNAVAILABLE: that is no longer true, so read the availability map instead of hiding the partner unconditionally.

​
🟢 What’s New

A nested account identifier

SEAAL is the first partner addressed by a pair rather than a single key, because the biller authenticates on both halves together:
  • code_client — 2 to 6 alphanumeric characters
  • code_contrat — 2 to 10 digits
Both are printed on the customer’s paper water bill and both are mandatory; there is no flat shorthand. The transaction reads the identifier back flat, as account.codeClient.

Several quarters, one order, one fee

Water is billed quarterly and an account can carry many unpaid factures at once — one account verified at go-live owed 45 quarters. Selecting several of them produces one order and one card payment, and the fee is charged once on the total, never summed per bill. The SEAAL fee rule is 0.5% of the amount, clamped to a 30 DZD minimum and a 60 DZD maximum — the same rule the other billers use, and on a water facture it always lands on the 30 DZD floor.
Multi-bill selection shipped in the OneClickDz consumer checkout first. It is on this API too: POST /v3/bills/pay accepts a billIds array of up to 50 factures — see the entry above.

Five sandbox scenarios

Each scenario is keyed off code_client; code_contrat still has to be present and well-formed.

Biller rules worth handling

  • A 200 DA minimum. SEAAL refuses any order whose selected total is below 200 DA.
  • Temporary account lockout. After repeated failed attempts the biller blocks that account for a few hours and says how long. It is account-specific — not an outage and not a bad identifier — and the only remedy is to wait.
  • Nothing due is a result, not a fault. A fully settled account answers “Vous êtes à jour, merci pour votre fidélité.” and surfaces as BILL_ALREADY_PAID. Reconciliation works by absence: a paid facture simply stops being listed.

Partners and accounts

The identifier rules

Bill Payment Overview

The whole flow

​
Bill Payment API - August 2026

New product, no breaking changes. Bill Payment is a new section of the v3 API, on the base URL and the key you already use. Nothing else in the Flexy API changed.
Pay Algerian utility and telecom bills on behalf of your customers — ADE, SONELGAZ, SEAAL, AADL and Algérie Télécom.

​
🟢 What’s New

The base URL you already use

Same host, same X-Access-Token header, same key — no new base URL and no new authentication mechanism. Your sandbox key selects the sandbox environment, exactly as it does everywhere else in v3.

Discover, pay, poll, download

  • POST /v3/bills/discover — ask a biller what an account owes
  • POST /v3/bills/pay — pay one of the discovered bills
  • GET /v3/bills/transactions/{transactionId} — follow it to a final state
  • GET /v3/bills/transactions/{transactionId}/receipt — download the proof of payment
Both write endpoints are asynchronous: a 200 is an acknowledgement, and the outcome appears in the transaction’s status.

A deterministic sandbox

Each key is bound to one environment. In sandbox, the account identifier you send chooses the outcome, so a decline, a refund and an unconfirmed payment can all be reproduced on demand.

Bill Payment Overview

Start here

API Reference

All seven endpoints

​
v3.0.0 - October 2025

Breaking Changes: v3 is a complete redesign. See Migration Guide for upgrade instructions.

​
🔴 What You Must Change

1. Base URL Changed

2. Authentication Header Changed

3. Response Structure Changed

All responses now wrapped in standardized format:Before (v2):
After (v3):
Access data via response.data instead of directly from response.

4. Endpoint Paths Changed

5. Error Handling Changed

Before (v2):
After (v3):
Always check response.success boolean first.

​
✨ What’s New

  • Gift Cards API: Complete gift card delivery system with 100+ products
  • Sandbox Keys: Separate API keys for testing without affecting production balance
  • IP Whitelisting: Enhanced security through dashboard settings
  • Request Tracking: Every request includes unique requestId for debugging
  • Better Errors: Structured error codes with actionable messages
  • Schema Validation: Automatic validation prevents invalid requests

​
📅 Migration Deadline

v2 will be deprecated on October 30, 2026. Migrate before this date to avoid service disruption.

​
🔗 Resources

​
v2.x - Pre-October 2025

​
August 2025

  • Added sandbox mode for testing
  • Improved error handling and logging

​
July 2023

  • Initial sandbox implementation
  • Added support for ADSL internet recharge

​
Earlier

  • Mobile top-ups for Mobilis, Djezzy, Ooredoo
  • Basic transaction tracking
  • Account balance management

​
Need Help?

Contact Support

Questions about migration? We’re here to help.