Rails Pay API — Rails Cloud

← All APIs · Auth Media Vault Messaging Location

Base URL

            https://pay.railscloud.co/api/v1
        

Authentication

All requests require your Developer API key in the Authorization header. User-scoped endpoints also need a session token obtained from the Rails Auth API.

# Developer API key (required on all requests)
Authorization: Bearer dk_live_your_api_key

# User session (for wallet & transfer operations)
X-Session-Token: usr_session_token_here

How Payments Work

Rails Pay provides multi-currency wallets with instant P2P transfers. Authenticate users via the Auth API, then use Pay for all financial operations.

1 Authenticate the user via the Auth API to get a session token

2 Wallets (USD, ZiG) are auto-created when a user registers

3 Estimate fees with POST /transfers/estimate before sending

4 Execute transfers instantly or send pending transfers to unregistered users

Quick Start

# Step 1: Check wallet balance
curl https://pay.railscloud.co/api/v1/wallets/USD/balance \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN"

# Response: {"data": {"currency": "USD", "balance": 1250.00, "available_balance": 1200.00, "held_balance": 50.00}}

# Step 2: Estimate the transfer
curl -X POST https://pay.railscloud.co/api/v1/transfers/estimate \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USD", "amount": 25.00, "recipient_phone": "+263771234567"}'

# Response: {"data": {"amount": 25.00, "fee": 0.50, "total": 25.50, "recipient_name": "John D."}}

# Step 3: Send money
curl -X POST https://pay.railscloud.co/api/v1/transfers \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USD", "amount": 25.00, "recipient_phone": "+263771234567", "note": "Lunch"}'

# Response: {"data": {"id": "txn_abc123", "type": "transfer", "amount": 25.00, "fee": 0.50, "status": "completed"}}

Endpoints

Wallets

GET /wallets List all wallets with balances

GET /wallets/{currency} Get wallet by currency (USD, ZIG)

GET /wallets/{currency}/balance Get balance only (lightweight)

Transfers

POST /transfers/estimate Estimate fees before sending

POST /transfers Send money to another user

Transaction History

GET /transactions List transactions (filterable, paginated)

GET /transactions/{id} Get transaction details

Pending Transfers

POST /pending-transfers Send to unregistered user

GET /pending-transfers List sent pending transfers

GET /pending-transfers/claimable Get incoming money to claim

POST /pending-transfers/claim Claim a pending transfer

GET /pending-transfers/{id} Get pending transfer details

POST /pending-transfers/{id}/cancel Cancel and refund a pending transfer

Example: Send to Unregistered User

# Send money to someone who hasn't signed up yet
curl -X POST https://pay.railscloud.co/api/v1/pending-transfers \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"currency": "USD", "amount": 50.00, "recipient_phone": "+263779876543", "note": "Welcome bonus"}'

# Response: {"data": {"id": "pt_xyz789", "status": "pending", "amount": 50.00, "expires_at": "..."}}

# Recipient signs up via Auth API, then claims the transfer
curl -X POST https://pay.railscloud.co/api/v1/pending-transfers/claim \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: RECIPIENT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"pending_transfer_id": "pt_xyz789"}'

# Response: {"data": {"id": "txn_def456", "type": "claim", "amount": 50.00, "status": "completed"}}

Pending transfers hold funds in the sender's wallet. If unclaimed, they expire and refund automatically.

Example: Query Transaction History

# Get recent USD transactions
curl "https://pay.railscloud.co/api/v1/transactions?currency=USD&type=transfer&per_page=20" \
  -H "Authorization: Bearer dk_live_your_key" \
  -H "X-Session-Token: ACCESS_TOKEN"

# Response: {"data": [{"id": "txn_abc123", "type": "transfer", "direction": "outgoing", "amount": 25.00, ...}]}

Rate Limits

Transfer operations Based on your tier (400-3,000 req/min)

Balance checks Based on your tier (400-3,000 req/min)

Transaction history Based on your tier (400-3,000 req/min)

Error Responses

All errors follow a standard format.

{
  "error": "insufficient_funds",
  "message": "Wallet balance too low for this transfer"
}

400 Insufficient funds or self-transfer attempted

401 Invalid or missing API key / session token

404 Wallet or transaction not found

409 Pending transfer already claimed

410 Pending transfer expired and refunded

429 Rate limit exceeded

Get Started with Rails Pay