Skip to main content

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

1

API Credentials

Obtain and secure your authentication keysGet Credentials →
2

Token Generation

Implement authentication and token managementGenerate Tokens →
3

Process Transactions

Create payments, cashouts, and transfersCreate Operations →
4

Webhook Integration

Receive real-time transaction updatesSetup Webhooks →
5

Balance Management

Monitor funds and settlementsCheck Balance →

Core Guides

Essential Implementation

Advanced Topics


Payment Methods Reference

Accept payments from customers:
MethodCodeCountriesTypical Confirmation
Cards (Visa/MC/Amex)CARDSAll 13Instant
Bank TransferBANK_TRANSFERAll 131-3 business days
Cash (OXXO, Baloto, etc.)CASHAll 13Up to 72 hours
NequiNEQUIColombiaInstant
DaviplataDAVIPLATAColombiaInstant
PayPalPAYPALGlobalInstant
USDT (TRC20/ERC20)USDTGlobal~10 minutes
Each method requires specific parameters. See Payment Methods for details.

Integration Patterns

By Use Case

Online store checkout integration
    // 1. Create charge on checkout
    const payment = await createCharge({
      amount: cart.total,
      currency: user.currency,
      description: `Order #${order.id}`,
      customer_id: user.id,
      return_url: `${baseUrl}/orders/${order.id}/confirmation`,
      notification_url: `${baseUrl}/webhooks/88pay`
    });
    
    // 2. Redirect to payment
    res.redirect(payment.urlCheckout);
    
    // 3. Webhook updates order status
Key considerations:
  • Show payment status in order history
  • Handle abandoned carts (webhook timeout)
  • Support multiple currencies per country

Development Checklist

Track your integration progress:
Account & Environment
  • Create 88Pay account
  • Upload KYC documents
  • Receive document approval
  • Copy sandbox credentials
  • Set environment variables
  • Test API connectivity
Estimated time: 2-4 hours (+ 24h approval wait)
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
Estimated time: 8-16 hours
Validation
  • Test successful payment flows
  • Test declined/failed scenarios
  • Verify webhook delivery
  • Test token expiration handling
  • Simulate rate limit scenarios
  • Test all payment methods
Estimated time: 4-8 hours
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
Estimated time: 4-6 hours

Quick Reference

Essential Endpoints

EndpointMethodPurposeAuth Required
/api/auth/tokenPOSTGenerate JWTAPI Key only
/api/transactions/chargesPOSTCreate card/wallet payment
/api/transactions/cashPOSTCreate cash voucher
/api/transactions/cashout-bank-transferPOSTCreate bank payout
/api/transactions/{reference}GETGet transaction status
/api/balancePOSTCheck merchant balance
Complete API Reference →

Transaction States

StatusDescriptionNext Action
PENDINGPayment initiated, awaiting user actionWait for webhook
COMPLETEDSuccessfully processedFulfill order
REJECTEDFailed, declined, or expiredNotify user, offer retry
All Status Codes →

Standard Headers

# Authentication endpoints
x-api-key: {your_api_key}
x-merchant-id: {your_merchant_id}

# All other endpoints
Authorization: Bearer {access_token}
x-session-id: {session_id}
Content-Type: application/json

Testing Resources


Common Issues & Solutions

Symptoms:
  • Payments complete but no webhook arrives
  • Webhook endpoint returns errors
Checklist:
  1. Verify URL is publicly accessible (not localhost)
  2. Check endpoint returns 200 OK within 5 seconds
  3. Validate webhook signature (see Webhooks Guide)
  4. Check server logs for incoming POST requests
  5. Use webhook.site to debug payloads
Symptoms:
  • Frequent 401 errors
  • Need to re-authenticate often
Solutions:
  1. Implement token caching (50-second TTL)
  2. Check system clock is synchronized (NTP)
  3. Don’t share tokens across requests (use per-request generation or cache)
  4. See Token Management
Symptoms:
  • 429 Too Many Requests responses
  • API rejecting legitimate requests
Solutions:
  1. Implement exponential backoff (1s, 2s, 4s, 8s…)
  2. Cache tokens (reduces token endpoint calls)
  3. Batch operations where possible
  4. See Rate Limits Guide
Symptoms:
  • Transaction never reaches COMPLETED or REJECTED
  • Customer completed payment but status unchanged
Explanations:
  • 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)
Actions:
  1. Query transaction status: GET /api/transactions/{reference}
  2. Check webhook logs for missed notifications
  3. Set reasonable timeout expectations per method

Support & Resources


Start Integrating

Get API Credentials

Begin with obtaining your authentication keys