​
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

​
customer
object
required

Customer information object

​
amount
integer
required

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

  • Minimum: 100

  • Maximum: Currency-specific limits apply

​
currency
string
required

Three-letter currency code (e.g., NGN, USD)

​
description
string
required

Payment description or purpose

​
direction
string
default:"incoming"
required

Payment direction. Use “incoming” for receiving payments.

​
payment_method
object
required
{
  "type": "bank_account"
}
​
reference
string
required

Your unique reference for this payment

  • Must be unique across all payments

  • Alphanumeric characters only

​
metadata
object
required

Additional payment information

​
Example Request

curl -X POST "https://api.spendjuice.com/payment-sessions" \
-H "Authorization: Bearer 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"
        }
    },
    "description": "Order Payment",
    "currency": "NGN",
    "amount": 100000,
    "direction": "incoming",
    "payment_method": {
        "type": "bank_account"
    },
    "reference": "ord_xyz_123",
    "metadata": {
        "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",
      "metadata": {
        "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?