​
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) * Must be within transfer limits * Minimum and maximum vary by currency

​
beneficiary
object
required

Beneficiary object

  "beneficiary": {
    "id": "",
    "type": ""
  }
​
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",
    "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",
    "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