Receiving Payments

Easily receive payments from your wallet users with a simple, secure process.

When integrating payment processing into your Mini App within Speed Wallet, it is crucial to ensure that all payment prompts direct users to complete transactions through the Speed Wallet exclusively. While Mini Apps are permitted to use external services or providers to accept payments (i.e., the payment receiver can be any service), the sender must always be Speed Wallet. This approach guarantees a secure, seamless, and compliant payment experience within the Speed Wallet ecosystem.

Key Requirements

Mandatory Payment Prompt via Speed Wallet:

Mini Apps can generate payment requests through external services, but when displaying a payment prompt (e.g., showing a QR code or payment link), the user must be guided to complete the payment using Speed Wallet only.

Compliance and Security:

Any attempt to allow external wallet payments directly from the Mini App will result in app rejection or suspension from the Speed Wallet App Store. The payment initiation must always invoke Speed Wallet, ensuring a controlled and secure transaction flow.

Implementation Steps

Method 1: Payment Request via the JSON

The Mini App will send a JSON payload, enabling Speed to recognize that the payment is requested from the wallet user.

Step 1: Integrate the Payment Initiation Script

The following script must be included in your Mini App to prompt Speed Wallet as the payment method whenever a user needs to complete a transaction. The script supports Android, iOS, and web environments:

if (window) {
    if (window.Android) {
        window.Android.postMessage(data);
    } else if (window.webkit?.messageHandlers?.iosInterface) {
        window.webkit.messageHandlers.iosInterface.postMessage(data);
    } else if (window.parent) {
        window.parent.postMessage(data, "*");
    } else {
        window.postMessage(data, "*");
    }
}

How the Script Works:

For Android Users: The script uses window.Android.postMessage to automatically open Speed Wallet for payment processing.

For iOS Users: Utilizes window.webkit.messageHandlers.iosInterface.postMessage to interact with Speed Wallet on iOS devices.

For Web and Other Platforms: Falls back to window.parent.postMessage or window.postMessage to maintain broad compatibility.

Important: Ensure the data object is a stringified JSON using JSON.stringify(data) before passing it to the postMessage method.

Step 2: Prepare the Payment Request JSON Object

When requesting a payment from a user, construct the following JSON object containing all the necessary transaction details:

{
  "version": "2022-10-15",
  "account_id": "acct_xxxxxxxxxx",
  "data": {
    "amount": 450,
    "currency": "USD",
    "target_currency": "SATS",
    "deposit_address": "lnbc1xxxxxxxxxxxxx",
    "note": "Payment for Game Credits"
  }
}

Explanation of Key Parameters:

Parameter	Description	Requirement
version	API version to maintain compatibility with Speed Wallet. Always use "2022-10-15".	Required
account_id	The Speed Wallet account ID of the sender. This ID is included in the Mini App URL.	Required
amount	The exact payment amount expected from the user.	Required
currency	Base currency code (USD, EUR, BTC). Defaults to SATS for Lightning Network payments.	Required
target_currency	The cryptocurrency to receive payments (SATS or USDT).	Required
deposit_address	Provide the external service’s payment address or invoice. This can be an LN address, LN invoice, LNURL, or Bitcoin/USDT address.	Required
note	Optional transaction details (e.g., “Payment for Game Credits”).	Optional

Method 2 - Generating a Payment Request via QR Code

If your Mini App needs a payment from the user, you can generate a QR code with the deposit address (LN invoice, LN address, BTC address, or USDT address) and embed the amount in it.

• In these situations, Speed scans the displayed QR code to provide customers with a seamless payment option.

• If the screen contains moving elements (e.g., a counter), the QR code may not be recognized due to an unsuccessful screen scan. Additionally, if the QR code does not contain a valid address, the customer will not see the prompt to complete the transaction.

• Once the QR is successfully scanned, it is checked that the amount is embedded with the address or not.

• If the amount is not embedded, the user will be prompted to enter it before proceeding.

• Once the address and amount are confirmed, Speed seamlessly takes over to complete the payment using its smooth UI.

Method 3: Generating a Payment Request via Copyable address

