FPSF-CPP-001 — Reference
Layer: Reference · Audience: developers (daily reference) For normative requirements, see the Formal Specification.
Mandatory API Endpoints
| Endpoint | Description |
|---|---|
POST /v1/cashpack/issue | Submit a Lock Request. Returns a signed cash-pack on success. |
POST /v1/cashpack/renew | Submit a cash-pack plus a Renewal Entry. Returns updated signed cash-pack. |
POST /v1/cashpack/redeem | Submit a Redemption Request plus the cash-pack. Returns Redemption Confirmation. |
GET /v1/cashpack/{pack_id}/status | Query instrument status. Restricted to issuing Principal and Operator. |
Instrument Status Values
| Status | Terminal | Meaning |
|---|---|---|
ACTIVE | No | Instrument is valid and can be renewed or redeemed. |
REDEEMED | Yes | Redeemed. Funds released. |
EXPIRED | Yes | Reached expiry without redemption. Funds returned to Principal. |
CANCELLED | Yes | Cancelled by Operator (typically via legal order). Funds held pending instruction. |
Error Codes
| Error Code | Meaning |
|---|---|
INSUFFICIENT_BALANCE | Principal's available balance is less than the requested amount. |
AMOUNT_EXCEEDS_LIMIT | Amount exceeds the Operator's configured maximum. |
INVALID_SIGNATURE | One or more signatures failed verification. |
BEARER_MISMATCH | Submitting public key does not match current_bearer_pk. |
CHAIN_DIGEST_MISMATCH | prev_chain_digest does not match the instrument's current chain_digest. |
INSTRUMENT_NOT_ACTIVE | Instrument status is REDEEMED, EXPIRED, or CANCELLED. |
CHAIN_DEPTH_EXCEEDED | renewal_chain has reached the Operator's configured maximum depth. |
REDEEMER_NOT_IDENTIFIED | Redeemer could not be verified to the required identity level. |
DUPLICATE_ID | request_id or renewal_id has been seen before (replay prevention). |
EXPIRY_INVALID | Requested expiry is outside the Operator's permitted range. |
Well-Known Resources
| URL | Purpose |
|---|---|
/.well-known/cashpack-policy.json | Operator Policy Document |
/.well-known/cashpack-pubkey.json | Operator's current public signing key (JWK format, RFC 7517) |
Glossary
| Term | Definition |
|---|---|
| Bearer | The entity currently authorized to renew or redeem a cash-pack, identified by control of the private key corresponding to current_bearer_pk. |
| Cash-Pack | The signed digital bearer instrument defined in this specification. |
| Chain Digest | A rolling SHA-256 hash binding each entry in the renewal chain to all previous entries. |
| Disposable Key Pair | An asymmetric key pair generated for a single instrument and discarded after use. |
| Initial Bearer | The first recipient of a cash-pack, whose public key is specified in the Lock Request. |
| Intermediate Bearer | Any bearer who renews the instrument rather than redeeming it. Not identified to the Operator. |
| Lock Request | The signed message submitted by the Principal to initiate issuance. |
| Operator | The regulated entity that issues, countersigns, and redeems cash-packs. |
| Principal | The identified account holder who requests issuance and whose funds are locked. |
| Renewal | The act of updating current_bearer_pk to a new public key, transferring bearer rights. |
| Redemption | The final conversion of a cash-pack into spendable funds by the current bearer. |
FPSF-CPP-001 v1.0.0 · Draft · Fabric Payment Standards Foundation · Apache-2.0