> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hifi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Split Payments

> Facilitate split payment services where a single payment is divided among multiple recipients. Perfect for splitting bills, shared expenses, or distributing funds to multiple stakeholders efficiently.

**🎯 What you'll build:** A split payment system where users deposit USD into a virtual account, funds convert to USDC, then split payments are distributed to multiple recipients through the use of batch transfers.

## Use Case Overview

This recipe demonstrates a split payment flow where:

* ✅ Users deposit USD into dedicated virtual accounts
* ✅ USD automatically converts to USDC stablecoin
* ✅ Payments are split among multiple recipients using batch transfers
* ✅ Operational overhead is minimized through automation

Common Split Payment Use Cases:

* **Paying multiple recipients at once** – Take funds from a single wallet and send payouts to several recipients in one batch instead of issuing individual transfers.
* **Sharing revenue between parties** – Distribute a single pool of funds across different stakeholders (for example, a primary recipient plus one or more collaborators).
* **Operational or treasury fan-out** – Move balance from a central wallet into multiple wallets (such as teams, regions, or projects) in a single operation.
* **Scheduled payout runs** – Periodically aggregate earnings and use a batch transfer to pay out all recipients for a given period in one shot.
* **Distributing rewards or incentives** – Send rewards, rebates, or incentive payments to many users at the same time from one funding source.

***

## What you'll build

Here's what we'll accomplish in this recipe:

1. **Add Virtual Account** - Set up account for collecting USD payments that convert to USDC
2. **Split Payments** - Execute on-demand split payments with batch transfers

**Payment Flow**

```
USD → User Bank Account → Virtual Account → USDC → Batch Transfer → Multiple Recipients
```

<Note>
  All examples in this guide use the sandbox environment. When you're ready for
  production, simply replace the sandbox URL with the production endpoint and
  use your production API keys.
</Note>

***

## Prerequisites

Before you begin, make sure you have:

**User A** – Individual user created and KYC submitted with `status = active`

For a complete guide on user onboarding, see:

* [Authentication Guide](/docs/api/authentication)
* [User Guide](/docs/users/overview)
* [KYC Guide](/docs/kyc)

***

## Add Virtual Account

The sender needs a **Virtual Account** for collecting the payment to be split. This is a bank account number automatically created by HIFI that users can deposit USD into. When fiat arrives, it's automatically converted to USDC and ready for distribution.

<Note>
  **Virtual Account for Split Payments:** Each virtual account comes with unique
  ACH/Wire/RTP details you can surface in your app. When deposits arrive, HIFI
  detects the funds and applies your conversion settings (e.g., USD → USDC). You
  can then use settlement rules for automatic splitting or batch transfers for
  on-demand splitting.
</Note>

