​
Overview

Initiate bank transfers from your Juicyway balance to bank accounts. This endpoint supports both domestic and international transfers with real-time rate conversion where applicable.

Before initiating a transfer:

  1. Ensure sufficient balance in the source currency
  2. Verify beneficiary account details
  3. Check transfer limits for your account tier in our Overview

​
Endpoint

POST /payouts

​
Request Parameters

​
amount
integer
required

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

​
beneficiary_id
string
required

Unique identifier of a saved beneficiary

  • Must be a valid beneficiary ID
  • Alternative to providing full beneficiary details
​
beneficiary_type
string
required

Type of beneficiary account

  • Must be “bank_account”
​
description
string
required

Purpose or description of the transfer

  • Maximum length: 200 characters
​
destination_currency
string
required

Currency code for the destination account

  • Supported: NGN, USD, CAD
​
pin
string
required

Transfer authorization PIN

  • 6 digits
  • Required for security
​
reference
string
required

Your unique reference for this transfer

  • Must be unique across all transfers
  • Used for idempotency
​
source_currency
string
required

Currency to debit from your balance

  • Must match destination_currency for local transfers
  • Rate conversion applies for cross-currency transfers

​
Request Examples

​
Local Bank Transfer (NGN)

{
  "amount": 100000,
  "beneficiary_id": "juice-payout-5d906f6d-933b-4de9-927f-c7522823f5ec",
  "beneficiary_type": "bank_account",
  "description": "Vendor Payment",
  "destination_currency": "NGN",
  "pin": "123456",
  "reference": "pmt_vendor_123",
  "source_currency": "NGN"
}

​
International Transfer (USD)

{
  "amount": 50000,
  "beneficiary_id": "us_ben_789xyz",
  "beneficiary_type": "bank_account",
  "description": "International Payment",
  "destination_currency": "USD",
  "pin": "123456",
  "reference": "intl_pmt_456",
  "source_currency": "NGN"
}

​
Error Handling

​
insufficient_funds
error

Balance too low for transfer

  • Status code: 400
  • Check available balance
  • Consider exchange rates for international transfers
​
invalid_beneficiary
error

Invalid or inactive beneficiary

  • Status code: 400
  • Verify beneficiary_id
  • Check account status
​
transfer_limit_exceeded
error

Transfer exceeds account limits

  • Status code: 400
  • Review transfer limits
  • Contact support for limit increases

​
Best Practices

  1. Idempotency

    • Use unique references
    • Handle duplicate requests
    • Store transfer IDs

  2. Validation

    • Verify account details
    • Check currency support
    • Validate amounts

  3. Monitoring

    • Implement webhook handling
    • Track transfer status
    • Log all attempts

  4. Security

    • Use transfer PINs
    • Implement 2FA where available
    • Monitor for suspicious patterns

Next Steps

List Nigerian BanksInitiate a Stablecoin Transfer