Purchase

Table of Contents

Purchase Entities

Not intended to be interpreted as Database Model

Orders

Depicts a shopping Cart and contains:

  • Timestamp

  • Items

    • item

    • description - e.g. domain name

    • type

      • FIO Domain

      • FIO Address

      • FIO Domain Renewal

      • Bundles

    • Amount in FIO

    • Amount in USDC

    • Executed to blockchain

      • True

      • False

    • Status

      • None

      • Success

      • Failed

  • Target FIO Public Key

  • Status

    • New

    • Pending

    • Success

    • Canceled

    • Partial Success

    • Failed

  • Payment type

    • FIO Tokens

    • Stripe

    • Bitpay

  • Link to User

  • Links to Payments

Events

Record events associated to Orders and Payments

Orders

  • Order Created

  • Funds credited to Order, e.g. “Stripepayment notification received (TX: 3213123131231, Status: Completed)”

  • Funds debited from Order, e.g. “Charge for pawel@hodl”

  • FIO Domain/Address registered on chain, e.g. “Registred pawel@hodl (FIO TX: kjdhakjdhkadhkajsdhkasjdhkasjhdkas)”

  • FIO Domain/Address registration error, e.g. “Failed to register pawel2@hodl (FIO error: "Insufficient funds")”

  • Funds credited to user, e.g. “Crediting FIO to user”

Payments

  • Payment notification received, e.g. “Stripe payment notification received (TX: 3213123131231, Status: Pending)”

Payments

Depicts payment transactions executed against specific Order. This is akin to Registration site transaction.

  • Timestamp

  • Type

    • FIO Tokens

    • Stripe

    • Bitpay

  • Currency

  • Amount

  • Amount in USDC

  • External transaction ID

  • Description

Cart Purchase Logic

Free

Paid with FIO

Paid with Bitpay

Success

 

  • Create Order as Pending

    • Auto-generate order ID (6 alphanumeric, e.g. ABC123)

  • Create Invoice via API

    • currency = USD

    • merchantName = “FIO Dashboard”

    • price = Total price of order

    • orderId = Order ID

    • notificationURL = webhook notification url

    • redirectURL = link to Order details where user will be redirected after payment

    • buyer

      • email = Email address of user

    • token = API token provided by Bitpay

  • Capture response

    • id

  • Trigger Modal Invoice

  • Await Webhook notification.

  • When received fetch invoice via API to ensure not spoofed

  • Action based on status

    • new/confirm

      • No action

    • paid

      • Set order status to Pending

      • User should stay on Invoice Modal

    • expired

    • invalid

    • complete

      • Create Payment for amount received

      • Create Payment for amount of order

      • Execute on-chain action

      • On success

      • On complete Purchase Error

        • Create Payment for amount of order back to User

        • Create Payment for amount of order Spent On FIO

        • Send FIO to User’s account

          • On Error Create Payment for amount of order back to User

        • Display Shopping and Checkout | Purchase Error

        • Update Order as Purchase Error

      • On Partial Success

        • Create Payment for amount of failed items back to User

        • Create Payment for amount of failed items Spent On FIO

        • Send FIO to User’s account

          • On Error Create Payment for amount of failed items back to User

        • Display Shopping and Checkout | Partial Success

    • Handling price changes

      • Preserve FIO pricing and USDC pricing for cart

      • When payment is received compare total price of cart when saved to what it is at the time when payment notification is received

        • If price deviation is +/- 25% from saved price do not alter pricing and execute transaction

        • If price deviation is more than +/- 25% reprice send FIO to User’s account at new rate of exchange

Paid with Stripe

See https://stripe.com/docs/payments/accept-a-payment?ui=elements

Registering Handles on private domains AND not paid with FIO

  • If cart contains a domain (meaning the domain is not yet registered) and a single handle(s) on that domain:

  • If cart contains multiple handles on a new domain or 1 or more handle on an existing private domain:

    • If owner wallet is a Ledger Wallet registration of FCH on private domain is not allowed

      • Display error: “At this moment registration of FIO Handles on private domains secured by Ledger device are only supported when paid for using FIO Tokens.”

    • Have the user sign a transaction registering that FCH using pay with FIO functionality

      • Set the max_fee parameter to 125% of fee obtained from get_fee for register_fio_address

    • Once payment is received (e.g. webhook notification from Stripe received):

      • If domain is being registered in the same purchase, register it first

        • If registration fails, automatically fail FCH registrations on that domain

        • Wait at least 5 seconds between registering the domain and first handle on that domain

      • Re-check current register_fio_address fee

        • If just obtained register_fio_address is more than the fee signed by user in the step above fail FCH registration

      • Send FIO Tokens to user in the amount of just obtained register_fio_address

        • If transaction fails with Insufficient funds to cover fee:

          • re-check current register_fio_address fee

          • Send users the difference between new fee and number of tokens they received

          • Resubmit the transaction with higher fee

Registering or renewing domains for multiple years

  • If cart contains a domain registration or renewal for more than 1 year, it will be captured as a single cart item, but needs to be executed sequentially as follows:

  • On errors:

    • If first call fails, the entire item fails, Shopping and Checkout | Purchase Error error message is shown and appropriate form of payment refund is processed (Stripe, Bitpay).

    • If 2nd or later call fails, the item needs to be modified as follows:

      • Original item is modified to reflect what was purchased

      • New item is added to reflect what fails

      • Example:

        • User wants to buy a domain for 3 years

        • Original item (“FIO Domain Registration - 3 years”) is modified to “FIO Domain Registration - 1 year” and marked as Success

        • New item is created: FIO Domain Renewal - 2 years and is marked Failed

        • The overall order is marked Partial Success, Shopping and Checkout | Partial Success error messages is shown and appropriate form of payment refund is processed (Stripe, Bitpay)

    • Analytics and Reporting

On-chain execution of cart items

Item

On-chain call

Item

On-chain call

Register FIO Address

register_fio_address

Register FIO Domain

register_fio_domain

Renew FIO Domain

renew_fio_domain

Add bundles to FIO Address

add_bundled_transactions