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
Target FIO Public Key
Status
Created
Pending
Success
Partial Success
Purchase Error
Declined
Payment type
FIO Tokens
CoinPayments
Link to User
Links to Payments
Events
Record events associated to Orders and Payments
Orders
Order Created
Funds credited to Order, e.g. “CoinPayments payment 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. “CoinPayments payment notification received (TX: 3213123131231, Status: Pending)”
Payments
Depicts payment transactions executed against specific Order. This is akin to Registration site transaction.
Timestamp
Type
Coinpayments
Credit Card (future)
FIO Tokens
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 address is free
Execute using register_fio_address using designated account
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
Paid with FIO
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 register_fio_domain and/or register_fio_address for every item in cart
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
Paid with CoinPayments
Success
With Errors
Create Order as Pending
Auto-generate order ID (6 alphanumeric, e.g. ABC123)
Redirect in same window to https://www.coinpayments.net/index.php based on this spec and the following parameters:
cmd: _pay_simple
reset: 1
merchant: 3143e56ef04c6125c3a246c34b421fd7
currency: USDT
amountf: (total cart value in USDC)
item_name: “FIO Dashboard cart”
item_desc: “FIO Domains: (list comma delimited), FIO Crypto Handles: (list comma delimited)”
If length exceeds 125 character truncate rest and add “…”
Do not show FIO Domains label if no domains
Do not show Crypto Handles label if no domains
Examples
“FIO Domains: test, test1, test2; FIO Crypto Handles: example@test, example@test1”
“FIO Domains: test”
“FIO Crypto Handles: example@test, example@test1”
invoice: (shopping cart reference)
email: (Dashboard user’s email address)
success_url: (Link to Payment Progress Page - In Progress)
cancel_url: (Link to Payment Progress Page - Cancelled)
Await Webhook notification. See https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/501153808/Purchase#CoinPayments-Webhook
Payload spec: https://www.coinpayments.net/merchant-tools-ipn
Action based on status
< 0
Update Order as Cancelled and display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Cancelled
2 or >=100
Create Payment for amount received
Create Payment for amount of order
Execute register_fio_domain and/or register_fio_address for every item in cart using designated account
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
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
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% 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
Create Order as Pending
Auto-generate order ID (6 alphanumeric, e.g. ABC123)
Create
PaymentIntentwith StripeAPI keys to be provided offline
amount- total amount of order in USDCcurrency: '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
canceledUpdate Order as Cancelled and display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Dashboard+Checkout#Cancelled
requires_payment_methodUpdate Order as Declined and display https://fioprotocol.atlassian.net/wiki/spaces/DAO/pages/500793345/Checkout#Purchase-Error-or-Declined
payment_intent.succeededCreate Payment for amount received
Create Payment for amount of order
Execute register_fio_domain and/or register_fio_address for every item in cart using designated account
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
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_feeparameter to 125% of fee obtained from get_fee forregister_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_addressfeeIf just obtained
register_fio_addressis 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_addressIf transaction fails with
Insufficient funds to cover fee:re-check current
register_fio_addressfeeSend users the difference between new fee and number of tokens they received
Resubmit the transaction with higher fee