Overview

A FIO Request is a transaction in which a payee is requesting funds from a payer using a FIO Handle. The details of FIO Requests are private and only readable by the counter parties to the transaction.

This request is stored on-chain, and all sensitive metadata is encrypted (currency, amount, public address of payee, FIO Data, etc.) using the Diffie-Hellman key exchange scheme, which utilizes a shared secret from the payee private key and payer public key. This encryption is always enabled for all FIO Requests.

The payer's wallet or application polls the FIO Chain for relevant requests, and when found, decrypts the request inside their wallet (at which point a wallet can choose to implement a notification mechanism or FIO Request UI). This information is then used to pre-populate the send screen of the relevant blockchain whose token/coin is being requested.

The payer has a choice whether to approve or reject the request. If rejected, there is a status update made on FIO Chain, which removes the request from being shown.

FIO Requests are included as part of the bundled transaction with registering a FIO Handle.

📘

FIO Request does not use mapped addresses

The crypto public address specified in FIO Request does NOT have to be the same as public_address mapped using /add_pub_address

Native Integration

For wallets desiring full control over the registration user experience, the best strategy is to execute mapping actions directly to the FIO Chain.

Getters

Integrating these actions do not require the integrator to have access to user's FIO Private Key.

Available FIO Request Getters

🚧

Some data is encrypted

Please note that some data returned by these getters is encrypted and needs to be decrypted before it is displayed to the user. See Encryption in FIO Request and FIO Data for more details.

Write Transactions

Integrating these actions require the integrator to have access to user's Private key and properly serialize and sign each transaction. For additional information, see Write Transaction.

Available FIO Request Actions

🚧

Some data must be encrypted

Please note that some data passed into these actions needs to be encrypted. See Encryption in FIO Request and FIO Data for more details.

Example

Alice requests 1 BTC from Bob

• In her wallet Alice enters:
  • Amount and token type: 1 BTC
  • Memo: "Invoice 123"
• Public address is automatically selected for her as the public address of the wallet she is requesting from
• public address, amount, memo and other data are encrypted. If you are using the FIO SDK, encryption is done as part of the requestFunds function call.
• newfundsreq is submitted to FIO Chain.
• /get_sent_fio_requests will return the request just sent with the status requested and all encrypted data including memo. We recommend wallets show this request with a status of “pending”.

Bob checks his wallet for new requests

• /get_pending_fio_requests will return the request just sent with the status requested and all encrypted data including “Invoice 123” memo. We recommend wallets show this request for Bob to act on.

Bob accepts the request and pays Alice

Step 1

• BTC public address, amount and memo are decrypted
• Wallet creates a payment for 1 BTC to provided BTC public address.
• User has the option to modify amount or memo.
• Once user approves, the transaction is broadcasted to Bitcoin blockchain using the normal wallet transaction workflow.

Step 2

• Actual amount, actual memo, transaction ID (obt_id) from Bitcoin blockchain and other data are encrypted. If you are using the FIO SDK, encryption is done as part of the recordObtData function call.
• recordobt is sent to FIO Chain with status set to sent_to_blockchain.

Alice checks payment

• /get_sent_fio_requests will return the request with the status sent_to_blockchain. We recommend wallets show this request as “received”.
• /get_obt_data will return important encrypted metadata wallets should attach to the request and/or the actual Bitcoin transaction including actual amount, actual memo, transaction ID (obt_id) from Bitcoin blockchain and other data. obt_id may be used to match the information with the actual Bitcoin blockchain transaction.

Bob checks his wallet for new requests

• /get_received_fio_requests will return the the request with the status sent_to_blockchain. We recommend wallets show this request as “paid”.

UX/UI Considerations

• Provide notifications for incoming requests (push notifications and in-app notifications).
• Make sending FIO Requests accessible from a cryptocurrency’s wallet page.
• Provide notifications that FIO Request has successfully been sent.
• When sending a FIO request, the user should be able to choose which FIO Handle to send from (assuming the user has multiple addresses)
• When accepting a FIO Request, the user should be able to choose which FIO Handle to accept from (assuming the user has multiple addresses)

Quality Assurance Checklist

The following lists the items that should be tested to confirm support for FIO Request:
Sent FIO Requests

• User is able to send a FIO Request to a valid FIO Handle
• User is able to add a memo when sending a FIO Request
• User is able to view sent FIO Requests
• Sent Requests show the FIO Handle of the recipient, the token being requested, the amount of the request, request memo, and the status of the request (requested, rejected, received)
• User who sent Request is able to cancel the Request

Received FIO Requests

• User is able to view pending FIO Requests
• Pending Requests show the FIO Handle of the user that sent the Request, the token being requested, the amount of the Request, and the Request memo
• User who recieved a Request is able to reject the Request
• User who recieved a Request is able to confirm and send crypto in response to the Request
• User responding to a Request is able to change the amount of the Request (optional)
• User responding to a Request is able to update the Request memo (optional)

Link to FIO App

Alternatively to Native Integration, the application may link the user to to the FIO App, a comprehensive website to register and manage FIO Handles and many other functionality related to FIO Protocol.

For additional information, see FIO App.