Skip to main content

Order custom ID

MetaMask requires an order ID of a purchase made on MetaMask, in order to track the status of the order. This order ID is included in the redirection URL at the end of the fiat on-ramp provider flow.

However, the redirection is not guaranteed to be executed successfully in the following cases:

  • The user's phone runs out of battery after making a purchase but before the redirection takes place.
  • Connectivity issues occur.
  • The operating system closes the mobile application.
  • The user opens the buy widget in another browser, and this browser doesn't support a redirection to a mobile app (Universal Links, Deep Links, etc.).

To ensure MetaMask always retrieves the order ID, on-ramp providers must implement a feature called order custom ID.

When this feature is enabled, the provider buy widget must accept an order ID defined by MetaMask. It allows MetaMask to store this information before any purchase is made, making the redirection URL optional in the end. MetaMask starts tracking the status of the order associated with this ID a few seconds after the widget is displayed to the user.

The redirection is still required to take place when possible; it allows the user to come back to MetaMask after a purchase. It also speeds up the tracking of the order for the user. Once the user is redirected to MetaMask, the order status is immediately queried.

The custom ID is never associated with a real order if the user doesn't place any order. Because of this, MetaMask must stop tracking it after some time. The provider must ensure the user can't make a purchase after MetaMask has stopped tracking the custom ID.

Technical specifications​

A custom ID generated by MetaMask is a random 64-character string using uppercase (A–Z) and lowercase (a–z) letters, and numbers (0–9). Custom IDs generated this way are considered statistically unique.

The provider must prevent displaying the widget if the custom ID has already been used in the past seven days. This means the provider must keep track of all the custom IDs used during this time.

MetaMask starts querying the order status 10 seconds after the widget is displayed. If possible, MetaMask tries to query again at a maximum frequency of one query every 10 seconds. When the app is closed or its scheduler is overloaded, this frequency decreases or some queries don't happen.

Workflow​

  1. The user selects Buy.
  2. MetaMask generates the custom ID.
  3. MetaMask sends the custom ID to the provider and displays the buy widget.

MetaMask polls the order associated with the custom ID information:

  • 10 seconds after the widget is displayed, and every 10 seconds afterwards.
  • When MetaMask detects a redirection URL call.
  • When MetaMask detects a browser being closed.

If the provider API returns a 5xx HTTP error, MetaMask retries with exponentially decreasing frequency (10s, 1min 40s, 16min 40s, 2h 45min, 1d 3h, etc.).

The polling completely stops when:

  • An order is retrieved and its status isn't PENDING (that is, COMPLETED, FAILED, CANCELED, or an unknown status).
  • No order is retrieved (404 HTTP status) and the custom ID is expired (one hour after it's generated).