Bank Transfer Initialization

Overview

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.

Supported Bank Transfer Types

NGN Transfers

All major Nigerian banks
Instant virtual account generation
Real-time transfer notifications
Processing time: 1.5 - 10 minutes

Initialize Transfer Payment

POST /payment-sessions

Request Parameters

amount

integer

required

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

Minimum: 100
Must be positive integer
Example: 10000 = $100.00 USD

currency

string

required

ISO currency code

Supported: NGN, USD, CAD, USDT, USDC
Must match payment method
Example: “USD”

customer

object

required

Customer information object

Show Customer Fields

string

required

Valid email address

first_name

string

required

Customer’s first name

last_name

string

required

Customer’s last name

phone_number

string

required

Phone number in E.164 format

billing_address

object

required

Billing address details

type

string

required

Must be of type business or individual

ip_address

string

required

Customer’s ip address

Must be ipv4 e.g 127.0.0.1

description

string

required

Payment description

Maximum length: 200 characters
Will appear on statements

reference

string

required

Unique transaction reference

Must be unique per transaction
Maximum length: 50 characters

payment_method

object

required

Payment method details

type

string

required

Must be of type: ""

order

object

required

Order information object

Show Order Fields

identifier

string

required

Unique identifier

items

object[]

required

Show Items Fields

name

string

required

type

string

required

type must be one of digital,physical

metadata

object

Optional additional data

Nested objects allowed

Example Request

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"
            }
        ]
    }
}'

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())

Success Response

{
  "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

Transaction Limits may vary based on

Account verification level.
Transaction history.

NGN Transfers

Minimum: ₦100
Maximum per transaction: ₦5,000,000

Processing Times

Transfer processing times vary by:

Bank type (local vs international)
Time of day
Transaction volume
Bank system availability

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

Error Handling

400 - Invalid Request

{
  "error": {
    "code": "invalid_request",
    "message": "Invalid parameters provided",
    "details": {
      "amount": ["Amount must be at least 100"]
    }
  }
}

422 - Validation Error

{
  "error": {
    "code": "validation_error",
    "message": "The request contains invalid parameters",
    "details": {
      "currency": ["Currency must be one of: NGN, USD"]
    }
  }
}

Best Practices

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
Webhook Integration
- Implement webhook handling for transfer status updates
- Process webhooks asynchronously
- Verify webhook signatures
Error Handling
- Implement proper retry logic
- Handle timeouts gracefully
- Log all errors with payment references
Customer Communication
- Display virtual account details clearly
- Show transfer instructions
- Set clear expiration times

Need Help?

Review the Error Handling Guide
Check our API Reference
Contact Support

​Overview

​Supported Bank Transfer Types

NGN Transfers

​Initialize Transfer Payment

​Request Parameters

​Example Request

​Success Response

​Transfer Limits

​

​Processing Times

​Error Handling

​Best Practices

Need Help?

Overview

Supported Bank Transfer Types

Initialize Transfer Payment

Request Parameters

Example Request

Success Response

Transfer Limits

Processing Times

Error Handling

Best Practices