<AccordionGroup>
  <Accordion title="Create Virtual Account">
    **Request:**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.hifibridge.com/v2/users/3b77cec8-1bb9-5ea0-91a1-e8c1411dd429/virtual-accounts \
      --header 'accept: application/json' \
      --header 'authorization: Bearer YOUR_API_KEY' \
      --header 'content-type: application/json' \
      --data '
    {
      "sourceCurrency": "usd",
      "destinationCurrency": "usdc",
      "destinationChain": "POLYGON"
    }
    '
    ```

    **Response:**

    ```json theme={null}
    {
      "id": "c48d1dd1-b5cd-5bc7-b85e-df1b0f17c1c8",
      "status": "activated",
      "provider": "CROSS_RIVER",
      "userId": "3b77cec8-1bb9-5ea0-91a1-e8c1411dd429",
      "source": {
        "paymentRails": ["ach", "wire", "rtp"],
        "currency": "usd"
      },
      "destination": {
        "chain": "POLYGON",
        "currency": "usdc",
        "walletAddress": "0x63dAbB631bcE6d6090A4e6c5c7aB20d3D853C338"
      },
      "depositInstructions": {
        "bankName": "Cross River Bank",
        "bankAddress": "885 Teaneck Road, Teaneck, NJ 07666",
        "beneficiary": {
          "name": "John Doe",
          "address": "123 Park Ave, Kansas City, KS, 10001, US"
        },
        "ach": {
          "routingNumber": "021214891",
          "accountNumber": "372232122120"
        },
        "wire": {
          "routingNumber": "021214891",
          "accountNumber": "372232122120"
        },
        "instruction": "Please deposit USD to the bank account provided. Ensure that the beneficiary name matches the account holder name provided, or the payment may be rejected."
      }
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Split Payments with Batch Transfers

Batch transfers let you manually initiate split payments with full control over amounts and recipients for each transaction. You decide when to split and can customize the distribution for each payment.

<Note>
  **When to Use Batch Transfers:** Use batch transfers when you need: -
  On-demand split payments that vary per transaction - Dynamic recipient lists
  that change based on the payment - Conditional logic before splitting (e.g.,
  verify amounts, check balances) - Bill payments where amounts differ each time

  * One-time or irregular split payments Perfect for bill payment services,
    dynamic revenue sharing, or variable expense splits.
</Note>

<AccordionGroup>
  <Accordion title="Create Batch Transfer">
    Create a batch transfer to split a payment among multiple recipients in a single transaction using the [Create Batch Transfer](https://docs.hifi.com/api-reference/crypto-transfer/create-batch-transfer) endpoint.

    In this example, we'll split a payment to three different recipients with 10 USDC each from the user's wallet.

    **Request:**

    ```bash theme={null}
    curl --request POST \
      --url https://sandbox.hifibridge.com/v2/wallets/transfers/batches \
      --header 'accept: application/json' \
      --header 'authorization: Bearer YOUR_API_KEY' \
      --header 'content-type: application/json' \
      --data '
    {
      "requestId": "b91772a6-f9c0-4479-a34c-c8723608d2e8",
      "currency": "usdc",
      "chain": "POLYGON",
      "source": {
        "userId": "3b77cec8-1bb9-5ea0-91a1-e8c1411dd429"
      },
      "destination": {
        "batch": [
          {
            "walletAddress": "0xA4C951a7ca4138220a9D4611e7A058d4673e14c3",
            "amount": "10"
          },
          {
            "walletAddress": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760",
            "amount": "10"
          },
          {
            "walletAddress": "0x8356d234077d4b7c71E35c95B075ed4ba5FF7681",
            "amount": "10"
          }
        ]
      },
      "requireApproval": false
    }
    '
    ```

    **Request Fields:**

    <ResponseField name="requestId" type="string" required>
      Unique identifier (UUID) for this batch transfer request to ensure
      idempotency.
    </ResponseField>

    <ResponseField name="currency" type="string" required>
      Cryptocurrency to transfer. Use `usdc` for USD Coin.
    </ResponseField>

    <ResponseField name="chain" type="string" required>
      Blockchain network for the transfer. Options: `POLYGON`, `ETHEREUM`
    </ResponseField>

    <ResponseField name="source" type="object" required>
      Source of the batch transfer (the user making the split payment).

      <Expandable title="properties">
        <ResponseField name="userId" type="string" required>
          The user ID sending the payments (split payment initiator's account)
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="destination" type="object" required>
      Destination configuration containing the batch of recipients.

      <Expandable title="properties">
        <ResponseField name="batch" type="array" required>
          Array of payment destinations. Each object specifies a wallet address and
          amount.

          <Expandable title="properties">
            <ResponseField name="walletAddress" type="string" required>
              Recipient's wallet address (recipient's crypto wallet)
            </ResponseField>

            <ResponseField name="amount" type="string" required>
              Amount to send to this recipient (in USDC)
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="requireApproval" type="boolean">
      Whether the batch transfer requires manual approval before execution. Set to
      `false` for automatic processing.
    </ResponseField>

    **Response:**

    ```json theme={null}
    {
      "id": "467e8eed-c6e2-4f78-9404-a82148c49e0e",
      "type": "WALLET.TRANSFER.BATCH",
      "status": "CREATED",
      "chain": "POLYGON",
      "currency": "usdc",
      "contractAddress": "0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582",
      "source": {
        "userId": "3b77cec8-1bb9-5ea0-91a1-e8c1411dd429",
        "walletAddress": "0x63dAbB631bcE6d6090A4e6c5c7aB20d3D853C338",
        "walletType": "INDIVIDUAL"
      },
      "destination": {
        "batch": [
          {
            "amount": "10",
            "walletAddress": "0xA4C951a7ca4138220a9D4611e7A058d4673e14c3"
          },
          {
            "amount": "10",
            "walletAddress": "0x0466DCD644Ae2Ee5d88CF0e1976c3ce237A0D760"
          },
          {
            "amount": "10",
            "walletAddress": "0x8356d234077d4b7c71E35c95B075ed4ba5FF7681"
          }
        ]
      },
      "receipt": {
        "transactionHash": null,
        "userOpHash": null
      }
    }
    ```

    ✅ **Batch transfer created!**

    **Response Fields:**

    <ResponseField name="id" type="string">
      Unique batch transfer ID. **Save this** to monitor the batch status and
      retrieve transaction details.
    </ResponseField>

    <ResponseField name="type" type="string">
      Transfer type. Always `WALLET.TRANSFER.BATCH` for batch transfers.
    </ResponseField>

    <ResponseField name="status" type="string">
      Current batch status. Starts as `CREATED`, then progresses through: -
      `CREATED` - Batch transfer initiated - `PENDING` - Being processed on
      blockchain - `COMPLETED` - All payments successfully delivered - `FAILED` -
      One or more payments failed (check individual statuses)
    </ResponseField>

    <ResponseField name="chain" type="string">
      Blockchain network where the transfer is being executed.
    </ResponseField>

    <ResponseField name="currency" type="string">
      Cryptocurrency being transferred.
    </ResponseField>

    <ResponseField name="contractAddress" type="string">
      Smart contract address handling the USDC transfers on the blockchain.
    </ResponseField>

    <ResponseField name="source" type="object">
      Source details showing the user's wallet information.

      <Expandable title="properties">
        <ResponseField name="userId" type="string">
          User ID of the person making the split payment
        </ResponseField>

        <ResponseField name="walletAddress" type="string">
          User's wallet address sending the payments
        </ResponseField>

        <ResponseField name="walletType" type="string">
          Type of wallet (e.g., "INDIVIDUAL")
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="destination" type="object">
      Destination details showing all recipients in the batch.

      <Expandable title="properties">
        <ResponseField name="batch" type="array">
          Array of all payment destinations with amounts

          <Expandable title="properties">
            <ResponseField name="amount" type="string">
              Amount sent to this recipient
            </ResponseField>

            <ResponseField name="walletAddress" type="string">
              Recipient's wallet address
            </ResponseField>
          </Expandable>
        </ResponseField>
      </Expandable>
    </ResponseField>

    <ResponseField name="receipt" type="object">
      Transaction receipt information.

      <Expandable title="properties">
        <ResponseField name="transactionHash" type="string">
          Blockchain transaction hash (populated when complete). Use this to verify
          the transaction on a blockchain explorer like Polygonscan.
        </ResponseField>

        <ResponseField name="userOpHash" type="string">
          User operation hash (for account abstraction wallets)
        </ResponseField>
      </Expandable>
    </ResponseField>

    **Understanding the Batch Transfer:**

    In this example:

    * **Source:** User's wallet (`0x63dA...C338`) with 30+ USDC available
    * **Batch:** 3 recipients receiving 10 USDC each
    * **Total:** 30 USDC distributed in a single blockchain transaction
    * **Cost Savings:** One transaction fee instead of three separate transactions

    <Info>
      **Monitoring Batch Transfers:** Subscribe to `WALLET.TRANSFER.BATCH.UPDATE`
      webhook events to receive real-time notifications as the batch progresses. You
      can also poll the [Retrieve Batch
      Transfer](https://docs.hifi.com/api-reference/crypto-transfer/retrieve-batch-transfer)
      endpoint to check individual payment statuses within the batch.
    </Info>

    For a complete guide on batch transfers including advanced features like approval workflows and error handling, see our [Batch Transfers Guide](/docs/features/batch-transfers).
  </Accordion>
</AccordionGroup>

***

## 🎉 Congratulations!

You've successfully built a split payment system! By following this recipe, you can now:

* ✅ Create virtual accounts for collecting payments with automatic conversion
* ✅ Execute batch transfers for on-demand split payments
* ✅ Reduce operational overhead with automated or consolidated transactions

### Next Steps

Ready to scale your split payment service? Here's what to explore next:

* **[Batch Transfers Guide](/docs/features/batch-transfers)** - Learn about batch transfers with approval workflows, failure handling, and advanced features
* **[Webhooks](/docs/webhooks)** - Set up real-time notifications for deposit detection, conversion completion, and split payment distribution
* **[Virtual Accounts Guide](/docs/virtual-accounts)** - Learn about monitoring deposits and handling multiple virtual accounts per user
* **[API Reference](https://docs.hifi.com/api-reference)** - Explore all available endpoints and parameters for advanced features