PayOut Module Overview

Cashela API – PayOut Module

Overview

The PayOut module enables your business to send funds to beneficiaries worldwide through a unified API. Support multiple payout methods including bank transfers, mobile wallets, cash pickup locations, and local payment networks.

Key Features:

Global coverage – Send money to 100+ countries
Multiple payout methods – Bank accounts, wallets, cash pickup, and more
Competitive FX rates – Transparent pricing with locked rates
Fast processing – Real-time and same-day payout options available
Compliance built-in – KYC/AML checks integrated into the flow
Webhook notifications – Real-time status updates for all transactions
Sandbox environment – Test integrations safely before going live

This guide covers authentication, quotation creation, transaction processing, and best practices for integrating global payouts into your application.

Getting Started

Prerequisites

Before integrating the PayOut module, ensure you have:

A verified Cashela Business account
Completed KYC/AML documentation
Defined your payout use case and compliance requirements
A secure server environment with HTTPS support
Adequate funding in your Cashela business wallet

1. Create Your Business Account

The Business Dashboard provides:

API credential management
Payout transaction monitoring and reporting
Webhook configuration
Balance management and funding
Beneficiary management tools
Sandbox and production environment access

2. Generate API Credentials

Once logged into your dashboard:

Navigate to Settings → API Credentials
Generate your Business Key (public identifier) and Business Secret (private key)
Configure IP allowlist for API access security
Set up your webhook endpoint URL
Obtain sandbox credentials for testing

Security Requirements:

✅ Mandatory IP allowlisting for all API requests
✅ HTTPS-only endpoints (TLS 1.2 or higher)
✅ Basic Authentication with Business Key + Secret
✅ Keep your Business Secret secure – never expose it in client-side code or public repositories
✅ Rotate credentials regularly (recommended every 90 days)

Important: Treat your API credentials like passwords. If you believe your credentials have been compromised, revoke them immediately through the dashboard and generate new ones.

3. Integration Review Process

Before receiving production credentials, Cashela conducts a technical and compliance review:

Technical Review:

✅ Webhook endpoint validation (signature verification, 2xx responses)
✅ Idempotency implementation check
✅ Error handling and retry logic
✅ Transaction reconciliation process
✅ Security best practices (HTTPS, credential storage)

Compliance Review:

✅ Payout use case evaluation
✅ KYC/AML documentation verification
✅ Transaction monitoring procedures
✅ Sanctions screening implementation
✅ Terms of service acceptance

Timeline: Reviews typically complete within 3-5 business days after submission.

API Capabilities

The PayOut API provides comprehensive functionality for global money transfers:

Quotation & Pricing

Create quotations – Get locked FX rates and fee estimates
Calculate costs – Transparent pricing with no hidden fees
Rate locking – Lock rates for up to 60 minutes
Multiple currencies – Support for 50+ currency pairs

Transaction Management

Send money – Initiate payouts to beneficiaries worldwide
Track status – Real-time transaction status and updates
Transaction history – Query past payouts and their details
Cancel transactions – Cancel pending payouts when allowed

Configuration & Discovery

Country support – Query supported destination countries
Payout services – Discover available payout methods per country
Payer networks – Get available payer/provider options
Required fields – Dynamic field requirements per service

Compliance & Security

Beneficiary validation – Verify recipient details before sending
AML screening – Built-in compliance checks
Webhook notifications – Real-time event delivery for status changes
Idempotency support – Safe retry logic for network failures

Authentication

All PayOut API requests require HTTP Basic Authentication using your business credentials.

Authentication Method

Scheme: HTTP Basic Auth
Username: Your business_key
Password: Your business_secret

Required Headers

Every API request must include these headers:

Authorization: Basic <base64_encoded_credentials>
Content-Type: application/json
Accept: application/json
Idempotency-Key: <uuid-v4>     # Required for POST requests

Example: Encoding Credentials

Format: base64(business_key:business_secret)

Example in different languages:

# Bash
echo -n "your_business_key:your_business_secret" | base64

// JavaScript (Node.js)
const credentials = Buffer.from('your_business_key:your_business_secret').toString('base64');
const authHeader = `Basic ${credentials}`;

# Python
import base64
credentials = base64.b64encode(b'your_business_key:your_business_secret').decode('ascii')
auth_header = f'Basic {credentials}'

// PHP
$credentials = base64_encode('your_business_key:your_business_secret');
$authHeader = 'Basic ' . $credentials;

Authentication Errors

HTTP Status	Error Code	Description
401	`UNAUTHORIZED`	Invalid or missing credentials
403	`FORBIDDEN`	Valid credentials but IP not allowlisted
403	`FORBIDDEN`	API access disabled for your account
403	`INSUFFICIENT_FUNDS`	Account balance too low for this transaction

Security Note: Never include your Business Secret in client-side code, mobile apps, or version control systems. Always make API calls from your secure backend server.

API Environments

Cashela provides two distinct environments for development and production use:

Sandbox Environment

Base URL: https://sandbox-api.cashela.com

Use for development and testing
No real money transfers
Simulated payout flows and responses
Test webhook deliveries
Separate credentials from production
Test all payer networks and countries

Production Environment

Base URL: https://api.cashela.com

Live transactions with real money
Requires completed compliance review
Production credentials issued after approval
Full monitoring and support
Real-time processing and settlements

Best Practice: Complete all integration testing in sandbox before requesting production access. Test edge cases, error scenarios, and webhook handling thoroughly.

Payout Flow

The typical payout flow consists of three main steps:

1. Discovery Phase

graph LR
    A[Get Countries] --> B[Get Services]
    B --> C[Get Payers]

Query supported countries
Discover available payout services
Get payer/provider options

2. Quotation Phase

graph LR
    A[Create Quotation] --> B[Review Rates & Fees]
    B --> C[Lock Rate - 60min]

Create quotation with source/destination amounts
Receive locked FX rate and fee breakdown
Rate valid for up to 60 minutes

3. Execution Phase

graph LR
    A[Create Transaction] --> B[Processing]
    B --> C[Webhook Updates]
    C --> D[Completed]

Submit transaction with beneficiary details
Monitor status via webhooks
Receive completion confirmation

Next Steps

Quick Start Guide

Get Countries – Discover supported destination countries
Get Services – Query available payout methods
Get Payers – View payer/provider networks
Create Quotation – Generate FX quote with locked rates
Create Transaction – Initiate your first payout

Support & Resources

Developer Support

Email: api-support@cashela.com
Documentation: https://docs.cashela.com
Status Page: https://status.cashela.com
Response Time: Within 24 hours for technical inquiries

Additional Resources

API Changelog – Stay updated on new features and changes
Postman Collection – Ready-to-use API requests
Code Examples – Sample implementations in multiple languages
Integration Checklist – Ensure production readiness

Rate Limits

To ensure platform stability, the following rate limits apply:

Environment	Requests per Second	Requests per Hour
Sandbox	10	1,000
Production	50	10,000

Rate Limit Headers:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 1640995200

When rate limited, the API returns HTTP 429 Too Many Requests. Implement exponential backoff with jitter when retrying rate-limited requests.

API Versioning

The current PayOut API version is v1. All endpoints are prefixed with /api/v1/pay-out/.

Version Format: Date-based (YYYY-MM-DD)
Current Version: 2025-08-01
Compatibility: Breaking changes are introduced in new major versions only

We maintain backward compatibility within the same major version. When we introduce breaking changes, we’ll:

Announce the new version 90 days in advance
Provide migration guides and tools
Support the previous version for at least 12 months

To stay informed about API updates, subscribe to our developer newsletter.