PayIn Module Overview

Cashela API – PayIn Module

Overview

The PayIn module enables your business to accept payments from customers globally through a unified API. Support multiple payment methods including credit/debit cards, bank transfers, mobile wallets, cash vouchers, and local payment networks.

Key Features:

Multi-currency support – Accept payments in 20+ currencies
Local payment methods – Reach more customers with region-specific options
Real-time processing – Instant payment confirmation for supported methods
Webhook notifications – Receive real-time updates on transaction status
Sandbox environment – Test integrations safely before going live
PCI-compliant infrastructure – Secure payment processing out of the box

This guide covers authentication, available endpoints, and best practices for integrating payment acceptance into your application.

Getting Started

Prerequisites

Before integrating the PayIn module, ensure you have:

A verified Cashela Business account
Completed KYC/AML documentation
Defined your use case and expected transaction volumes
A secure server environment with HTTPS support

1. Create Your Business Account

The Business Dashboard provides:

API credential management
Transaction monitoring and reporting
Webhook configuration
Settlement and reconciliation 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:

✅ Business use case evaluation
✅ KYC/AML documentation verification
✅ Transaction monitoring procedures
✅ Terms of service acceptance

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

API Capabilities

The PayIn API provides comprehensive functionality for payment processing:

Payment Processing

Create deposits – Initiate payment transactions with multiple methods
Query transaction status – Real-time status checking and updates
Retrieve payment methods – Discover available options per country/currency
Calculate exchange rates – Get live FX rates and fee estimates
Process refunds – Issue full or partial refunds programmatically

Data & Configuration

Country support – Query supported countries and their payment methods
Payment method details – Get required fields, validation rules, and capabilities
Currency information – Supported currencies and conversion rates
Fee calculation – Transparent pricing with no hidden fees

Integration Features

Webhook notifications – Real-time event delivery for status changes
Idempotency support – Safe retry logic for network failures
Sandbox testing – Complete test environment with simulated transactions
Redirect & iframe flows – Flexible payment UI integration options

Authentication

All PayIn 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

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 transactions
Simulated payment flows and responses
Test webhook deliveries
Separate credentials from production

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

Best Practice: Complete all integration testing in sandbox before requesting production access. This ensures a smooth go-live experience and reduces potential issues.

Next Steps

Quick Start Guide

Get Countries – Discover supported countries
Get Payment Methods – Query available payment options
Get Exchange Rates – Calculate fees and FX rates
Create Deposit – Initiate your first payment
Webhooks – Set up real-time notifications

Support & Resources

Developer Support

Email: 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 PayIn API version is v1. All endpoints are prefixed with /api/v1/pay-in/.

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.