• If your app provides a valid deposit address, Speed will detect and process it when copied. If the address is valid, Speed will scan it. If not, the text will be copied, but Speed won’t scan it.

• If an amount is embedded within the address, Speed will automatically recognize it.

• If the amount is not embedded, the user will be prompted to enter the amount before proceeding.

• Once the address and amount are confirmed, Speed seamlessly takes over to complete the payment using its smooth UI.

Note: Speed recommends using only one of the three methods—JSON, QR code, or a copyable address—at a time, as they cannot be combined.

Step-by-Step Payment Flow in Your Mini App

• Initiate Payment Request:

  When the user initiates a payment-related action, such as purchasing credits or making a donation, your app generates the payment request using one of the specified methods: JSON, a scannable QR code, or a copyable address.
• Display Payment Prompt:

  Display a payment amount with " Pay " button within the Mini App. Ensure that the prompt is designed to guide the user to complete the transaction using Speed Wallet.

• Trigger Speed Wallet for Payment:

  No matter which method you choose—JSON, QR code, or a copyable address—the payment will be processed through Speed Wallet. If using JSON, be sure to include the script!

• Complete the Transaction:

  The user approves the transaction within Speed Wallet.

  The payment is processed, and the funds are sent to the deposit address specified by the external service provider

• Post-Transaction Handling:

  Your Mini App receives a transaction status update (success or failure) from your payment provider. Provide visual feedback to the user, such as updating the app’s UI with purchased credits or displaying a success message. Note that Speed wallet do not provide any webhook or prompt of payment success or failure to mini app.

Best Practices

User Guidance:

• Clearly instruct users to use Speed Wallet to complete payments. Do not provide any alternative payment methods.

• Add a call-to-action like “Pay via Speed Wallet” to avoid confusion.

Validation and Security:

• Validate all input fields and ensure the deposit_address, account_id, and amount are accurately configured.

• Always use HTTPS to secure communication between your Mini App and Speed Wallet.

Error Handling:

• Implement robust error handling for scenarios like insufficient balance, payment timeouts, or user cancellations.

• Display clear error messages and provide options to retry or contact support.

Testing Before Go-Live:

• Test all payment scenarios in the Speed Wallet with live payments. We do not provide testnet payments in Mini-apps.

• Simulate successful and failed payments to ensure a robust user experience.

Optimizing User Experience:

• Use clear prompts and guidance throughout the payment process.

• Provide visual cues (e.g., loading spinners) during transaction processing.

Example Payment Flow

Scenario: User purchases game credits via external payment service, paying only through Speed Wallet

1. Trigger Payment: The user selects “Buy Credits” in the Mini App.

   

2. Generate Payment Request: The Mini App constructs a JSON payment request object with all necessary parameters, including the amount, currency, deposit address, and a transaction note.

3. Send Payment Request to Speed Wallet: The Mini App uses the integration script to post this data to Speed Wallet

   

4. Prompt in Speed Wallet: The Speed Wallet app opens automatically, presenting the user with a payment confirmation screen. The user can see the transaction details, including the amount, payment method, and recipient information.

   

5. User Confirmation: The user clicks “Confirm” within the Speed Wallet interface to authorize the payment.

6. Transaction Processing: Speed Wallet securely processes the transaction. The payment is sent to the specified deposit address (which could belong to an external service, but the payment is initiated through Speed Wallet).

7. Transaction Completion: Once the transaction is complete, your external service sends a confirmation back to the Mini App. The Mini App updates the UI to reflect the successful purchase, such as adding game credits to the user’s account.

8. Feedback to the User: The Mini App displays a success message, such as “Your game credits have been added successfully!”.

   

Key Highlights

1. The user never interacts with external wallets; the entire payment experience is contained within Speed Wallet.

2. The Mini App directly prompts Speed Wallet to initiate the payment, ensuring compliance and security.

3. The “Buy Credits” button seamlessly triggers the payment process, avoiding additional steps like scanning a QR code or entering payment details manually.

This streamlined approach not only enhances security and compliance but also offers a smooth and intuitive payment experience for Speed Wallet users.