Functional Specification
Section 1: Fourdotzero Introduction
What is Fourdotzero?
Fourdotzero is a convenient and fun way to pay for the little things online and in person.
Specifically designed for the next evolution of the internet, we make small payments pay to power Web 3.0 and metaverse business models. Making it easier and cheaper to buy and sell online services both now and in the future.
The Fourdotzero network was founded to create safe, trusted, regulated money.
Meet the digital way to pay.
Reference to all Network Documents
The following document make up the collection of Fourdotzero network documents (‣ Rulebook, Membership Agreement and Branding Kit)
1.0 Purpose and Context
This Functional Specification sets out the details for members to ensure the smooth running of the Fourdotzero system. It describes the system, architecture and more detailed components for implementation. The Functional Specification is applicable to all members who are responsible for keeping abreast of updates.
2.1 Overview of System Players
2.1.1 Users
Send and/or receive payments across the Fourdotzero network via a wallet provider. There are two types of users: consumers and retailers.
Consumers
Consume content, physical goods and make payments to other users for transaction values of $25 (in local equivalent) or less
Retailers
Sell content, services and/or goods (physical or digital) for transaction values of $25 (in local equivalent) or less, and use the Fourdotzero network to get paid.
2.1.2 Wallet Providers
Provide services to users for making and receiving payments. Users have a direct commercial relationship with a wallet provider. Wallet providers provide user wallets to their customers and have separate blockchain wallets only for the wallet provider’s internal use to manage settlement on the blockchain. Wallet providers are responsible for any regulatory elements.
2.1.3 Wallet Developers
Develop the wallet software or modules embedded in a wallet provider's wallets. These may be standalone or embedded mobile wallets, web browsers, e-commerce platforms, IoT devices etc.
2.1.4 Fourdotzero
Provides the payment network, rules, tokenomics and regulatory status to support the smooth operation of the Fourdotzero global micropayment network. Fourdotzero is a licensed e-money provider and the regulated entity for the issuance of money used within the Fourdotzero system.
2.1.5 Network Service Providers
Specialist service providers, integrated into the Fourdotzero network, offering optional services to wallet providers. This includes the service provider responsible for the blockchain used to settle Fourdotzero payments.
Fig 1.1 - Overview of System Players
3.0 Overview of System Components
3.1 Fourdotzero Network
The Fourdotzero network, as described in the system players section, connects many speciality areas to enable a successful network. Each player is responsible for their components as follows:
3.2 Wallets
These software modules allow users to send and receive payments across the Fourdotzero network. Developed by wallet developers (who also may be acting as a wallet provider), they may be in a standalone mobile application or embedded into another multi-purpose application, such as a mobile bank application, ride-hailing, or mobile network carrier application. Users wallets, in there many forms, interact with the wallet providers system only and the balances held in their system, separately the wallet providers have wallets used to interact with the smart contract and blockchain, these are for internal use to manage settlement on the blockchain.
3.3 Network Access Point / Node
Operated by the wallet provider, this connects Fourdotzero users to each other as well as to the internal Fourdotzero blockchain ledger. It allows for incoming and outgoing messages, such as payments and post-payment notifications.
3.4 Wallet Provider System
A combination of a ledger to maintain user balances as well as various compliance, regulatory and administrative functions.
Fig 3.1 - Overview of Fourdotzero Network
Section 2: Architectural Overview
4.0 Fourdotzero Components
The Fourdotzero system is made up of three main components, as follows:
Wallet - Wallets can be browser-based, mobile-based (standalone or embedded into an existing mobile application) or Internet of Things-based. Wallets connect with a payment gateway for making and receiving payments. That is to say, sender wallet providers make pre-validation calls to receiver wallet providers prior to transferring funds across the Fourdotzero network.
Network Access Point - This is a wallet provider’s interface to the Fourdotzero network.
Payment Network - The Fourdotzero payment network comprises all wallet providers, wallet developers and users connected under the governance structure as set out in the Fourdotzero Membership Agreement, Rulebook and Functional Specification.
4.1 Money Flows
4.1.2 Money Flow Introduction
Wallet providers will be agents, providing payment services using Fourdotzero money. The following section describes how this money is issued, and redeemed, the mechanics of the money in regulation and it’s safeguarding.
All Fourdotzero network payments must transit the Fourdotzero network, this includes payments between customers of the same wallet provider to ensure smart contract calculates and distributes fees correctly. Making on-net type payments, bypassing the Fourdotzero network to send payments within a wallet provider domain is banned and in contravention of the Rulebook and wallet provider’s licence.
4.1.3 Tokenomics
For a more detailed overview of Fourdotzero’s token please see our Tokenomics overview.
4.1.4 Wallet Funding/Defunding Overview
Terminology
Funding a wallet is paying money in. To do this, Fourdotzero must mint (issue) tokens. Defunding a wallet is taking money out, sometimes also known as a withdrawal, redemption, payout or cash out. To do this, Fourdotzero must burn (destroy) tokens.
How the Funding/Defunding Process Works
The funding process starts with fiat currency and ends with a Fourdotzero token. The defunding process starts with a Fourdotzero token and ends with fiat currency.
Funding and defunding a Fourdotzero wallet is possible 24/7 via a single click function in the wallet. All funding and defunding operations are performed by Fourdotzero.
Account and cash-based funding/defunding is supported, subject to limits defined in the Fourdotzero Rulebook. Cash-based funding/defunding must take place at Fourdotzero-registered service points, namely physical locations where cash can be exchanged for tokens or tokens for cash.
After a registered Fourdotzero user deposits funds to the Fourdotzero bank account, Fourdotzero issues the corresponding Fourdotzero e-money tokens. The User’s registered Fourdotzero wallet provider then applies the tokens to the user’s Fourdotzero account, as shown in the diagram below:
4.1.5 Transaction Status for Funding
The following table shows the status of the Funding operation.
| Funding Status | |
|---|---|
| 1 | Bank funds received pending minting |
| 2 | Tokens minted on DLT |
| 3 | Wallet provider sent receives minting details |
| 4 | Unmintable deposit - unknown bank reserve deposit |
| 5 | Bank funds are returned to the depositor without minting |
Fig 4.1 - Status Used For Managing Funding Operation
The following diagram show the sequence of activities in the Funding journey.
Fig 4.2 - Funding Flow Sequence Diagram
4.1.6 More on Defunding
After a registered Fourdotzero user makes a defund request, their wallet provider transfers the corresponding Fourdotzero e-money tokens to Fourdotzero. Fourdotzero then credits the user’s bank account with the defunded amount, as shown in the diagram below:
Transaction Status for Defunding
The following table show the status in the Defunding operation.
| Defunding Status | |
|---|---|
| 1 | Tokens received for burning |
| 2 | Tokens burned |
| 3 | Burned tokens paid to the customer by bank transfer |
| 4 | Burned tokens paid to customer cash handler by cash |
Fig 4.3 - Status’s Used for Managing De-funding Operation
The following diagram shows the sequence of activities in the Defunding journey.
Fig 4.2 - De-Funding Flow Sequence Diagram
Both Funding and Defunding operations happen in near real-time in the Fourdotzero system. Local or domestic payment infrastructure and bank account settlement cycles will govern when cleared funds are in turn available to users.
Section 3: Network Details
The Fourdotzero system supports many different end-client applications, payment initiation and allied transaction types. This section describes each type, giving examples where necessary.
5.0 Supported Clients Types
The following list shows where Fourdotzero application may be deployed. The list is non-exhaustive.
| Channel |
|---|
| Mobile |
| Browser |
| Desktop |
| Cloud-based system (i.e. WordPress) |
| IoT |
Fig 5.1 - List of Fourdotzero Client Applications
5.1 Detailed Payment Flows
This Simple Payment Journey below shows the major stages in the payment flow of a typical Fourdotzero payment. It starts with an invoice request, which may also come from a request-to-pay-based transaction or other invoice-based mechanisms in future product enhancements.
Fig 5.2 - Simple Payment Journey Sequence Flow
5.1.1 Initiation Types
The Fourdotzero network supports the following payment initiation types.
| Initiations Types | Comments | |
|---|---|---|
| 1 | p2p user-keyed | |
| 2 | p2b user-keyed | |
| 3 | p2p dynamic QR | |
| 4 | p2p static QR | |
| 5 | p2b dynamic QR | |
| 6 | p2b static QR | |
| 7 | p2p request-to-pay | |
| 8 | p2b request-to-pay | |
| 9 | p2p universal_link | |
| 10 | p2b universal_link | |
| 11 | p2p show-to-pay rtp | |
| 12 | p2b show-to-pay rtp | |
| 13 | Mandate | Soon |
| 14 | Another type | Soon |
Fig 5.2 - List of Payment Initiation Types
5.1.2 Transaction Types
The Fourdotzero network supports the following transaction types.
| Types | |
|---|---|
| 1 | network payment |
| 2 | refund request |
| 3 | refund payment |
| 4 | defunding |
| 5 | request-to-pay |
Fig 5.2 - List of Transactions Types
5.1.3 Transaction Status for Network Payment
See the Simplified Payment Journey diagram above for details of the flow. The following table shows the Regular Payment Flow status’.
| Network Payment Status | |
|---|---|
| 1 | initiated |
| 2 | payer checked |
| 3 | receiver checked |
| 4 | authorised (settlement triggered) |
| 5 | settled |
| 6 | complete |
| 7 | failed payment |
Fig 5.3 - List of Payment Status’
5.1.4 Regular Payment Flow States
Here we have the Regular Payment flow state diagram showing the happy and unhappy paths.
Fig 5.4 - Payment Status Flow Diagram
5.1.5 Transaction Status for Request to Pay
Request to pay functionality is supported by Fourdotzero, here we have the Regular Payment flow states including both the happy and unhappy paths.
| Request to Pay Status | |
|---|---|
| 1 | request to pay transaction |
| 2 | request to pay pending |
| 3 | request to pay timed out |
Fig 5.5 - List of Request to Pay Status’
The following diagram show the sequence of activities in the Request to Pay journey.
Fig 5.6 - Request to Pay Sequence Flow
5.1.6 Transaction Status for Refund Request
This following table shows the Refund Payment Flow status’.
| Refund Status | |
|---|---|
| 1 | refund payment transaction only |
| 2 | partial refund complete |
| 3 | full refund complete |
| 4 | failed refund |
| 5 | refund request transaction |
| 6 | refund request pending |
| 7 | refund accepted |
| 8 | refund rejected |
| 9 | refund request expired |
Fig 5.5 - List of Refund Status’
The sequence diagram below shows the Refund Request and Payment flow.
Fig 5.6 - Refund Sequence Flow
Refund Payment Flow States
Here we have the Refund Payment flow state diagram showing the happy and unhappy paths.
Fig 5.4 - Refund States Flow Diagram
5.1.7 Transaction Status for Reporting Bad Actors
If a registered Fourdotzero user has a bad experience with another registered user on the Fourdotzero platform, they are able to report this via their wallet provider. The wallet provider must investigate and act if their users are not behaving in good faith.
Fig 5.6 - Reporting a Bad Actor Sequence Flow
5.2 User Accounts
To facilitate different use cases, the Fourdotzero network supports different user account types. Note: Payments between these account types attract different fees, see Fees section for more details.
5.2.1 Account Types
Fourdotzero network supports a number of account types, as follows
| Type | |
|---|---|
| 1 | personal |
| 2 | retail |
| 3 | family account |
Fig 5.7 - List of Account Types
5.2.2 Account Status
A wallet provider can apply different descriptions to best reflect the status of an end-users Fourdotzero account.
| Status | |
|---|---|
| 1 | active |
| 2 | closed |
| 3 | blocked by the wallet provider |
| 4 | blocked by wallet holder |
| 5 | account suspended by wallet provider - lost |
| 6 | account suspended by wallet provider - stolen |
| 7 | frozen |
Fig 5.7 - List of Account Status
5.1.3 Account Management
Dealing with Reported User
In addition to the appropriate fraud prevention measures required of members, Fourdotzero users are also able to flag bad actors to wallet providers. Wallet providers must act if users are not behaving in good faith.
5.1.4 Wallet Provider and Wallet Developer Accounts
Members will require the following DLT wallets to participate in the Fourdotzero network:
| Operational Account | Fee Account | |
|---|---|---|
| Wallet Provider | Y | Y |
| Wallet Developer | N | Y |
| Network | N | Y |
| Fourdotzero | Y | Y |
Fig 5.7 - List of Account Needed by System Participants
The operational account is used to make and receive payments between wallet providers, and for funding and defunding transfers between wallet providers and Fourdotzero. The fee account is used to receive fees for facilitating payment and may be used to pay any non-compliance fines or defunding to fiat money.
5.3 Addressing
5.3.1 Users
For user addressing, Fourdotzero employs the open standard PayString secured by TLS1.3 and the Verifiable extension.
PayString is a simple, web-based protocol designed to make it as easy to send
money as it is to send an email. The
PayString protocol
uses human-readable addresses to transmit value in the currency of choice. The
PayString network allows participants to reach one another through
standardised addresses. An address such as alice$example.com maps
to the corresponding URL https://example.com/alice.
Making an HTTP GET request that follows the PayString protocol resolves to an address on the Fourdotzero network.
The PayString protocol is designed to be simple, general, open and universal. This makes it composable with any other existing namespace, including blockchain namespace projects, such as ENS and Unstoppable Domains or app-specific usernames. Anyone with an existing username or address can get a PayString address that works across all platforms.
5.3.2 Wallet Providers
Wallet providers receive a wallet provider key (wpk_id)when they are approved to join the Fourdotzero network. This key ensures the correct identification of the wallet provider and is used for fee distribution.
Wallet providers must make both their Fourdotzero wallet provider key and that of their wallet developer available to the system, as appropriate.
5.3.3 Wallet Developers
Wallet developers receive a wallet developer key (wdk_id) for production instances of their Fourdotzero wallet when they are approved to join the Fourdotzero network. This key ensures the correct identification of the wallet developer and is used for fee distribution.
5.4 Validation Failure Codes and End-user Messages
See Fourdotzero Rule Book.
5.5 Transaction Validation Checks
This section gives an overview of the recommended check performed throughout the use of Fourdotzero.
- Payer Checks - validating payer details before a payment is made and before a refund request is made
- Receiver Checks - validating receiver details before a payment is made and before a refund request is made
- Withdrawal checks - validating the user account before a withdrawal is made
- Funding checks - validating the depositor before minting (out of scope for the MVP)
The purpose of the checks is to validate the items in the table below before a payment transaction, refund request transaction or request-to-pay are executed. The checks are performed in different parts of the flows.
| Validation Item | Payer Checks | Receiver Checks | Withdrawal Checks | Funding Checks |
|---|---|---|---|---|
| Payer account exists | x | |||
| Payer account is active | x | |||
| Receiver account exists | x | |||
| Receiver account is active | x | |||
| payment principal (principal_amount) <= maximum payment | x | |||
| paid_amount <= (current balance - minimum balance) | x | |||
| if the account is non-kyc, check the payment is under the flow limit: (total out over the past month + total in over the past month + paid_amount) <= maximum_monthly_flow for the payment currency | x | x | ||
| if the account is non-kyc, check the current balance + paid_amount <= maximum_non_kyc_account_balance | x | |||
| (current balance - withdrawal) >= minimum balance | x | |||
| if the account is non-KYC check the withdrawal amount <= maximum withdrawal | x | |||
| the funding Fourdotzero id is valid | x | |||
| the funding Fourdotzero id is active | x | |||
| funding is insufficient to take the balance above the minimum | x | |||
| if the account is non-KYC the deposit keeps the balance within the maximum | x |
Fig 5.8 - List of Transaction Validation Checks
Section 4: Fees
6.0 Fees Introduction
Fees are payable on all payment and refund transactions across the Fourdotzero
network. Funding and defunding transactions do not attract fees. Fourdotzero
network automatically calculates these fees when processing transactions.
Wallet providers must ensure they implement the latest fees at all times,
represented in attribute total_txn_fee_percent provided by
Fourdotzero, available from
api.fourdotzero.io/networkdata to
registered wallet providers.
Fig 6.1 - Fee Rate Synchronisation Sequence Flow
The following is a list of product types on the Fourdotzero network. Typically the payer sends the fees unless the receiver has registered as a business/retailer account. A complete list of products supported is detailed below:
| Product | Initiation Type | Fee Payer |
|---|---|---|
| Product 1 | p2p user-keyed | Payer |
| Product 2 | p2b user-keyed | Receiver |
| Product 3 | dynamic QR-p2p | Payer |
| Product 4 | static QR-p2p | Payer |
| Product 5 | dynamic QR-p2b | Receiver |
| Product 6 | static QR-p2b | Receiver |
| Product 7 | p2p request-to-pay | Payer |
| Product 8 | p2b request-to-pay | Receiver |
| Product 9 | p2p universal_link | Payer |
| Product 10 | p2b universal_link | Receiver |
| Product 11 | refund_request | Refund Payment Payer |
Fig 6.2 - List of Product Types
Fee amount is constructed as follows:
Fees are calculated in the following manner:
6.1 Anatomy of Fees
| Principal Amount | Type of Payment | Payer debited | Receiver credited | Fees | |
|---|---|---|---|---|---|
| Payment 1 | 10 | P2P (payer pays fees) | 10.10 | 10.00 | 0.10 |
| Payment 2 | 10 | P2R (receiver pays fees) | 10.00 | 9.90 | 0.10 |
| DDL Terms (t600_customer_transaction) | principal_amount | paid_amount | received_amount | fee |
Note: totalTxnFeePercent = 0.01
Fig 6.3 - Fee Anatomy Table
6.1.2 Worked Examples
Payment 1: Calculation (P2P): Fee = [principle amount:10 * totalTxnFeePercent:0.01]= 0.10. So paid_amount = [principal_amount:10 +fee:0.1]=10.10 , received_amount=[principal_amount:10.00-fee:0.1]=10.00
Payment 2: Calculation(P2R): Fee = [principle amount:10 * totalTxnFeePercent: 0.01]= 0.10. So paid_amount = [principal_amount:10]=10.00, received_amount=[principal_amount:10.00-fee:0.1]=9.90
Notes on Data Normalisation ~~~~Fees and received_amounts can
be calculated, fee payer can be derived by the relationship between the
principal_amount and the paid_amount which if not
equal the Payer has paid fees, otherwise, the Receiver has paid fees. The Fee
is calculated as above and either added or subtracted from the
principal_amount added for Payer, see the application of Fees
section below.
Notes on Data Integrity
In the Settle Payment process flow, the DLT passes the receiver’s
received_amount to the r_wp and the payload_hash. Since the DLT
is the source of truth for balance and transaction data the
received_amount is recorded rather than derived. Therefore the
received_amountis recorded on the
transaction model (and is populated only for incoming payments to
the customer account)
Notes on Principal Amount, Paid Amount and Limits
The following rules apply when making checks where limits apply:
-
For a normal payment, the maximum payment amount (e.g. £20) applies to the
principal_amount(the paid amount may be higher where the payer pays fees) - For a refund payment, there is no maximum payment amount (it will be limited by the limit on the original payment, but may be higher than the limit as the refund includes feed paid by the payer)
-
Where a maximum monthly total payment applies, the total of payments and
received is calculated using
paid_amountandreceived_amount -
For the minimum balance amount, the
paid_amountis used to check the balance is at or above the minimum (this prevents fees from taking the balance below the minimum) -
Where a maximum balance applies,
received_amountis used to check an incoming payment and keeps the balance at or below the maximum
6.2 Application of Fees
The following section gives an explanation of how to apply fees across the different parties in the Fourdotzero
6.2.1 Payer Fees
6.2.2 Receiver Fees
6.2.3 Example UX for Fees
Payment 1- Payer Pays Fee
The first example shows when the Payer is responsible for paying the fees,
note on the Payer Receipt the principal_amount and the
paid_amount are not equal
| Payer Receipt | |
|---|---|
| Principal Amount | 10.00 |
| Paid Amount | 10.10 |
| Fee | 0.10 |
| Receiver Receipt | |
|---|---|
| Principal Amount | 10.00 |
| Received Amount | 10.00 |
| Fee | 0 |
Payment 2 - Receiver Pays Fee
The second example shows when the Receiver is responsible for paying the fees,
note on the Payer Receipt that the principal_amount and the
paid_amount are equal
| Payer Receipt | |
|---|---|
| Principal Amount | 10.00 |
| Paid Amount | 10.00 |
| Fee | 0 |
| Receiver Receipt | |
|---|---|
| Principal Amount | 10.00 |
| Received Amount | 9.90 |
| Fee | 0.10 |
6.2.4 Fees Modification
Fees are modified based on the know-your-customer (kyc) status for users.
Wallet providers hold kyc status for both payer and receiver in fields
p_kyc and r_kyc. These are passed in the payment
instruction, the total fee is the same if kyc = 0 or 1, an adjustment on the
Wallet Provider fee is made for non-kyc users which is paid to Fourdotzero.
6.3 Refunds Overview
Refunds can be requested on any complete payments, whether person to person or person to retail. Requests are made by the payer of the initial payment.
6.3.1 Business Rules
1) The payer requesting a refund must receive exactly the amount the receiver agrees to refund
2) Refund request and refund payment maybe up to the amount of the initial payment
3) Refund payment fees will be paid by the sender of the refund payment (initial payment receiver)
4) Both initial and refunded payments attract fees
5) Refunder, the payer of the refund (original receiver) pays refund fees
6.3.2 Calculation of Refund Fees
Payer Fees Calculation
6.3.3 User Experience
Here we have a layout of the example payment/refunds shown from both the paying and receiving party. Note that the refund is paid by the receiver of the initial payment and received by the payer of the original payer.
Payment 1 (Initial Payment)
| Payer Receipt | |
|---|---|
| Amount | 10.00 |
| Paid Amount | 10.10 |
| Fee | 0.10 |
Refund 1
| Receiver Receipt | |
|---|---|
| Amount | 10.00 |
| Net Received | 10.00 |
| Fee | 0 |
| Refund Payer Receipt | |
|---|---|
| Amount | 10.00 |
| Paid Amount | 10.10 |
| Fee | 0.10 |
| Refund Receiver Receipt | |
|---|---|
| Amount | 10.00 |
| Net Received | 10.00 |
| Fee | 0 |
Payment 2 (Initial Payment)
| Payer Receipt | |
|---|---|
| Amount | 10.00 |
| Paid Amount | 10.00 |
| Fee | 0 |
Refund 2
| Receiver Receipt | |
|---|---|
| Amount | 10.00 |
| Net Received | 9.90 |
| Fee | 0.10 |
6.3.4 Design Logic
The following section outline the calculation methods for establishing amounts and fees to be paid on a return payment.
Return Calculation Variables
| Term | Description |
|---|---|
| pt | initial payment |
| rt | refund request related to initial payment (linked_payment) |
| Principal Amount | amount user would like to send |
| Paid Amount | amount (PrincipalAmount) to be sent including fees |
| Request Amount | amount refund requestor requests for refund (this will be amount in refund request transaction) |
Fig 6.4 - Calculations Variables Used in Establishing Amounts and Fees for Refunds
Return Payment Fee Calculations
Payer app function to ensure payer refund request does not exceed initial payment
Receiving app function to ensure receiver refund payment does not exceed the initial payment
Receiving app function to calculate refund payment paid amount
Section 5: Data Sharing
7.0 Data Sharing Introduction
Wallet providers must share data with both Fourdotzero and wallet developers, as described below.
Data must be submitted by wp_key at data.fourdotzero.io as described in the API Explorer.
| Category | Data | Frequency |
|---|---|---|
| Flows | Sent (ccy) | Daily |
| Received (ccy) | Daily | |
| Sent (#) | Daily | |
| Received (#) | Daily | |
| Errors | Failed Transactions (#) | Daily |
| Balance | End of Day (ccy) | Daily |
| Users | Total Users (#) | Monthly |
| Active Users (#) | Monthly | |
| Closed Users in period(#) | Monthly | |
| blocked by wallet provider in period(#) | Monthly | |
| blocked by wallet holder in period(#) | Monthly | |
| account suspended by wallet provider - lost in period(#) | Monthly | |
| account suspended by wallet provider - stolen in period(#) | Monthly | |
| Frozen in period(#) | Monthly | |
| System | System Uptime (%) | Monthly |
Fig 7.1 - List of Required Wallet Providers Data Sharing Items and Frequency
Section 6: Wallet User Experience
8.0 Checklist and Considerations
User experience is paramount for application that are use frequently and require a high level of trust such as required for payment applications. The table below, combined with the Fourdotzero Brand Guidelines, help to achieve a high quality user experience.
| Ref | Activity | Mandatory Network Function | Description |
|---|---|---|---|
| 1 | Onboarding | Y | Wallet providers must be able to onboard users in less than one minute via either a standalone or embedded application. The minimum information required for sign-up is name, e-mail or mobile number and pnp_id. |
| 2 | Authentication | Not prescribed | To provide ease of use whilst ensuring the highest level of security, wallet providers may employ secure and up-to-date authentication methods, especially for wallet login and payment. Multi-factor or strong customer authentication methods are strongly recommended. |
| 3 | Authorisation | Not prescribed | |
| 4 | Make Payment | Y |
Support the making of payments through the following initiation
types: [p2p user-keyed p2b user-keyed p2p dynamic QR p2p static QR p2b dynamic QR p2b static QR p2p request-to-pay p2b request-to-pay p2p universal_link p2b universal_link p2p show-to-pay rtp p2b show-to-pay rtp] |
| 5 | Receive Payment | Y | Users must be able to receive payments to their Fourdotzero wallet |
| 6 | Contact Book / Favourites | Y | Users must be able to save another user as a ‘contact’ for quick reference and ease of use for subsequent transactions |
| 7 | Receipts | Y | Users must be able to export a receipt from their wallet to share digitally, store or print |
| 8 | Search | Y | Users must be able to search transaction by date, type, amount, retailer, keywords, status and counter-party at a minimum |
| 9 | Transaction Analysis and Manipulation | N | Ability for user to be able to perform advances date and subject search / filter and sorting. |
| 10 | User Microsite | N | Provide a simple microsite for users allowing users to host by pnp_id their details and in the case of a retailer their products allowing ideally allowing for a minimum of 10 products including product description, link and prices. |
| 11 | Blocking My Wallet | Y | Allows the user to block and unblock their wallet from both sending and receiving payments. This on / off function also allows users to manage their own risk. |
| 12 | Requesting a Refund | Y | This is a mandatory function and must be provided in an easy to use accessible / highly visible area of the wallet. |
| 13 | Report Users | Y | This is a mandatory function and must be provided in an easy to use accessible / highly visible area of the wallet. |
| 14 | Seller Rating | Y | This is a mandatory function and must be provided in an easy to use accessible / highly visible area of the wallet. |
Fig 8.1 - List of Wallet User Experience Considerations
Section 7: Implementation Guidelines
9.0 How Wallet Providers Connect to the Fourdotzero Network
After they have signed the Fourdotzero membership agreement, Fourdotzero issues wallet developers and wallet providers with an x.509 digital certificate.
Fourdotzero acts as a certificate authority and also manages the certificate revocation list. Asynchronous ephemeral keys will be used for all transactions between parties in the Fourdotzero network ensuring confidentiality, integrity and availability.
Fig 9.1 - Establishing Connection to the Fourdotzero Network Sequence Diagram
9.1 Network Data
Wallet providers must refresh the following network data parameters daily at 00:00 UTC. See API Explorer for more details api.fourdotzero.io/networkdata
| Category | Field | Attribute | Type | Change Date | Description |
|---|---|---|---|---|---|
| Fees | total_txn_fee_percent | Number | Y | See Fees section | |
| Limits | maximum_non_kyc_account_balance | Country | Number | Y | Maximum Balance for a non-KYC’d User |
| maximum_non_kyc_withdrawal_amount | Country | Number | Y | Maximum Withdrawal amount for a non-KYC’d User | |
| maximum_monthly_flow | Country | Number | Y | Maximum Wallet Flow for a non-KYC’d User | |
| maximum_payment_amount | Currency | Number | Y | The maximum amount for a single payment transaction | |
| Network Addresses | pnp_op_dlt_id | Currency | Address | Y | DLT Wallet Address for Fourdotzero for minting and burning |
| pnp_fee_dlt_id | Currency | Address | Y | DLT Wallet Address for Fourdotzero for Fees | |
| network_fee_dlt_id | Currency | Address | Y | DLT Wallet Address for Network Provider for Fees | |
| All other addresses are provided as an array | |||||
| Contract Details | pGB | Address | Smart Contract address for Fourdotzero GBP token | ||
| pEu | Address | Smart Contract address for Fourdotzero Euro token | |||
| pUS | Address | Smart Contract address for Fourdotzero USD token | |||
| All other Address details are provided as an array. | |||||
| Reference data | urgent_network_update | Global, Region, Country, Wallet Developer | String | Communication to Fourdotzero network members is restricted for urgent matters such as information security breaches or other network health matters | |
| network_update | Global, Region, Country, Wallet Developer | String | Communication to Fourdotzero network members is restricted for non-urgent matters such as information security breaches or other network health matters |
Fig 9.2 - List of Network Broadcast Data Items Wallet Providers Must Keep upto Date With
9.2 Idempotency
To prevent accidental ‘double payments’, making the same payment multiple times unintentionally, all operations must be idempotent. That is an operation will produce the same results when executed over and over again.
Of the four HTTP methods [Get, Put, Delete and Post] only post presents an idempotent concern. All others methods given the same input will create the same result due to the methods behaviour or the uniqueness of the request, i.e. you cannot delete a specific user twice or update the address to city London again and again and achieve a different result, Get method behaviour of course, changes no results.
Fourdotzero does not stipulate how idempotency is achieved although recommends the use of an idempotent key. A UUIDv4 or a string with a low possibility of collision be used to uniquely identify all transactions thus avoiding double processing of a unique transaction.
9.3 Strong Customer Authentication
Strong customer authentication (SCA) is a requirement of the European Union Revised Directive on Payment Services (PSD2) and a requirement of the Fourdotzero network.
SCA should be implemented both for Strong Authentication and Dynamic Transaction linking, the following description is for information only, please read PSD2 information for more details.
9.3.1 Strong Authentication
1) Something that only the customer KNOWS. For example, a password, PIN, or response to a security question.
2) Something that only the customer HAS. For example, a mobile phone.
3) Something that the customer IS. For example, a biometric such as a fingerprint.
9.3.2 Dynamic Linking
(a) the payer is made aware of the amount of the payment transaction and of the payee;
(b) the authentication code generated is specific to the amount of the payment transaction and the payee agreed to by the payer when initiating the transaction;
(c) the authentication code accepted by the payment service provider corresponds to the original specific amount of the payment transaction and to the identity of the payee agreed to by the payer;
(d) any change to the amount or the payee results in the invalidation of the authentication code generated.
9.4 Wallet Developer Communication
The following data must be provided by wallet developers as described below. All data must be submitted by wd_key at data.fourdotzero.io as described in the API Explorer.
| Category | Field | Description |
|---|---|---|
| Version | Latest version | Date released |
| Downloads | Total | Monthly |
| In period | Monthly | |
| Users | Active users in period (#) | Monthly |
Fig 9.3 - List of Wallet Developer Data Submission Requirements
9.5 Wallet Provider Outline Architecture
Here is a schematic component diagram showing the elements and functions needed to operate as a wallet provider.
Fig 9.4 - Outline System Architecture
9.6 Non-Functional Requirements
9.6.1 Real-time Payments
Wallet providers must be able to facilitate real-time payments 24/7/365. This includes the ability for their users to send and receive payments and refunds across the Fourdotzero network, as well as fund and defund Fourdotzero accounts, and receive real-time balance status updates.
9.6.2 Performance
System availability will be such that users can make and receive payments and refunds, and in later developments make and receive requests to pay notifications.
9.6.3 Security
Security across the Fourdotzero system is addressed by the combined efforts of Fourdotzero, wallet providers, wallet developers, network providers and users.
The outline shared responsibility model is shown below and describes who is responsible for what.
9.6.4 Shared Responsibility Model
The model below show the distribution of responsibilities between the wallet provider and Fourdotzero.
Fig 9.5 - Shared Responsibility Model
The mandatory expectation for security from all systems participants are as follows:
1) HTTPS/TLS1.2+ will be used
2) Any hashing will be SHA-256 and above
3) Best practice DDoS services will be employed
Fourdotzero compiles a vulnerability threat radar system and holds quarterly security calls with invited members to capture, evaluate, monitor and respond to ongoing threats.
9.6.5 Assurance Programme Responsibilities
Fourdotzero maintains a set of automated tests that can be utilised as is or extended by wallet providers in their launch testing and continued. The tests can be run during the development and regression stages of the software lifecycle.
Self-certification is required prior to production services and the following enhancement as outlined in Network Upgrade. Prior to a wallet provider going live, self-certification with evidence of successful testing provided to Fourdotzero is required.
Tests can be found at develop.fourdotzero.io
9.6.6 Network Upgrades
Changes to wallet provider implementations are made through updates to Networks Documents for Network Enhancements, or in the case of vulnerabilities through the ‘urgent_network_update’ channel. The update schedule service level is as follows:
| Change Type | Category | Timetable |
|---|---|---|
| Vulnerability | S1 | 24 hours |
| S2 | 1 week | |
| S3 | 1 month | |
| Enhancements | 3 months after publication |
Fig 9.6 - List of Service Levels and Activities for Network Upgrades
9.6.7 Dashboard and Operational Management
The following screenshots give wallet providers an overview of the type of functionality they may wish to include in their business and operational support systems.
Appendix
Application Programming Interfaces
Context Id
The following tables outline mandatory fields that persists across the Fourdotzero network.
| Context Id | Description |
|---|---|
| order_id | Generated by by Receiver when issuing an Invoice |
| invoice_id | Invoice is a completed payment request from the Receiver to the Payer generated by Receiver |
| confirmation_id | Code generated by Receiving Wallet Provider to Payer approving all details of forthcoming payment (confirms the action of the pre-validation checks) |
| End to End Payment ID (e2e_id) | Issued/Generated by the Payer Wallet application in UUID format when initiating a payment, or Issued / Generated by Fourdotzero for Minting or Burning Fourdotzero e-money token in UUID format |
| DLT Transaction ID (dlt_tx_id) | Issued / Generated by DLT as transaction is written to the DLT |
| pnp_auth_code | Code generated by payment initiating client for verification by Payer Wallet Provider to support Dynamic Linking SCA (strong customer authentication) requirement |
| linked_payment_e2e_id | For a refund request, a new transaction is added to the table with type "refund request" and with e2e_id of the original payment. |
| payload_hash_dlt | DLT payload hash to exchange transaction private details off-chain between Wallet Providers. Wallet Provider Restful APIs |
Fourdotzero e-money Token Smart Contract
The following outlines the smart contract address, details and interactions.
| Parameters | Key / Address |
|---|---|
| FourdotzeroContractId |
GBP: details provided as per section 9.1 USD: details provided as per section 9.1 Euro: details provided as per section 9.1 Euro: details provided as per section 9.1 |
| Web3.0 Functions contract.defund |
Arguments: uint256 amount bytes32 payloadHash Function Details: Sends an amount of pGB tokens to the pGB admin for defunding. Only the wallet providers can call this function. Emits the Defund event and logs it to Snowtrace. |
| Web3.0 Functions contract.payment |
Arguments: uint256 amount bytes32 payloadHash bool p_kyc bool r_kyc address p_wp_fee_dlt_id address r_wp_fee_dlt_id address p_wd_fee_dlt_id address r_wd_fee_dlt_id Function Details: Sends an amount of pGB tokens from the sender to r_wp_op_dlt_id after all the fees. Takes into account KYC for both the receiver and payer. Only the wallet providers can call this function. Emits the Payment event and logs it to Snowtrace. |
| {WalletId} | see table below |
Wallet Id Information
| Account Name | Account Details |
|---|---|
| Fourdotzero DLT Operation Account | See section 9.1 |
| Fourdotzero DLT Fee Account | See section 9.1 |
| DLT / Network Account | See section 9.1 |
Wallet Provider API
The following list of API’s outlines interactions between wallet provider to wallet provider and wallet to counter-party wallet provider for payments and other messaging communication.
| ModelRestful API | Description |
|---|---|
| 2.1 Request-to-Pay | Enables users to make a request-to-pay (RtP) transaction. Use the rtp function for a receiver to make a payment request from their client app to the payer’s wallet provider (the payer client app then picks up the request when the 1.4 Synch Service 3 runs) |
| 2.2 Receiver Check | Allows the payer’s client app to check that the receiver can receive payment if sent - details are sent from the payer’s client app direct to the receiver’s wallet provider |
| 2.3 Resolve Payload | Returns full payment transaction details on request from the receiver wallet provider to the payer wallet provider |
| 2.4 Credit Confirmation | Writes to the payers wallet provider a credit confirmation sent by the receiver’s wallet provider |
| 2.5 Refund Request Send | Write to the payer’s wallet provider a refund request sent from the receiver’s client app |
| 2.6 Refund Request Decline | Writes to the payer’s wallet provider Transaction table an update to the request transaction from pending to refund rejected, sent from the receiver wallet provider |
| 2.7 Receiver Rating | Writes to the receiver’s wallet provider Transaction table an update to a payment transaction with a receiver rating sent from the payer wallet provider. Allows a user to give feedback to another user on the network on a scale of 1-5 |
| 2.8 Bad actor | Writes to the receiver’s wallet provider Transaction table an update to a payment transaction with bad actor details sent from the payer wallet provider. Allows a user to report another user’s bad behaviour on the network. |
2.1 Request-to-Pay API
POST /rtp/:{p_pnp_id}
Resource Description: enables users to make a request-to-pay
(RtP) transaction. Use the rtp function for a receiver to make a payment
request from their client app to the payer’s wallet provider (the payer client
app then picks up the request when the 1.4 Synch Service 3 runs).
Content: application/json
2.2 Receiver Check
POST /pay$tring/:{r_pnp_id}
Resource Description: Allows the payer’s client app to check that the receiver can receive payment if sent - details are sent from the payer’s client app direct to the receiver’s wallet provider
Content: application/json
2.3 Resolve Payload
GET /resolve/:{payloadHash}/?signature
Resource Description: Returns full payment transaction details on request from the receiver wallet provider to the payer wallet provider
2.4 Credit Confirmation
POST /confirm/credit/:{payloadHash}
Resource Description: Writes to the payer’s wallet provider a credit confirmation sent by the receiver’s wallet provider
2.5 Refund Request Send
POST /refund/:{linked_payment_e2e_id}
Resource Description: Write to the payer’s wallet provider a refund request sent from the receiver’s client app. Content: application/json
2.6 Refund Request Decline
POST /refund/decline/:{invoice_id}
Resource Description: Writes to the payer’s wallet provider Transaction table an update to the request transaction from pending to refund rejected, sent from the receiver wallet provider. Content: application/json
2.7 Receiver Rating API
POST /rate/:{e2e_id}
Resource Description: Writes to the receiver’s wallet provider Transaction table an update to a payment transaction with a receiver rating sent from the payer wallet provider. Allows a user to give feedback to another user on the network on a scale of 1-5 Content: application/json
2.8 Bad actor API
POST /flag/:{e2e_id}
Resource Description: Writes to the receiver’s wallet provider Transaction table an update to a payment transaction with bad actor details sent from the payer wallet provider. Allows a user to report another user’s bad behaviour on the network.
Fourdotzero Restful APIs
The following list of API’s outlines interactions between wallet provider and Fourdotzero core for Funding and Defunding operations.
| Restful API | Description |
|---|---|
| 3.1 Resolve (lookup) funding | Provides the client app pnp_id from the Fourdotzero console to the wallet provider for a funding transaction |
| 3.2 Funding Confirmation | Provides the Fourdotzero core middleware with confirmation of funds credited at the wallet provider |
| 3.3 Resolve Defund Details | Provides the Fourdotzero core middleware from the wallet provider with the defunding user’s payout information |
| 3.4 Account Credit Confirmation | Updates the defunding transaction on the wallet provider Transaction table with credit confirmation details sent by the Fourdotzero core middleware (after resolving the withdrawal/payout details from the wallet provider) |
| 3.5 Account Defund Confirmation | The Fourdotzero core middleware notifies the wallet provider that the GBP funds for the withdrawal request have been credited to the user’s bank account |
3.1 Resolve (lookup) funding:
GET api.core.fourdotzero.io/resolve/{payloadHash}
Resource Description: Provides the client app pnp_id from the Fourdotzero console to the wallet provider for a funding transaction
3.2 Funding Confirmation
Resource Description: Provides the Fourdotzero core middleware with confirmation of funds credited at the wallet provider
3.3 Resolve Defund Details
POST /resolve/:{payloadHash}
Resource Description: Provides the Fourdotzero core middleware from the wallet provider with the defunding user’s payout information
3.4 Account Credit Confirmation:
POST confirm/credit/:{payloadHash}
Resource Description: Updates the defunding transaction on the wallet provider Transaction table with credit confirmation details sent by the Fourdotzero core middleware (after resolving the withdrawal/payout details from the wallet provider)
3.5 Account Defund Confirmation:
POST /confirm/defund
Resource Description: The Fourdotzero core middleware notifies the wallet provider that the GBP funds for the withdrawal request have been credited to the user’s bank account (same process flow as for wp→wp for payment confirmation)
Reference Wallet Provider Database Definition Language
The follow is a reference database definition language (DDL) for a wallet Provider.