​
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"
        }
    },
    "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?