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:

Ensure sufficient balance in the source currency
Verify beneficiary account details
Confirm the charge
Check transfer limits for your account tier in our Overview

Charge Endpoint

GET /payouts/Charge

Request Parameters

string

required

Amount to charge

string

required

Cyrrency to charge e.g (USD,NGN,CAD)

string

required

Cyrrency rail to use e.g (USD,NGN,CAD)

Response

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

Request

\

Payout Endpoint

POST /payouts

Request Parameters

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

Must be within transfer limits
Minimum and maximum vary by currency

object

required

Beneficiary object

  "beneficiary": {
    "id": "",
    "type": ""
  }

string

Purpose or description of the transfer

Maximum length: 200 characters

string

required

Currency code for the destination account

Supported: NGN, USD, CAD

string

required

Your unique reference for this transfer

Must be unique across all transfers
Used for idempotency

string

required

Currency to debit from your balance

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

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

{
  "data": {
    "beneficiary": {
      "account_name": "ACME CORPORATION",
      "account_number": "0821081314",
      "account_type": "current",
      "bank_name": "ACCESS BANK",
      "id": "d8c0226b-048c-4c44-9606-a93333f56283",
      "type": "bank_account"
    },
    "beneficiary_type": "bank_account",
    "created_at": "2024-03-01T02:29:49Z",
    "destination_amount": 100000,
    "destination_currency": "NGN",
    "id": "93cf071e-d773-11ee-bf78-c6d49632367b",
    "source_amount": 100000,
    "source_currency": "NGN",
    "status": "pending",
    "updated_at": "2024-03-01T02:29:53Z"
  }
}

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

{
  "data": {
    "beneficiary": {
      "account_name": "Global Services LLC",
      "account_number": "12345678",
      "routing_number": "021000021",
      "bank_name": "CHASE",
      "id": "us_ben_789xyz",
      "type": "bank_account"
    },
    "beneficiary_type": "bank_account",
    "created_at": "2024-03-15T14:30:00Z",
    "destination_amount": 50000,
    "destination_currency": "USD",
    "id": "intl_tx_789abc",
    "source_amount": 45000000, // NGN equivalent
    "source_currency": "NGN",
    "status": "pending",
    "updated_at": "2024-03-15T14:30:00Z"
  }
}

Error Handling

error

Balance too low for transfer

Status code: 400
Check available balance
Consider exchange rates for international transfers

error

Invalid or inactive beneficiary

Status code: 400
Verify beneficiary_id
Check account status

error

Transfer exceeds account limits

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

Best Practices

Idempotency
- Use unique references
- Handle duplicate requests
- Store transfer IDs
Validation
- Verify account details
- Check currency support
- Validate amounts
Monitoring
- Implement webhook handling
- Track transfer status
- Log all attempts
Security
- Use transfer PINs
- Implement 2FA where available
- Monitor for suspicious patterns

Next Steps

Review Transfer Limits
Set up Webhook Handling for transfer status updates
Learn about Error Handling

Need Help?

For additional assistance:

Review our Error Handling Guide
Contact support@juicyway.com

Home

Customers

Payments

Payment Transactions

Transfers

Exchange

Wallet As A Service

Initiate Bank Transfer

Overview

Charge Endpoint

Request Parameters

Response

\

Request Parameters

Request Examples

Local Bank Transfer (NGN)

International Transfer (USD)

Error Handling

Best Practices

Next Steps

Need Help?

​Overview

​Charge Endpoint

​Request Parameters

​Response

​\

​Request Parameters

​Request Examples

​Local Bank Transfer (NGN)

​International Transfer (USD)

​Error Handling

​Best Practices

Next Steps

Need Help?

Overview

Charge Endpoint

Request Parameters

Response

\

Request Parameters

Request Examples

Local Bank Transfer (NGN)

International Transfer (USD)

Error Handling

Best Practices