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

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

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

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"
        }
    },
    "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.

NGN Transfers

USD Transfers

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
USD	ACH	1 - 3 business days
USD	Wire	Same/Next business day
USD	SWIFT	3 - 5 business days

Error Handling

400 - Invalid Request

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

On this page

Overview
Supported Bank Transfer Types
Initialize Transfer Payment
Request Parameters
Example Request
Success Response
Transfer Limits
Processing Times
Error Handling
Best Practices

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

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

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"
        }
    },
    "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.

NGN Transfers

USD Transfers

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
USD	ACH	1 - 3 business days
USD	Wire	Same/Next business day
USD	SWIFT	3 - 5 business days

Error Handling

400 - Invalid Request

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

On this page

Overview
Supported Bank Transfer Types
Initialize Transfer Payment
Request Parameters
Example Request
Success Response
Transfer Limits
Processing Times
Error Handling
Best Practices

Bank Transfer Initialization

Overview

Supported Bank Transfer Types

NGN Transfers

USD/International

Initialize Transfer Payment

Request Parameters

Example Request

Success Response

Transfer Limits

Processing Times

Error Handling

Best Practices

Need Help?

exchange

payouts

payments

Bank Transfer Initialization

Overview

Supported Bank Transfer Types

NGN Transfers

USD/International

Initialize Transfer Payment

Request Parameters

Example Request

Success Response

Transfer Limits

Processing Times

Error Handling

Best Practices

Need Help?

​Overview

​Supported Bank Transfer Types

NGN Transfers

USD/International

​Initialize Transfer Payment

​Request Parameters

​Example Request

​Success Response

​Transfer Limits

​

​Processing Times

​Error Handling

​Best Practices

Need Help?

exchange

payouts

payments

​Overview

​Supported Bank Transfer Types

NGN Transfers

USD/International

​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

Overview

Supported Bank Transfer Types

Initialize Transfer Payment

Request Parameters

Example Request

Success Response

Transfer Limits

Processing Times

Error Handling

Best Practices