Credits Facilitator

The Credits Facilitator handles verification and settlement for Credits scheme payments. It manages atomic balance debits with an immutable ledger.

Base URL

https://walletapi.fluxapay-qa.xyz/api/facilitator

Endpoints

Method	Path	Description
POST	/api/facilitator/verify	Validate a credits payment proof
POST	/api/facilitator/settle	Execute credits settlement

Verify

Validates a credits payment proof without executing settlement.

Request

{
  "paymentPayload": "<base64-encoded X-Payment JSON>"
}

Or the alternative direct format:

{
  "payment": {
    "payerWallet": "0x...",
    "amountCredits": "100",
    "nonce": "0x...",
    "validAfter": "1700000000",
    "validBefore": "1700001200",
    "creditsMandateId": "mnd_..."
  },
  "signature": "0x..."
}

Validation Checks

1. Network is fluxa-monetize-credits
2. EIP-712 signature is valid and recovers to payerWallet
3. Nonce is within the 20-minute validity window and not reused
4. Amount matches the associated payment_records entry
5. Payer wallet matches the user's registered wallet
6. Mandate exists, is active, and has sufficient remaining budget (if applicable)
7. Approval exists and is in a valid status (if applicable)

Response (success)

{
  "isValid": true,
  "payer": "0x...",
  "network": "fluxa-monetize-credits",
  "currency": "FLUXA_MONETIZE_CREDITS",
  "amountCreditsMinor": "100",
  "amountCredits": "1.00",
  "nonce": "0x..."
}

Response (failure)

{
  "isValid": false,
  "invalidReason": "insufficient_credits_balance"
}

Settle

Executes atomic credits settlement — debits the payer's balance and writes an immutable ledger entry.

Request

Same format as Verify.

Response (success)

{
  "success": true,
  "txHash": "credits_a1b2c3...",
  "transaction": "credits_a1b2c3...",
  "network": "fluxa-monetize-credits",
  "paymentRequestId": "x402c:fluxa-monetize-credits:<nonce>",
  "receiptId": "...",
  "receiptToken": "...",
  "ledgerEntryId": 123,
  "balanceAfterMinor": "900",
  "alreadySettled": false
}

Idempotency

If settle is called for a payment that has already been settled (record status is used), the facilitator returns the original receipt with alreadySettled: true instead of rejecting the request. This ensures safe retries.

Error Scenarios

Error	Description
insufficient_credits_balance	Available balance is less than the payment amount
invalid_signature	EIP-712 signature recovery does not match payerWallet
invalid_nonce	Nonce is outside the 20-minute validity window or reused
invalid_validity_window	validAfter / validBefore values are invalid
payment_record_not_found	No matching payment_records entry for the nonce
amount_mismatch_with_payment_record	Amount does not match the payment record
mandate_not_found	Referenced mandate does not exist
invalid_mandate_status	Mandate is not in an active/signed status
approval_not_found	Referenced approval does not exist
invalid_approval_status	Approval is not in a valid status for settlement
already_settled	Payment already settled (idempotent return)
credits_account_not_found	No credits account found for the user