> ## 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.

# Bank Transfer Initialization

> Accept bank transfer payments through virtual accounts for various currencies and banking systems. This guide covers the initialization process for bank transfer payments.

export const payment_method_0 = "bank_account"

## Overview

<Note>
  Bank transfers are asynchronous - after initialization, you'll receive a virtual account where the customer can deposit funds. Webhook notifications will inform you of the transfer status.
</Note>

### Supported Bank Transfer Types

<CardGroup cols={2}>
  <Card title="NGN Transfers" icon="naira-sign">
    * All major Nigerian banks
    * Instant virtual account generation
    * Real-time transfer notifications
    * Processing time: 1.5 - 10 minutes
  </Card>
</CardGroup>

## Initialize Transfer Payment

```bash theme={null}
POST /payment-sessions
```

### Request Parameters

<ParamField body="amount" type="integer" required>
  Payment amount in minor units (e.g., cents, kobo)

  * Minimum: 100

  * Must be positive integer

  * Example: 10000 = \$100.00 USD
</ParamField>

<ParamField body="currency" type="string" required>
  ISO currency code

  * Supported: NGN, USD, CAD, USDT, USDC

  * Must match payment method

  * Example: "USD"
</ParamField>

<ParamField body="customer" type="object" required>
  Customer information object

  <Expandable title="Customer Fields">
    <ParamField body="email" type="string" required>
      Valid email address
    </ParamField>

    <ParamField body="first_name" type="string" required>
      Customer's first name
    </ParamField>

    <ParamField body="last_name" type="string" required>
      Customer's last name
    </ParamField>

    <ParamField body="phone_number" type="string" required>
      Phone number in E.164 format
    </ParamField>

    <ParamField body="billing_address" type="object" required>
      Billing address details
    </ParamField>

    <ParamField body="type" type="string" required>
      Must be of type `business` or `individual`
    </ParamField>

    <ParamField body="ip_address" type="string" required>
      Customer's ip address

      * Must be ipv4 e.g 127.0.0.1
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="description" type="string" required>
  Payment description

  * Maximum length: 200 characters

  * Will appear on statements
</ParamField>

<ParamField body="reference" type="string" required>
  Unique transaction reference

  * Must be unique per transaction

  * Maximum length: 50 characters
</ParamField>

<ParamField body="payment_method" type="object" required>
  Payment method details

  <ParamField body="type" type="string" required>
    * Must be of type: "{payment_method_0}"
  </ParamField>
</ParamField>

<ParamField body="order" type="object" required>
  Order information object

  <Expandable title="Order Fields">
    <ParamField body="identifier" type="string" required>
      Unique identifier
    </ParamField>

    <ParamField body="items" type="object[]" required>
      <Expandable title="Items Fields">
        <ParamField type="string" body="name" required />

        <ParamField type="string" body="type" required>
          type must be one of digital,physical
        </ParamField>
      </Expandable>
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="metadata" type="object">
  Optional additional data

  * Nested objects allowed
</ParamField>

