Not intended to be interpreted as Database Model
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
Record events associated to Orders and Payments
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”
Payment notification received, e.g. “Stripe payment notification received (TX: 3213123131231, Status: Pending)”
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
User FIODashboard GeeTest FIOChain
@Starter(User)
"{Confirmation}" = User->FIODashboard.FreeFIOAddress() {
"Solved" = User->GeeTest.Captcha()
FIODashboard.CreateOrder(amount_usdc=0,amount_fio=0)
"Registered" = FIODashboard->FIOChain.Register()
FIODashboard.UpdateOrder()
} |
Create Order
Auto-generate order ID (6 alphanumeric, e.g. ABC123)
Payment is not created as address is free
Execute on-chain action
On Success
Update Order as Success
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Success
On complete Purchase Error
Update Order as Purchase Error
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Purchase-Error
On Partial Success
Update Order as Partial Success
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Partial-Success
User FIODashboard FIOChain
@Starter(User)
"{Confirmation}" = User->FIODashboard.PayWithFIO() {
FIODashboard.CreateOrder(amount_usdc=123,amount_fio=456)
"Registered" = FIODashboard->FIOChain.Register()
FIODashboard.UpdateOrder()
} |
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 https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Success
On complete Purchase Error
Update Order as Purchase Error
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Purchase-Error
On Partial Success
Update Order as Partial Success
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Partial-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.
Payload spec: https://bitpay.com/docs/invoice-webhooks
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 https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Shopping+and+Checkout#Canceled
invalid
Set order status to Pending
Display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Shopping+and+Checkout#Pending
complete
Create Payment for amount received
Create Payment for amount of order
Execute on-chain action
On success
Update Order as 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
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
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 https://stripe.com/docs/payments/accept-a-payment?ui=elements
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 https://stripe.com/docs/webhooks
Payload spec: https://stripe.com/docs/api/events/object
Action based on status
canceled
Update Order as Cancelled and display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Cancelled
requires_payment_method
Update Order as Declined and display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Checkout#Purchase-Error-or-Declined
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 https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Success.1
On complete Purchase Error
Create Payment for amount of order back to User
Refund amount collected using https://stripe.com/docs/refunds#issuing
Create Payment for amount refunded
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 usinghttps://stripe.com/docs/refunds#issuing
Create Payment for amount refunded
Any other status
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
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
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:
Register 2+ years
First call is register_fio_domain
For each additional year execute renew_fio_domain
Renew 2+ years
For each year of renewal execute renew_fio_domain
On errors:
If first call fails, the entire item fails, https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/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
1st register_fio_domain is sucesful
2nd renew_fio_domain fails
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, https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Shopping+and+Checkout#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.
Item | On-chain call |
|---|---|
Register FIO Address | |
Register FIO Domain | |
Renew FIO Domain | |
Add bundles to FIO Address |