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

  • Create Order

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

  • Payment is not created as there is no payment to Dashboard, it’s made on-chain directly

  • Execute on-chain action

  • On Success

    • Update Order as Success

    • Display

  • On complete Purchase Error

    • Update Order as Purchase Error

    • Display

  • On Partial Success

    • Update Order as Partial Success

    • Display

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

      • Update Order as Cancelled and display

    • invalid

      • Set order status to Pending

      • Display

    • complete

      • Create Payment for amount received

      • Create Payment for amount of order

      • Execute on-chain action

      • On success

        • Update Order as Success

        • Display

      • 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

        • 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

    • 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

See

  • Create Order as Pending

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

  • Create PaymentIntent with Stripe

    • API keys to be provided offline

    • amount - total amount of order in USDC

    • currency: 'usd'

    • automatic_payment_methods: {enabled: true}

  • Trigger stripe.confirmPayment

    • return_url - url of confirmation page

  • Await Webhook notification. See

    • Payload spec:

    • Action based on status

      • canceled

        • Update Order as Cancelled and display

      • requires_payment_method

        • Update Order as Declined and display

      • payment_intent.succeeded

        • Create Payment for amount received

        • Create Payment for amount of order

        • Execute on-chain action

        • On success

          • Update Order as Success

          • Display

        • On complete Purchase Error

          • Create Payment for amount of order back to User

          • Refund amount collected using

          • Create Payment for amount refunded

          • Display

          • Update Order as Purchase Error

        • On Partial Success

          • Create Payment for amount of failed items back to User

          • Refund amount collected for items which failed using

          • Create Payment for amount refunded

          • Display

      • Any other status

        • Display

    • 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% refund the purchase amount to the user and update Order as Purchase Error

Registering FCHs on private domain when not paid with FIO

  • If cart contains a FCH on a domain owned by the user check domain status (private/public)

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

    • Display error: “At this moment registration of FIO Cryptyo Handles on private domains is not supported. We are working hard to add this capability to the Ledger’s FIO App.”

  • If the FCH being registered is on a private domain (domain registered in the same transaction will be private):

    • Have the user sign a transaction registering that FCH using pay with FIO functionality (PIN code will be required immediately after they click Purchase)

      • 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

      • 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, 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, error messages is shown and appropriate form of payment refund is processed (Stripe, Bitpay)

    • Analytics and Reporting

      • There is no change to analytics or reporting

      • Register/renewal for 1 year shows up the same as multi-year, except the value will be higher.

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