### Example Request

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST "https://api.spendjuice.com/payment-sessions" \
  -H "Authorization:  YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
      "customer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "+2348000000000",
          "billing_address": {
              "line1": "123 Main St",
              "line2": "Suite 456",
              "city": "Ikoyi",
              "state": "LA",
              "country": "NG",
              "zip_code": "12345"
          },
          "ip_address": "127.0.0.1"
      },
      "description": "Order Payment",
      "currency": "NGN",
      "amount": 100000,
      "direction": "incoming",
      "payment_method": {
          "type": "bank_account"
      },
      "reference": "ord_xyz_123",
      "order": {
          "identifier": "ORD12345",
          "items": [
              {
                  "name": "Product A",
                  "type": "digital"
              }
          ]
      }
  }'
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.spendjuice.com/payment-sessions"
  headers = {
      "Authorization": " YOUR_API_KEY",
      "Content-Type": "application/json"
  }
  data = {
      "customer": {
          "first_name": "John",
          "last_name": "Doe",
          "email": "john.doe@example.com",
          "phone_number": "+2348000000000",
          "billing_address": {
              "line1": "123 Main St",
              "line2": "Suite 456",
              "city": "Ikoyi",
              "state": "LA",
              "country": "NG",
              "zip_code": "12345"
          },
          "ip_address": "127.0.0.1"
      },
      "description": "Order Payment",
      "currency": "NGN",
      "amount": 100000,
      "direction": "incoming",
      "payment_method": {
          "type": "bank_account"
      },
      "reference": "ord_xyz_123",
      "order": {
        "identifier": "ORD12345",
        "items": [
          {
            "name": "Product A",
            "type": "digital"
          }
        ]
      }
  }

  response = requests.post(url, json=data, headers=headers)
  print(response.json())
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "data": {
    "auth_type": null,
    "expires_at": "2024-03-01T08:43:08.110470Z",
    "links": {},
    "message": "Virtual account generated successfully",
    "payment": {
      "amount": 100000,
      "cancellation_reason": null,
      "correlation_id": "2549dcf4-d743-11ee-9d95-c6d49632367b",
      "currency": "NGN",
      "customer": {
        "billing_address": {
          "city": "Ikoyi",
          "country": "NG",
          "line1": "123 Main St",
          "line2": "Suite 456",
          "state": "LA",
          "zip_code": "12345"
        },
        "email": "john.doe@example.com",
        "first_name": "John",
        "id": "d05e51df-809e-498a-ac3f-7acfc0b5d35d",
        "last_name": "Doe",
        "phone_number": "+2348000000000"
      },
      "date": "2024-02-29T20:43:08.344264Z",
      "description": "Order Payment",
      "id": "2549c96c-d743-11ee-aa4d-c6d49632367b",
      "order": {
        "identifier": "ORD12345",
        "items": [
          {
            "name": "Product A",
            "type": "digital"
          }
        ]
      }
      "mode": "live",
      "payment_method": {
        "account_name": "JUICE PAYMENTS",
        "account_number": "1234567890",
        "bank_name": "Test Bank",
        "id": "5e21efda-c526-4057-92f6-1b94ee210b47",
        "type": "bank_account"
      },
      "reference": "ord_xyz_123",
      "status": "pending"
    },
    "status": "pending"
  }
}
```

## Transfer Limits

<Info>
  Transaction Limits may vary based on

  * Account verification level.
  * Transaction history.
</Info>

##

<AccordionGroup>
  <Accordion title="NGN Transfers">
    * Minimum: ₦100
    * Maximum per transaction: ₦5,000,000
  </Accordion>
</AccordionGroup>

## Processing Times

<Note>
  Transfer processing times vary by:

  * Bank type (local vs international)
  * Time of day
  * Transaction volume
  * Bank system availability
</Note>

| Currency | Transfer Type | Typical Processing Time |
| -------- | ------------- | ----------------------- |
| NGN      | Local         | 1.5 - 10 minutes        |

## Error Handling

<AccordionGroup>
  <Accordion title="400 - Invalid Request">
    ```json theme={null}
    {
      "error": {
        "code": "invalid_request",
        "message": "Invalid parameters provided",
        "details": {
          "amount": ["Amount must be at least 100"]
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="422 - Validation Error">
    ```json theme={null}
    {
      "error": {
        "code": "validation_error",
        "message": "The request contains invalid parameters",
        "details": {
          "currency": ["Currency must be one of: NGN, USD"]
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Best Practices

1. **Unique References**
   * Use unique, idempotent references for each transfer
   * Include your internal order ID in the reference
   * Store the payment ID returned in the response
2. **Webhook Integration**
   * Implement webhook handling for transfer status updates
   * Process webhooks asynchronously
   * Verify webhook signatures
3. **Error Handling**
   * Implement proper retry logic
   * Handle timeouts gracefully
   * Log all errors with payment references
4. **Customer Communication**
   * Display virtual account details clearly
   * Show transfer instructions
   * Set clear expiration times

<Card title="Need Help?">
  * Review the

    [Error Handling Guide](/errors)
  * Check our

    [API Reference](/api-reference/overview)
  * Contact

    [Support](mailto:support@juicyway.com)
</Card>