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

# Initiate Bank Transfer

> Send bank transfers to saved or new beneficiaries

## Overview

Initiate bank transfers from your Juicyway balance to bank accounts. This endpoint supports both domestic and international transfers with real-time rate conversion where applicable.

<Note>
  Before initiating a transfer:

  1. Ensure sufficient balance in the source currency
  2. Verify beneficiary account details
  3. Confirm the charge
  4. Check transfer limits for your account tier in our [Overview](/transfers/overview#processing-times)
</Note>

## Charge Endpoint

```bash theme={null}
GET /payouts/Charge
```

## Request Parameters

<ParamField body="amount" type="string" required>
  Amount to charge

  <ParamField body="Currency" type="string" required>
    Cyrrency to charge e.g (USD,NGN,CAD)

    <ParamField body="Currency rail" type="string" required>
      Cyrrency rail to use e.g (USD,NGN,CAD)

      ### Response

      <CodeGroup>
        ```json Response theme={null}
        {
          "data": {
            "can_perform": true,
            "fee": {
              "amount": 0,
              "currency": "string"
            },
            "reason": "string"
          }
        }
        ```

        `Request`
      </CodeGroup>

      # \\

      Payout Endpoint

      ```bash theme={null}
      POST /payouts
      ```

      ## Request Parameters

      Transfer amount in minor units (e.g., cents, kobo)

      * Must be within [transfer limits](/transfers/overview#processing-times)
      * Minimum and maximum vary by currency
    </ParamField>

    <ParamField body="beneficiary" type="object" required>
      Beneficiary object

      ```json theme={null}
        "beneficiary": {
          "id": "",
          "type": ""
        }
      ```
    </ParamField>

    <ParamField body="description" type="string">
      Purpose or description of the transfer

      * Maximum length: 200 characters
    </ParamField>

    <ParamField body="destination_currency" type="string" required>
      Currency code for the destination account

      * Supported: NGN, USD, CAD
    </ParamField>

    <ParamField body="reference" type="string" required>
      Your unique reference for this transfer

      * Must be unique across all transfers
      * Used for idempotency

      <ParamField body="source_currency" type="string" required>
        Currency to debit from your balance

        * Must match destination\_currency for local transfers
        * Rate conversion applies for cross-currency transfers
      </ParamField>
    </ParamField>

    <ParamField body="fee_charged_to" type="string">
      Must be one of: sender, recipient\
      Default: sender
    </ParamField>
  </ParamField>
</ParamField>

## Request Examples

### Local Bank Transfer (NGN)

<CodeGroup>
  ```json Request theme={null}
  {
    "amount": 100000,
    "beneficiary": {
      "id": "juice-payout-5d906f6d-933b-4de9-927f-c7522823f5ec",
      "type": "bank_account",
    },
    "description": "Vendor Payment",
    "destination_currency": "NGN",
    "pin": "123456",
    "reference": "pmt_vendor_123",
    "source_currency": "NGN",
    "fee_charged_to": "sender"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "beneficiary": {
        "account_name": "ACME CORPORATION",
        "account_number": "0821081314",
        "account_type": "current",
        "bank_name": "ACCESS BANK",
        "id": "d8c0226b-048c-4c44-9606-a93333f56283",
        "type": "bank_account"
      },
      "beneficiary_type": "bank_account",
      "created_at": "2024-03-01T02:29:49Z",
      "destination_amount": 100000,
      "destination_currency": "NGN",
      "id": "93cf071e-d773-11ee-bf78-c6d49632367b",
      "source_amount": 100000,
      "source_currency": "NGN",
      "status": "pending",
      "updated_at": "2024-03-01T02:29:53Z"
    }
  }
  ```
</CodeGroup>

### International Transfer (USD)

<CodeGroup>
  ```json Request theme={null}
  {
    "amount": 50000,
    "beneficiary": {
      "id": "us_ben_789xyz",
      "type": "bank_account"
    },
    "description": "International Payment",
    "destination_currency": "USD",
    "pin": "123456",
    "reference": "intl_pmt_456",
    "source_currency": "NGN",
    "fee_charged_to": "sender"
  }
  ```

  ```json Response theme={null}
  {
    "data": {
      "beneficiary": {
        "account_name": "Global Services LLC",
        "account_number": "12345678",
        "routing_number": "021000021",
        "bank_name": "CHASE",
        "id": "us_ben_789xyz",
        "type": "bank_account"
      },
      "beneficiary_type": "bank_account",
      "created_at": "2024-03-15T14:30:00Z",
      "destination_amount": 50000,
      "destination_currency": "USD",
      "id": "intl_tx_789abc",
      "source_amount": 45000000, // NGN equivalent
      "source_currency": "NGN",
      "status": "pending",
      "updated_at": "2024-03-15T14:30:00Z"
    }
  }
  ```
</CodeGroup>

## Error Handling

<ResponseField name="insufficient_funds" type="error">
  Balance too low for transfer

  * Status code: 400
  * Check available balance
  * Consider exchange rates for international transfers
</ResponseField>

<ResponseField name="invalid_beneficiary" type="error">
  Invalid or inactive beneficiary

  * Status code: 400
  * Verify beneficiary\_id
  * Check account status
</ResponseField>

<ResponseField name="transfer_limit_exceeded" type="error">
  Transfer exceeds account limits

  * Status code: 400
  * Review transfer limits
  * Contact support for limit increases
</ResponseField>

## Best Practices

1. **Idempotency**
   * Use unique references
   * Handle duplicate requests
   * Store transfer IDs
2. **Validation**
   * Verify account details
   * Check currency support
   * Validate amounts
3. **Monitoring**
   * Implement webhook handling
   * Track transfer status
   * Log all attempts
4. **Security**
   * Use transfer PINs
   * Implement 2FA where available
   * Monitor for suspicious patterns

<Card title="Next Steps">
  * Review [Transfer Limits](/transfers/overview#processing-times)
  * Set up [Webhook Handling](/webhooks) for transfer status updates
  * Learn about [Error Handling](/errors)
</Card>

<Card title="Need Help?">
  For additional assistance:

  * Review our [Error Handling Guide](/errors)
  * Contact [support@juicyway.com](mailto:support@juicyway.com)
</Card>