FPSF-SS-002 — Reference
Layer: Reference · Audience: developers (daily reference) For normative requirements, see the Formal Specification.
Message Type Index
Client → Gateway Messages
| Type | Section | Description |
|---|---|---|
GET_NONCE | §8.1 | Retrieve current permit nonce for a wallet and token. |
GET_FEES | §8.2 | Retrieve fee breakdown (operatorFee, acquiringFee, totalWithFees) for a given token, principal, and acquirerId. |
GET_BALANCE | §8.3 | Retrieve current balances for one or more tokens. |
GET_HISTORY | §8.4 | Retrieve transfer history for one or more tokens. |
SUBMIT_PAYMENT | §8.5 | Submit a signed TransferRequest for processing. |
SUBMIT_ACQUIRING | §8.6 | Submit a signed BuyAcquiringPackRequest for processing. |
SUBSCRIBE_BALANCE | §9.1 | Register to receive balance update notifications. |
SUBSCRIBE_TRANSFERS | §9.2 | Register to receive transfer notifications. |
UNSUBSCRIBE | §9.3 | Cancel an active subscription for specified tokens on a channel. |
Gateway → Client Messages (Responses)
| Type | Section | Description |
|---|---|---|
NONCE_RESULT | §8.1 | Current permit nonce. |
FEES_RESULT | §8.2 | BrokenDownAmount with operatorFee, acquiringFee, totalWithFees. |
BALANCE_RESULT | §8.3 | Array of { domainSeparator, balance } objects. |
HISTORY_RESULT | §8.4 | Array of TransferRecord objects, paginated. |
SUBMIT_PAYMENT_ACK | §8.5 | Acknowledgment with initial ENQUEUING status and echoed payloadId. |
SUBMIT_ACQUIRING_ACK | §8.6 | Acknowledgment with initial ENQUEUING status. |
SUBSCRIBE_BALANCE_ACK | §9.1 | Confirms subscribed tokens. |
SUBSCRIBE_TRANSFERS_ACK | §9.2 | Confirms subscribed tokens. |
UNSUBSCRIBE_ACK | §9.3 | Confirms removed tokens. |
ERROR | §12 | Error response for any failed request. |
Gateway → Client Messages (Push Notifications)
| Type | Section | Trigger |
|---|---|---|
BALANCE_UPDATE | §9.1 | Balance changed for a subscribed token. |
TRANSFER_NOTIFICATION | §9.2 | New confirmed transfer for a subscribed token. This is the final settlement signal. |
SUBMISSION_STATUS | §10.2 | Submission status transition. |
Submission Status Values
| Status | Terminal | Description |
|---|---|---|
ENQUEUING | No | Accepted by gateway; being passed to broadcast-service. |
PENDING | No | Received by broadcast-service; validation in progress. |
BROADCASTING | No | Validation passed; transaction submitted to network. |
SUCCESS | Yes | Network accepted the transaction. NOT final settlement. |
FAILURE | Yes | Submission failed. See failureCategory and failureReason. |
Error Codes
| Code | Category | Description |
|---|---|---|
MISSING_FIELD | STRUCTURAL_ERROR | Required field absent. |
INVALID_FORMAT | STRUCTURAL_ERROR | Field does not conform to expected format. |
INVALID_SIGNATURE | AUTHENTICATION_ERROR | Signature malformed or unverifiable. |
ADDRESS_MISMATCH | AUTHENTICATION_ERROR | Recovered signer ≠ callerAddress. |
EXPIRED_DEADLINE | AUTHENTICATION_ERROR | deadline is in the past. |
UNSUPPORTED_TOKEN | SEMANTIC_ERROR | Domain separator or token address not recognized. |
NONCE_MISMATCH | SEMANTIC_ERROR | Supplied nonce ≠ on-chain nonce. |
UNKNOWN_PAYLOAD_ID | SEMANTIC_ERROR | payloadId not known to any active session. |
ALREADY_SUBMITTED | SEMANTIC_ERROR | payloadId already processed or processing. |
WALLET_NOT_FOUND | NOT_FOUND | No state found for the wallet address. |
INITIALISING | SEMANTIC_ERROR | Wallet state still being collected. Retry shortly. |
RATE_LIMIT_EXCEEDED | RATE_LIMIT | Request rate exceeded. |
INTERNAL_ERROR | INTERNAL_ERROR | Unexpected gateway-side failure. |
Submission Failure Categories
Used in SUBMISSION_STATUS notifications when status: "FAILURE":
| Category | Description |
|---|---|
STRUCTURAL_ERROR | Submission payload failed structural validation. |
SEMANTIC_ERROR | Business rule violated (expired deadline, nonce mismatch, unknown payloadId). |
CRYPTOGRAPHIC_ERROR | Signature verification failure or signer mismatch. |
BROADCAST_ERROR | On-chain transaction reverted or could not be submitted. |
Glossary
| Term | Definition |
|---|---|
| BrokenDownAmount | Fee breakdown object: operatorFee, acquiringFee, totalWithFees. All in token units as decimal strings. |
| Caller Address | The EVM address identifying the wallet in a gateway message. MUST match the recovered signer. |
| Domain Separator | A bytes32 EIP-712 domain separator used as the primary token identifier in the gateway interface. |
| Idle Timeout | The configurable duration after which a connection with no inbound activity is closed. Recommended: 5 minutes. |
| Order Reference | A bytes16 value created by the merchant for charge tracking. A separate parameter from acquirerId. |
| Acquirer ID | A bytes16 UUID identifying a registered Acquirer. A separate parameter from orderReference. |
| Subscription | A per-connection registration for real-time push notifications. Cancelled when the connection closes. |
| Terminal State | A submission status from which no further transitions occur: SUCCESS or FAILURE. |
| Transfer Notification | The definitive signal of final payment settlement. Delivered after transfer-history confirms sufficient block confirmations. |
| Zero-UUID | 0x00000000000000000000000000000000. Used as acquirerId when no Acquirer is involved. |
FPSF-SS-002 v1.0.0 · Draft · Fabric Payment Standards Foundation · Apache-2.0