Complete Integration Roadmap
These guides provide everything you need to integrate 88Pay, from basic setup to advanced features. Follow them sequentially for a smooth implementation.First time here? Complete Getting Started before diving into these guides.
Implementation Path
API Credentials
Obtain and secure your authentication keysGet Credentials →
Token Generation
Implement authentication and token managementGenerate Tokens →
Process Transactions
Create payments, cashouts, and transfersCreate Operations →
Webhook Integration
Receive real-time transaction updatesSetup Webhooks →
Balance Management
Monitor funds and settlementsCheck Balance →
Core Guides
Essential Implementation
API Credentials
Obtain, store, and rotate your keys securely
Generate Tokens
Implement JWT authentication with caching
Create Operations
Process all transaction types (payin/payout)
Webhooks
Handle real-time notifications securely
Balance Inquiry
Query merchant balance and transaction history
Advanced Topics
Error Handling
Retry logic and graceful degradation
Rate Limits
Optimize requests and avoid throttling
Security
PCI compliance and best practices
Payment Methods Reference
- PAYIN (Collect)
- PAYOUT (Disburse)
Accept payments from customers:
| Method | Code | Countries | Typical Confirmation |
|---|---|---|---|
| Cards (Visa/MC/Amex) | CARDS | All 13 | Instant |
| Bank Transfer | BANK_TRANSFER | All 13 | 1-3 business days |
| Cash (OXXO, Baloto, etc.) | CASH | All 13 | Up to 72 hours |
| Nequi | NEQUI | Colombia | Instant |
| Daviplata | DAVIPLATA | Colombia | Instant |
| PayPal | PAYPAL | Global | Instant |
| USDT (TRC20/ERC20) | USDT | Global | ~10 minutes |
Integration Patterns
By Use Case
- E-commerce
- SaaS/Subscriptions
- Marketplace
- Remittance
Online store checkout integrationKey considerations:
- Show payment status in order history
- Handle abandoned carts (webhook timeout)
- Support multiple currencies per country
Development Checklist
Track your integration progress:1. Setup (Day 1)
1. Setup (Day 1)
Account & Environment
- Create 88Pay account
- Upload KYC documents
- Receive document approval
- Copy sandbox credentials
- Set environment variables
- Test API connectivity
2. Core Integration (Days 2-3)
2. Core Integration (Days 2-3)
Backend Implementation
- Implement token generation with caching
- Create payment endpoint
- Set up webhook receiver
- Validate webhook signatures
- Handle transaction states
- Add error handling and logging
3. Testing (Day 4)
3. Testing (Day 4)
Validation
- Test successful payment flows
- Test declined/failed scenarios
- Verify webhook delivery
- Test token expiration handling
- Simulate rate limit scenarios
- Test all payment methods
4. Production (Day 5)
4. Production (Day 5)
Go-Live Preparation
- Request production credentials
- Update environment variables
- Configure production webhook URL
- Enable monitoring/alerts (Sentry, etc.)
- Document integration for team
- Conduct final end-to-end test
- Train support staff
Quick Reference
Essential Endpoints
| Endpoint | Method | Purpose | Auth Required |
|---|---|---|---|
/api/auth/token | POST | Generate JWT | API Key only |
/api/transactions/charges | POST | Create card/wallet payment | ✅ |
/api/transactions/cash | POST | Create cash voucher | ✅ |
/api/transactions/cashout-bank-transfer | POST | Create bank payout | ✅ |
/api/transactions/{reference} | GET | Get transaction status | ✅ |
/api/balance | POST | Check merchant balance | ✅ |
Transaction States
| Status | Description | Next Action |
|---|---|---|
PENDING | Payment initiated, awaiting user action | Wait for webhook |
COMPLETED | Successfully processed | Fulfill order |
REJECTED | Failed, declined, or expired | Notify user, offer retry |
Standard Headers
Testing Resources
Test Cards
Sandbox card numbers for different scenarios
Webhook Tester
Debug webhook payloads (external tool)
Postman Collection
Pre-configured API requests
Error Simulator
Test error handling
Common Issues & Solutions
Webhook not receiving notifications
Webhook not receiving notifications
Symptoms:
- Payments complete but no webhook arrives
- Webhook endpoint returns errors
- Verify URL is publicly accessible (not localhost)
- Check endpoint returns
200 OKwithin 5 seconds - Validate webhook signature (see Webhooks Guide)
- Check server logs for incoming POST requests
- Use webhook.site to debug payloads
Token keeps expiring
Token keeps expiring
Symptoms:
- Frequent 401 errors
- Need to re-authenticate often
- Implement token caching (50-second TTL)
- Check system clock is synchronized (NTP)
- Don’t share tokens across requests (use per-request generation or cache)
- See Token Management
Rate limit errors (429)
Rate limit errors (429)
Symptoms:
429 Too Many Requestsresponses- API rejecting legitimate requests
- Implement exponential backoff (1s, 2s, 4s, 8s…)
- Cache tokens (reduces token endpoint calls)
- Batch operations where possible
- See Rate Limits Guide
Payment stuck in PENDING
Payment stuck in PENDING
Symptoms:
- Transaction never reaches COMPLETED or REJECTED
- Customer completed payment but status unchanged
- Bank transfers: Can take 1-3 business days
- Cash payments: Up to 72 hours for customer to pay
- Crypto: Network confirmations needed (~10 min for USDT)
- Query transaction status:
GET /api/transactions/{reference} - Check webhook logs for missed notifications
- Set reasonable timeout expectations per method
Support & Resources
API Documentation
Technical specs for all endpoints
Error Codes
Complete error reference
Best Practices
Optimization tips and patterns
Discord Community
Connect with other developers
Email Support
Direct help from our team
Status Page
API uptime and incidents
Start Integrating
Get API Credentials
Begin with obtaining your authentication keys

