Skip to content

ONRAMP-PROVIDER-TESTING.md

Latest commit

 

History

History
248 lines (167 loc) · 13.4 KB

ONRAMP-PROVIDER-TESTING.md

File metadata and controls

248 lines (167 loc) · 13.4 KB
Raw

On-Ramp Provider Manual Testing Guide

This guide covers how to manually test the on-ramp providers (Transak and MoonPay) in the staging environment. It outlines the staging setup, how to locate and use provider-specific test data, the UX flow for each provider, and a general framework for testing other providers.

Table of Contents

Overview

The on-ramp flow in MetaMask Mobile allows you to buy crypto using fiat payment methods. There are two provider integration types:

Type Description Providers
Native In-app KYC/OTP flow — checkout is handled entirely inside the app Transak
Aggregator Opens the provider's widget in an in-app browser (WebView) MoonPay

All manual staging tests should be run against a non-production build of the app. Non-production builds automatically target MetaMask's staging (UAT) Ramps backend, which connects to each provider's own staging environment.

Important: Do not use real payment credentials. All testing should use test card numbers and staging accounts provided by each provider.

Prerequisites

Before testing, confirm the following:

  • You are using a non-production build of the app (debug, QA, or RC build targeting staging)

  • The following remote feature flags are active on your build:

    Flag Purpose
    rampsUnifiedBuyV1 Enables the Buy button entry point
    rampsUnifiedBuyV2 Enables the V2 provider/quote flow
    depositConfig Required for the Transak native (deposit) flow

    If the Buy button is missing, these flags are likely inactive on your build. Check with the team or enable them via a local override.

  • Your device's region is supported. The staging environment is confirmed to work for:

    • United States (California)
    • France
    • Spain
    • Saint Lucia

Understanding Provider Types

The flow you experience after selecting a quote depends on the provider type:

  • Native — Everything happens in-app. You complete KYC, OTP verification, and order submission entirely within MetaMask without opening a browser. (Transak)
  • Aggregator — The app opens the provider's checkout widget in an in-app browser (WebView). You complete the entire payment experience inside their widget. (MoonPay)

This matters for testing because the steps, required test data, and observable behavior differ between the two.

How to Find Provider Test Data

Each provider maintains a separate staging or sandbox environment with test credentials. Below is a general guide for what you need and where to find it.

What "test data" means for on-ramp providers

  • Staging account — an account you register with the provider's developer portal, scoped to their sandbox environment
  • Test card numbers — Visa/Mastercard numbers that trigger success, decline, or 3DS challenge scenarios without a real charge
  • Test identity data — name, address, phone, and email you use for KYC screens (staging providers typically accept any valid-format data)
  • OTP bypass — some providers accept a static code (e.g., 000000) in their sandbox instead of a real SMS/email OTP
  • Provider API key — required for some native flows; you can find this in the depositConfig feature flag or the provider's developer dashboard

Where to get it

Provider Where to look
Transak Transak Staging Documentation — refer to their documentation for staging test credentials.
MoonPay MoonPay Staging Documentation — refer to their test documentation for sandbox credentials.
Any provider Check the provider's official developer documentation for a "sandbox," "test environment," or "testing" section. Most will list test Visa/Mastercard numbers for common scenarios.

Tip: When testing a new provider for the first time, confirm whether they have a sandbox environment (isolated test data) vs. a staging environment (shared with QA). Some providers have both. Always use the most isolated environment available.

UX Flow — Getting to Buy

All on-ramp tests start from the same entry point regardless of provider:

  1. Open the app and log in
  2. From the Wallet screen, tap the Buy button in the action bar
  3. The Fund sheet appears — tap Buy
  4. The Token Select screen appears — select the token you want to buy (e.g., ETH)
  5. The app detects your region and fetches available quotes
  6. The Build Quote screen shows the available quote — review the amount, fee, and provider name
    • From this screen you can change the payment type (e.g., debit/credit card, Apple Pay) and switch between available providers
    • In staging, all valid providers will have (Staging) appended to their name (e.g., "Transak (Staging)", "Moonpay (Staging)"). Only select providers with this suffix — any provider without it is not in the staging environment
  7. Tap Continue to proceed to the provider-specific checkout

Testing Transak (Native Flow)

Transak's integration runs entirely in-app — it is a native experience. No WebViews open; instead you move through each step as a native screen inside MetaMask.

Transak Test Data

You will need:

  • A Transak staging account registered at the Transak developer portal
  • The email address associated with that account (used for OTP)
  • A test card number from Transak's sandbox documentation
  • Test identity data for KYC fields (any valid-format name, address, and phone number)

Check Transak's sandbox docs for whether a static OTP bypass code is available. In their staging environment a fixed 6-digit code is sometimes accepted in place of a real email OTP.

Transak UX Walkthrough

