XRP Facilitator

The XRP Facilitator handles verification and settlement for XRP scheme payments.

Base URL

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

Endpoints

Method	Path	Description
POST	/api/facilitator/verify	Validate a signed XRP payment
POST	/api/facilitator/settle	Submit and settle an XRP payment

Verify

POST /api/facilitator/verify

Request

Format A — base64 payload:

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

Format B — direct object:

{
  "payment": {
    "network": "xrpl-mainnet",
    "txHash": "ABC123...",
    "signedTransaction": "120000...",
    "account": "rSenderAddress",
    "destination": "rReceiverAddress",
    "amount": "1000000",
    "currency": "XRP"
  },
  "signature": "120000..."
}

Response (success)

{
  "isValid": true,
  "payer": "rSenderAddress",
  "network": "xrpl-mainnet",
  "currency": "XRP",
  "amount": "1000000",
  "amountDrops": "1000000",
  "nonce": "ABC123...",
  "txHash": "ABC123..."
}

Response (failure)

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

Settle

POST /api/facilitator/settle

Takes the same request format as verify.

The facilitator submits the signed transaction to XRPL via RPC (submit with tx_blob), records the onchain_tx_hash, and returns the engine result. Finality is confirmed asynchronously — the settle endpoint does not immediately mark the payment as used.

Response (success)

{
  "success": true,
  "txHash": "ABC123...",
  "transaction": "ABC123...",
  "network": "xrpl-mainnet",
  "paymentRequestId": "x402r:xrpl-mainnet:ABC123...",
  "alreadySettled": false,
  "alreadySubmitted": false,
  "engineResult": "tesSUCCESS",
  "engineMessage": "The transaction was applied."
}

Response (already settled)

{
  "success": true,
  "txHash": "ABC123...",
  "transaction": "ABC123...",
  "network": "xrpl-mainnet",
  "paymentRequestId": "x402r:xrpl-mainnet:ABC123...",
  "alreadySettled": true,
  "alreadySubmitted": false,
  "engineResult": null,
  "engineMessage": null
}

Error Scenarios

Error	HTTP	Description
feature_not_enabled	404	FEATURE_RIPPLE_WALLET is not enabled
invalid_signed_transaction	400	Failed to decode the transaction blob
invalid_transaction_type	400	Transaction is not a Payment type
tx_hash_mismatch	400	Computed hash doesn't match provided txHash
account_mismatch_with_signed_transaction	400	Hint account doesn't match decoded tx
destination_mismatch_with_signed_transaction	400	Hint destination doesn't match decoded tx
amount_mismatch_with_signed_transaction	400	Hint amount doesn't match decoded tx
currency_mismatch	400	Currency is not XRP
payment_record_not_found	404	No matching payment record for the txHash
amount_mismatch_with_payment_record	400	Amount doesn't match payment record
destination_mismatch_with_payment_record	400	Destination doesn't match pay_to
invalid_payment_record_status	409	Record not in signed or used status
ripple_signature_expired	409	Transaction expired (tefMAX_LEDGER)
ripple_submit_rejected	409	XRPL rejected the transaction
ripple_submit_failed	502	XRPL RPC call failed

Key Constants

Constant	Value	Description
RIPPLE_NETWORK	xrpl-mainnet	Network identifier
RIPPLE_EPOCH_OFFSET_SECONDS	946684800	Unix epoch to Ripple epoch offset (2000-01-01)
RIPPLE_RPC_URL	https://s1.ripple.com:51234	Default XRPL JSON-RPC endpoint
RIPPLE_TOKEN_ADDRESS	XRP	Asset identifier