​
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

USD/International

  • SWIFT transfers
  • ACH (US only)
  • Wire transfers
  • Processing time: 1-3 business days

​
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
Three-letter ISO currency code
  • Supported: NGN, USD, CAD
  • Must match payment method
  • Example: “USD”
​
customer
object
required
Customer information object
​
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
​
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"
            }
        ]
    }
}'

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

​

​
Processing Times

Transfer processing times vary by:
  • Bank type (local vs international)
  • Time of day
  • Transaction volume
  • Bank system availability
CurrencyTransfer TypeTypical Processing Time
NGNLocal1.5 - 10 minutes
USDACH1 - 3 business days
USDWireSame/Next business day
USDSWIFT3 - 5 business days

​
Error Handling

​
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

Need Help?