After tapping Continue on the Build Quote screen:

  1. Verify Identity — You are shown Transak's KYC requirement screen; tap Continue
  2. Email entry — enter your Transak staging account email; tap Continue
  3. OTP entry — Transak sends a code to your email; enter it (or use the staging bypass code if available)
  4. Personal details — if this is your first time, you are prompted for name, address, and phone; fill in valid test data
  5. KYC confirmation — your identity status is verified and the flow proceeds automatically if approved
  6. Quote confirmation — you see the final breakdown: crypto amount, fiat total, and fees
  7. Order placement — confirm the order; it is submitted to Transak's staging environment
  8. Order details screen — you see a summary with token amount, total fiat, and fees
  9. Activity tab — your order appears under Transfers and transitions from Pending → Completed

What to verify:

  • OTP screen appears and accepts the staging code
  • KYC screen shows the correct status after identity check
  • Order details screen shows the correct token, amount, and provider name ("Transak (Staging)")
  • Order appears in the Activity tab
  • Order status reaches Completed

Testing MoonPay (Aggregator / WebView Flow)

MoonPay's integration opens their checkout widget in an in-app browser. You enter the flow from MetaMask and return to it automatically on completion — everything in between happens inside MoonPay's widget.

MoonPay Test Data

You will need:

  • A test card number from MoonPay's sandbox documentation
  • A test email for MoonPay account creation inside the widget (if prompted)
  • Any valid identity data if MoonPay's KYC flow is triggered during checkout

MoonPay's sandbox typically provides Visa and Mastercard numbers for success, decline, and 3DS challenge scenarios. Check their developer docs for the current list.

Important timing note: MoonPay's custom order ID expires after 60 seconds. Once the widget opens, complete the checkout flow without a long pause — if you leave the widget idle too long, the order may fail with an expiration error.

MoonPay UX Walkthrough

After tapping Continue on the Build Quote screen:

  1. In-app browser opens — MoonPay's checkout widget loads inside the app
  2. Widget checkout — inside the widget, you will:
    • Enter your payment card details (use a MoonPay staging test card)
    • Verify your email and create or log into a MoonPay account if prompted
    • Complete any KYC or identity steps required by MoonPay
    • Confirm the purchase
  3. Callback handled — on completion, MoonPay redirects you back to MetaMask automatically
  4. Order details screen — you see the order summary with token amount, fiat total, and provider name
  5. Activity tab — your order appears under Transfers and transitions from Pending → Completed

What to verify:

  • In-app browser opens and MoonPay widget loads correctly
  • Test card is accepted and payment completes within the widget
  • You are returned to the Order Details screen automatically after widget completion (no manual navigation needed)
  • Order details show the correct token, amount, and provider name ("Moonpay (Staging)")
  • Order appears in the Activity tab
  • Order status reaches Completed

Testing Other Providers

The on-ramp system supports multiple providers. When testing a provider not covered in this guide, use the following steps:

1. Confirm the provider is available in your region

The providers shown depend on your detected region. If the expected provider does not appear on the quote screen, confirm your device region is one the provider supports. You can change your region in system settings and relaunch the app.

2. Identify the flow type

Look at which screen appears after you tap Continue:

  • KYC / identity / OTP screens in-app → native flow (follow the same pattern as Transak)
  • In-app browser opens → aggregator flow (follow the same pattern as MoonPay)

3. Get staging credentials from the provider

Follow the same approach described in How to Find Provider Test Data:

  • Register for a sandbox account at the provider's developer portal
  • Collect test card numbers for success and failure scenarios
  • Gather test identity data if KYC is required
  • Confirm whether OTP has a bypass in their sandbox

4. Run through the same verification checklist

Regardless of provider, verify:

  • Provider name appears correctly on the Build Quote and Order Details screens
  • Checkout completes without errors using your test credentials
  • Order Details screen shows the correct token, amounts, and fees
  • Order appears in the Activity tab under Transfers
  • Order status reaches Completed

Troubleshooting

Buy button is not visible Confirm rampsUnifiedBuyV1 and rampsUnifiedBuyV2 feature flags are active on your build. These are required for the Buy entry point to appear.

No providers or quotes returned Your detected region may not be supported. Verify your device's region is set to a supported country (US, France, Spain, or Saint Lucia) and relaunch the app.

Transak KYC flow fails or loops Verify you are using a registered Transak staging account email. If the OTP is not arriving, check whether Transak's sandbox has a bypass code in their documentation.

MoonPay widget fails to load or returns an error The order ID has a 60-second expiration. If you delayed starting the widget after the quote was fetched, go back and start the flow again. Also confirm MoonPay's sandbox environment is accessible from your network.

Order stuck in Pending and never reaches Completed This typically means the provider's staging environment has not confirmed the order. Wait a few minutes and pull to refresh in the Activity tab. If it does not resolve, check whether the staging provider processed the transaction on their side.

Wrong provider shown or preferred provider not auto-selected Provider selection is based on your most recent order history. To test a specific provider, clear your order history from app state or use a fresh wallet fixture.