Integration Guides - 88Pay Documentation

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

Each method requires specific parameters. See Payment Methods for details.

Send money to users or vendors:

Method	Code	Countries	Settlement Speed
Bank Transfer	`BANK_TRANSFER`	All 13	Same/next day
Cash Pickup	`CASH`	Selected	Instant (code-based)
Wallet Transfer	`WALLET`	Selected	Instant

Payouts require additional KYC verification and minimum balance thresholds.

Integration Patterns

By Use Case

E-commerce
SaaS/Subscriptions
Marketplace
Remittance

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

Recurring billing for subscriptions

    // Store customer payment method
    // (88Pay doesn't tokenize cards - use direct charges)
    
    async function chargeSubscription(subscription) {
      try {
        const payment = await createCharge({
          amount: subscription.plan.price,
          customer_id: subscription.user_id,
          description: `${subscription.plan.name} - ${month}`,
          // ... other params
        });
        
        await sendPaymentEmail(subscription.user, payment.urlCheckout);
      } catch (error) {
        await handleFailedPayment(subscription);
      }
    }

Key considerations:

Notify users before charging
Implement grace periods for failed payments
Offer payment method updates

Multi-vendor platform with split payments

    // 1. Buyer pays full amount to platform
    const payment = await createCharge({
      amount: totalOrderValue,
      // ...
    });
    
    // 2. On webhook confirmation, distribute to sellers
    if (webhook.status === 'COMPLETED') {
      for (const seller of order.sellers) {
        await createPayout({
          amount: seller.earnings,
          recipient: seller.bankAccount,
          // ...
        });
      }
    }

Key considerations:

Hold funds until delivery confirmation
Handle refunds and disputes
Track seller settlements

Cross-border money transfers

    // 1. Sender pays in origin country
    const collection = await createCharge({
      amount: sendAmount,
      country: senderCountry,
      currency: senderCurrency
    });
    
    // 2. Convert and disburse in destination
    const payout = await createPayout({
      amount: receiveAmount,
      country: recipientCountry,
      currency: recipientCurrency,
      recipient: recipientDetails
    });

Key considerations:

Display exchange rates and fees upfront
Provide tracking for sender/recipient
Comply with AML/KYC regulations

Development Checklist

Track your integration progress:

1. Setup (Day 1)

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)

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

Estimated time: 8-16 hours

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

Estimated time: 4-8 hours

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

Estimated time: 4-6 hours

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	✅

Complete API Reference →

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

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

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

Symptoms:

Payments complete but no webhook arrives
Webhook endpoint returns errors

Checklist:

Verify URL is publicly accessible (not localhost)
Check endpoint returns 200 OK within 5 seconds
Validate webhook signature (see Webhooks Guide)
Check server logs for incoming POST requests
Use webhook.site to debug payloads

Token keeps expiring

Symptoms:

Frequent 401 errors
Need to re-authenticate often

Solutions:

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)

Symptoms:

429 Too Many Requests responses
API rejecting legitimate requests

Solutions:

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

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:

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

Core Integration

Advanced

​Complete Integration Roadmap

​Implementation Path

​Core Guides

​Essential Implementation

API Credentials

Generate Tokens

Create Operations

Webhooks

Balance Inquiry

​Advanced Topics

Error Handling

Rate Limits

Security

​Payment Methods Reference

​Integration Patterns

​By Use Case

​Development Checklist

​Quick Reference

​Essential Endpoints

​Transaction States

​Standard Headers

​Testing Resources

Test Cards

Webhook Tester

Postman Collection

Error Simulator

​Common Issues & Solutions

​Support & Resources

API Documentation

Error Codes

Best Practices

Discord Community

Email Support

Status Page

​Start Integrating

Get API Credentials

Complete Integration Roadmap

Implementation Path

Core Guides

Essential Implementation

Advanced Topics

Payment Methods Reference

Integration Patterns

By Use Case

Development Checklist

Quick Reference

Essential Endpoints

Transaction States

Standard Headers

Testing Resources

Common Issues & Solutions

Support & Resources

Start Integrating