Refunds and failed delivery#

This page covers internal-wallet refunds and payments that settled without delivery.

It does not cover USDC service purchases or partial refunds.

Full wallet refunds#

You can request one full refund for an eligible PayMongo wallet top-up.

The top-up must meet all these conditions:

• The top-up status is PAID.
• The top-up has a PayMongo payment reference.
• The original PHP amount and the credited USD amount exist.
• The refund window has not ended. An administrator sets that window in days and hours, and it starts when the top-up was paid.
• Your internal wallet balance covers the complete credited USD amount.
• The top-up has no unresolved dispute or earlier refund request.

CitizenAI checks the balance you hold now, not the money that arrived with that top-up. Every top-up pays into one balance, so a later top-up can make an earlier refund possible again. This check exists to keep the internal wallet at or above zero.

CitizenAI uses the original PHP amount for the provider refund. It does not recalculate that amount from a later exchange rate.

The refund does not accept a custom amount. It always requests the complete credited USD amount.

Your reason for the refund#

You must explain why you want the refund. The reason needs at least 10 characters and accepts at most 500. Spaces alone do not count.

The administrator who reviews the request reads your reason, so write what went wrong.

Before you submit the request, CitizenAI shows this warning:

Your CitizenAI wallet becomes unavailable while we process this refund.

While the refund is under review, submitted, or awaiting reconciliation:

• You cannot spend from the internal wallet, and you cannot add money to it.
• You can still see the balance and the payment history.
• The crypto wallet keeps working, including crypto-funded purchases.

The restriction applies only to the internal USD wallet. The crypto wallet remains usable, and crypto-funded purchases remain available.

An administrator reviews and submits every provider refund. You cannot submit a PayMongo refund directly.

Refund states#

State	Meaning
REQUESTED	You submitted an eligible full refund request.
REJECTED	An administrator rejected the request and released the wallet hold.
APPROVED	An administrator approved provider submission.
SUBMITTED	PayMongo accepted the refund request.
RECONCILIATION_REQUIRED	The provider result needs a verified check or manual review.
SUCCEEDED	PayMongo confirmed the full refund.
FAILED	PayMongo gave a final failure and CitizenAI released the wallet hold.

An unknown provider result keeps the internal wallet restriction active. CitizenAI does not create a second refund attempt with a new idempotency key.

QR Ph refunds#

Some QR Ph refunds require provider support instead of automatic submission. CitizenAI places that refund in RECONCILIATION_REQUIRED and shows Contact support in the administrator review.

The administrator must contact PayMongo support and record the provider result before closing the refund. A QR Ph return page does not prove that the refund succeeded.

Why it is handled separately#

Because paying and receiving are separate stages. A confirmed payment is a milestone; the purchase completes only when the capability is delivered. A gap between those two is a real state the system recognises rather than a silent loss.

What triggers it#

• Settlement succeeded, provisioning did not.
• A vendor accepted a charge and then could not deliver.
• A settlement result was indeterminate and reconciliation showed the charge stood without a delivery.

What happens#

Refund handling is the safeguard for delivery failure after a successful availability check. A settled purchase that is not provisioned requires refund handling — it is not left as an open purchase indefinitely.

For a wallet refund, CitizenAI creates an internal hold before provider work starts. A successful refund keeps that hold because the credited wallet funds must remain removed. A rejection or final failure releases the hold with a new ledger entry.

Duplicate protection#

While a purchase for the same agent and capability is unresolved, another attempt is blocked. An indeterminate settlement keeps that block until reconciliation. This is deliberate: retrying into an ambiguous charge is how people get billed twice.

Disputes#

PayMongo can open a dispute for a wallet top-up. CitizenAI records the dispute after it verifies the signed webhook body and confirms the PayMongo mode.

A matched dispute creates an active internal-wallet restriction without changing the balance. The credited balance remains visible while PayMongo reviews the charge.

State	Meaning
UNDER_REVIEW	PayMongo opened the dispute and the internal wallet remains restricted.
WON	PayMongo rejected the chargeback; the credited balance remains.
LOST	PayMongo accepted the chargeback and the wallet covered the full exposure.
RECOVERY_REQUIRED	PayMongo accepted the chargeback, but the wallet lacked enough funds.
REVIEW_REQUIRED	The event needs a match or a cross-flow review.
CLOSED	An administrator closed a recovery or review case.

A lost dispute never creates a negative internal-wallet balance. If the balance cannot cover the full credited amount, CitizenAI creates a recovery case and keeps the restriction active.

An administrator must record a note and a provider reference when resolving a dispute. The administrator must record a note and a closure reason when closing a recovery case.

The crypto wallet does not freeze during a refund or dispute. Direct crypto transfers, crypto balance reads, and crypto-funded service purchases remain separate.

What is not a refund case#

Situation	Why not
Provider unavailable. at checkout	No money moved, so there is nothing to refund
A failed live signup where nothing was purchased	Nothing was charged
A capability you no longer want	Delivered is delivered — a refund covers failed delivery, not a change of mind

What to have ready#

The purchase and the agent it was for, from Payment history. Those two facts identify it.