Phoenix API Changelog

This page documents all API surface changes in Phoenix - new endpoints, state machine changes, schema migrations, and breaking/non-breaking alterations. Entries are in reverse chronological order.

Release: 10 April 2026¶

New Endpoints¶

Method	Path	Service	Description	Auth Required	Breaking?
POST	`/api/v1/payin/payments/charge`	pay-in	Direct (no-OTP) recurring charge using a stored paymentToken. Designed for subscription billing flows. Cross-merchant token isolation is enforced at the service layer.	Bearer JWT + merchant scope	No - additive

New Service: Reconciliation (port 8447)¶

The reconciliation microservice exposes the following internal API (called by the pay-out service; not exposed at the KrakenD gateway boundary):

Method	Path	Description	Idempotent?
POST	`/internal/reconciliation/calculate`	Calculates customer.fee, customer.tax, merchant.fee, merchant.commission for a given transaction. Returns a settlement breakdown object.	Yes - idempotency key required

Disbursement Response - New settlement Field¶

The pay-out disbursement response now includes an optional settlement object populated inline by the reconciliation service. The field is omitted gracefully if reconciliation is unavailable (non-blocking).

{
  "disbursement_id": "disb_01HZ...",
  "status": "disbursed",
  "amount": "1000.00",
  "currency": "PKR",
  "settlement": {
    "customer": {
      "fee": "15.00",
      "tax": "2.25"
    },
    "merchant": {
      "fee": "8.00",
      "commission": "1.20"
    }
  }
}

Pay-Out State Machine - Three New States¶

Three states have been added to the disbursement state machine to achieve parity with the legacy Java platform. These states affect the status field returned in all pay-out API responses and webhook payloads.

New State	Meaning	Valid Transitions	Merchant Action Required?
`in_review`	AML hold - transaction under compliance review	`processing` (cleared) or `reversed` (rejected)	No - await webhook update
`on_hold`	Balance or manual hold - awaiting resolution by ops or merchant	`processing` (resolved) or `reversed` (cancelled)	Possibly - check balance / contact support
`stuck`	Partner timeout - no callback received within SLA	`processing` (retried) or `reversed` (abandoned)	No - Simpaisa ops will action

Merchant integration note: Merchants consuming pay-out webhooks must ensure their status handlers treat unrecognised states gracefully. The three new states (in_review, on_hold, stuck) are non-terminal - funds are neither disbursed nor reversed until a subsequent state transition occurs.

Security Changes¶

Change	Affected Services	Impact	Breaking?
Wildcard CORS middleware removed	card, pay-in, pay-out, remittance	Services are internal-only behind KrakenD. No external CORS headers emitted. Browser-based direct calls to these services (which should not be made) will now fail.	No - if integrations are correct (server-to-server via gateway only)

Prior Releases¶

This changelog was established on 10 April 2026. All Phoenix API changes from this date onwards will be recorded here. For pre-changelog history, refer to the Git commit log in the phoenix monorepo.