Sending Payments

Quickly send payments to your wallet users with a seamless and secure process.

Speed Wallet offers a seamless, secure, and flexible process for sending payments directly to Mini App users. Whether distributing rewards, processing payouts, or offering incentives, payments can be sent directly to the user’s Lightning Network (LN) address, ensuring fast and low-cost transactions.

Currently, payments are exclusively supported through the LN address, with plans to expand support to BTC and USDT (ERC20, TRC20) addresses in the future.

Flexibility

Two Options for Sending Payments:

1. Using Speed Merchant and “Instant Send” API:

Speed provides a native “Instant Send” API through Speed Merchant, offering an integrated and streamlined approach to handle payments within the Speed ecosystem.

2. Using External Services:

Mini Apps are not required to use Speed Merchant exclusively. You can also integrate any external payment service that supports sending payments to an LN address. This offers flexibility to leverage existing payment infrastructure while maintaining compliance with Speed Wallet requirements.

How to Send Payments

1. Retrieve the User’s Payment Address from the URL

When a user opens your Mini App within Speed Wallet, the app URL contains essential data, including the user’s LN address. You can extract this address to facilitate payments through either Speed Merchant or an external payment service.

Currently, Speed only provides LN addresses and does not offer other address types.

Example Data Sharing URL:

https://subdomain.yourdomain.com?acct=acct_li8hh2xyRuSBWnE4&lang=en&bal_btc=87636&bal_usdt=1975.29&p_add=[e-mail]

• acct (Account ID): User’s Speed Wallet account ID (acct_li8hh2xyRuSBWnE4).

• lang (Language): User’s language preference (en).

• bal_btc (Bitcoin Balance): User’s BTC balance in Satoshis (87636 SATs).

• bal_usdt (USDT Balance): User’s USDT balance (1975.29 USDT).

• p_add (Lightning Address): User’s payment address ([e-mail]).

2. Choose Your Payment Service

Option 1: Using Speed Merchant API (Optional)

• The “Instant Send” API in Speed Merchant offers a native integration for sending payments to LN addresses.

• Ideal for developers seeking a fully integrated solution within the Speed ecosystem.

Option 2: Using External Payment Services

• You can use any external service that supports sending payments to LN addresses.

• Ensure the external service is secure and capable of processing Lightning Network transactions seamlessly.

3. Initiate the Payment to the LN Address

Regardless of the chosen service, follow these steps to process the payment:

1. Extract the LN Address: Use the p_add parameter from the Mini App URL ([e-mail]).

2. Set the Payment Amount: Define the amount in Satoshis (SATS) or the preferred cryptocurrency.

3. Add a Payment Note: Include a message for transaction context (e.g., “Reward for completing the task”).

4. Process the Payment: Initiate the transaction using your selected payment service, ensuring that the LN address is correctly formatted and validated.

Best Practices

Validation and Security:

• Validate LN Address: Always verify the p_add parameter before processing the payment.

• Check Account ID: Confirm that the account_id matches the intended recipient.

• Secure API Calls: Use HTTPS for all payment transactions, whether through Speed Merchant or an external service.

Payment Failures

To maintain a seamless user experience, it is crucial to handle payment failures effectively while sending the amount back to your mini app user/customer. Below are key scenarios to address:

1. Insufficient Balance (Critical Handling Required)🔴

If your Mini App sends funds to customers/users and does not have enough balance to process a transaction, ensure the system displays a clear and informative error message.

• Display a message like: "Withdrawal unavailable. Our app does not have sufficient funds to process this request at this moment. Please try again after sometime"

• This way, you can prevent users from initiating withdrawals when the app's available balance is below the requested amount.

2. Invalid Address Errors

Ensure that the Lightning Network (LN) address provided is valid before processing a transaction.

3. Transaction Timeouts

If a payment request times out due to network delays or other issues:

• Provide users with an option to retry the transaction.

• Display a message indicating the issue, such as "Transaction timed out. Please try again."

• If applicable, suggest alternative withdrawal methods.

By implementing these handling measures, you ensure a smooth withdrawal experience to your mini app users.

Provide User Feedback:

• Success Message: Notify the user once the payment is completed (e.g., “1000 SATs have been sent to your account!”).

• Failure Notification: Display clear error messages with guidance on next steps if the payment fails.

Future Roadmap

In addition to the current Lightning Network support, Speed Wallet will soon enable payments to:

• Bitcoin (BTC) On-Chain Addresses: Ideal for on-chain BTC transfers for higher-value transactions or when Lightning Network is not applicable.

• USDT Payments on Ethereum and Tron: The addition of ERC20 and TRC20 network support will allow for USDT transfers to a broader range of addresses.

This upcoming functionality will provide more versatility in how you send payments to Mini App users, enabling a wider variety of use cases and transaction methods.