Skip to main content

​
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. Confirm the charge
  4. Check transfer limits for your account tier in our Overview

​
Charge Endpoint

GET /payouts/Charge

​
Request Parameters

​
amount
string
required
Amount to charge
​
Currency
string
required
Cyrrency to charge e.g (USD,NGN,CAD)
​
Currency rail
string
required
Cyrrency rail to use e.g (USD,NGN,CAD)

​
Response

{
  "data": {
    "can_perform": true,
    "fee": {
      "amount": 0,
      "currency": "string"
    },
    "reason": "string"
  }
}

​
\

Payout Endpoint
POST /payouts

​
Request Parameters

Transfer amount in minor units (e.g., cents, kobo)
​
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
​
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
​
fee_charged_to
string
Must be one of: sender, recipient
Default: sender

​
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",
  "fee_charged_to": "sender"
}

​
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",
  "fee_charged_to": "sender"
}

​
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

Need Help?

For additional assistance: