Wallet Transfers

Overview

Wallet-to-Wallet Transfers are the core of HOST Pay’s peer-to-peer capabilities. They allow for instant movement of funds between any two wallets managed by the same application with zero latency.

Key Features

Instant Settlement: Funds are moved between wallets as soon as the request is processed.
Multiple Identifiers: Recipient identification can be done via their unique username, phone_number, or email.
Atomic Transactions: Transfers are atomic; either both wallets are updated, or neither is.
Custom Metadata: Attach descriptions and metadata to each transfer for record-keeping.

The Transfer Flow

To perform a transfer, use the Wallet Transfer endpoint.

Step 1: Identify the Sender

The sender_wallet_id is required. Ensure the sender has a sufficient balance, including any applicable fees.

Step 2: Identify the Recipient

The recipient can be identified using a single string recipient_identifier. The system will search for a match in this order:

Username
Phone Number (E.164 format recommended)
Email Address

Step 3: Specify the Amount

The amount must be in the application’s base currency (e.g., USD or SLE — whichever your application is configured for). Internal transfers never involve currency conversion. For more on how currencies work, see the Currency & Conversions guide.

Fees

The platform allows you to configure a Transfer Fee percentage. This fee is automatically deducted from the sender’s wallet in addition to the transfer amount.

[!NOTE] If a sender attempts to transfer 100 units and your fee is 1%, the sender must have at least 101 units available in their wallet’s base currency.

Implementation Example

JavaScript

const options = {
  method: 'POST',
  headers: {
    'api-key': 'YOUR_API_KEY',
    'secret-key': 'YOUR_SECRET_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    sender_wallet_id: 'wall_sender_123',
    recipient_identifier: '+23279123456',
    amount: 50.00,
    description: "Dinner split"
  })
};

fetch('https://hpay-api.host-sl.com/api/v1/transactions/wallet/transfer/', options)
  .then(response => response.json())
  .then(data => console.log('Transfer complete:', data));

Security Considerations

Server-to-Server: Always perform transfers from your backend. Never expose your secret-key to the frontend.
Wallet Locking: The system handles concurrent transactions by locking wallets during the transfer process to prevent double spending.
Enabled Status: Both the sender and recipient wallets must be in an active state for the transfer to succeed.

Escrow Control

Hold funds until conditions are met

Webhooks

Listen for transfer events

Get Started

Guides

Overview

Key Features

The Transfer Flow

Step 1: Identify the Sender

Step 2: Identify the Recipient

Step 3: Specify the Amount

Fees

Implementation Example

Security Considerations

Escrow Control

Webhooks

​Overview

​Key Features

​The Transfer Flow

​Step 1: Identify the Sender

​Step 2: Identify the Recipient

​Step 3: Specify the Amount

​Fees

​Implementation Example

​Security Considerations

​Related Topics

Escrow Control

Webhooks

Overview

Key Features

The Transfer Flow

Step 1: Identify the Sender

Step 2: Identify the Recipient

Step 3: Specify the Amount

Fees

Implementation Example

Security Considerations

Related Topics