Integration

Integration Options

CloudBank offers multiple integration paths to fit your development needs and timeline. Choose the approach that works best for your use case.

Hosted Checkout (Recommended)

Our hosted checkout provides the fastest path to accepting payments. Perfect for most e-commerce and SaaS applications.

✅ Benefits

  • 5-minute setup: Create a checkout session and redirect users
  • Mobile optimized: Works seamlessly across all devices
  • All payment methods: Cards, mobile money, bank accounts included
  • Compliance handled: PCI DSS and local regulations managed for you
  • Conversion optimized: Tested UI patterns that maximize completion rates

🔧 Implementation

Code(bash)
 
# 1. Create checkout session
curl -X POST https://dev.api.cloudbank.fnstack.dev/v1/checkout/sessions \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": {"value": 10000, "currency": "XAF"},
    "external_id": "order_12345",
    "success_url": "https://yoursite.com/success",
    "cancel_url": "https://yoursite.com/cancel",
    "failure_url": "https://yoursite.com/error"
  }'

# 2. Redirect user to checkout_url from response

🎯 Best for:

  • E-commerce websites
  • SaaS billing pages
  • Event ticketing
  • Donation platforms
  • Quick prototypes

Payment Intents API

Build completely custom payment experiences with full control over the user interface and payment flow.

✅ Benefits

  • Full customization: Design your own payment forms and flows
  • Native experience: Keep users on your site/app throughout
  • Advanced workflows: Support complex business logic
  • Granular control: Manual confirmation, capture, and processing

🔧 Implementation

Code(javascript)
 
// 1. Create payment intent
const response = await fetch('/v1/payment_intents', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: {value: 10000, currency: 'XAF'},
    external_id: 'order_12345',
    payment_method_types: ['card', 'mobile_money']
  })
});

// 2. Confirm with payment method
await fetch(`/v1/payment_intents/${paymentIntentId}/confirm`, {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_test_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    payment_method: {
      type: 'mobile_money',
      phone_number: '+237xxxxxxxxx',
      mobile_money_provider: 'mtn_momo'
    }
  })
});

🎯 Best for:

  • Mobile applications
  • White-label solutions
  • Complex multi-step flows
  • Marketplaces
  • Subscription platforms

Framework Integrations

React/Next.js

Code(bash)
 
npm install @cloudbank/react
Code(tsx)
 
import { CloudBankProvider, CheckoutButton } from '@cloudbank/react';

function App() {
  return (
    <CloudBankProvider publishableKey="pk_test_...">
      <CheckoutButton
        amount={10000}
        currency="XAF"
        onSuccess={(session) => console.log('Payment successful!')}
        onError={(error) => console.log('Payment failed:', error)}
      >
        Pay 10,000 XAF
      </CheckoutButton>
    </CloudBankProvider>
  );
}

Node.js/Express

Code(bash)
 
npm install cloudbank
Code(javascript)
 
const cloudbank = require('cloudbank')('sk_test_...');

app.post('/create-checkout-session', async (req, res) => {
  const session = await cloudbank.checkout.sessions.create({
    amount: {value: 10000, currency: 'XAF'},
    external_id: `order_${Date.now()}`,
    success_url: 'https://yoursite.com/success',
    cancel_url: 'https://yoursite.com/cancel'
  });
  
  res.json({ checkout_url: session.checkout_url });
});

Python/Django

Code(bash)
 
pip install cloudbank
Code(python)
 
import cloudbank
cloudbank.api_key = "sk_test_..."

def create_checkout_session(request):
    session = cloudbank.checkout.Session.create(
        amount={'value': 10000, 'currency': 'XAF'},
        external_id=f"order_{int(time.time())}",
        success_url='https://yoursite.com/success',
        cancel_url='https://yoursite.com/cancel'
    )
    
    return JsonResponse({'checkout_url': session.checkout_url})

Webhooks Integration

Receive real-time notifications about payment events, account updates, and more.

Setup

  1. Configure endpoint in your CloudBank dashboard
  2. Verify signatures to ensure webhook authenticity
  3. Handle events idempotently
Code(javascript)
 
const crypto = require('crypto');

app.post('/webhook', express.raw({type: 'application/json'}), (req, res) => {
  const sig = req.headers['cloudbank-signature'];
  const endpointSecret = 'whsec_...';
  
  // Verify webhook signature
  const expectedSig = crypto
    .createHmac('sha256', endpointSecret)
    .update(req.body)
    .digest('hex');
    
  if (sig !== expectedSig) {
    return res.status(400).send('Invalid signature');
  }
  
  const event = JSON.parse(req.body);
  
  switch (event.type) {
    case 'payment.succeeded':
      handlePaymentSuccess(event.data);
      break;
    case 'payment.failed':
      handlePaymentFailure(event.data);
      break;
    default:
      console.log(`Unhandled event type: ${event.type}`);
  }
  
  res.json({received: true});
});

Event Types

  • payment.succeeded - Payment completed successfully
  • payment.failed - Payment failed or was declined
  • payment.processing - Payment is being processed
  • checkout.session.completed - Checkout session finished
  • account.balance.updated - Account balance changed

Testing & Development

Test Environment

Use our development environment for testing:

Code(bash)
 
# Development base URL
https://dev.api.cloudbank.fnstack.dev

# Test API keys (start with pk_test_ or sk_test_)
export CLOUDBANK_SECRET_KEY="sk_test_..."
export CLOUDBANK_PUBLISHABLE_KEY="pk_test_..."

Test Payment Methods

Test Cards:

  • Visa: 4242424242424242
  • Mastercard: 5555555555554444
  • Declined: 4000000000000002

Test Mobile Money:

  • MTN Mobile Money: +237600000001
  • Airtel Money: +237700000001

Webhook Testing

Use tools like ngrok to test webhooks locally:

Code(bash)
 
# Expose local server
ngrok http 3000

# Use the ngrok URL in your webhook settings
https://abc123.ngrok.io/webhook

Go Live Checklist

1. Switch to Live API Keys

Replace test keys with live keys from your CloudBank dashboard.

2. Update URLs

Change from development to production endpoints:

Code(bash)
 
# Production base URL
https://api.cloudbank.fnstack.dev

3. Webhook Configuration

  • Update webhook URLs to production endpoints
  • Verify webhook signature validation
  • Test error handling and retries

4. Security Review

  • ✅ API keys stored securely (environment variables)
  • ✅ Webhook signatures verified
  • ✅ HTTPS enabled on all endpoints
  • ✅ Rate limiting implemented
  • ✅ Error logging configured

5. Monitoring

  • Set up payment success/failure alerts
  • Monitor webhook delivery rates
  • Track API response times
  • Configure balance threshold notifications

Need Help? Our integration team is here to help. Reach out via email or join our developer community for assistance with your specific use case.

Last modified on
Accept One-Time PaymentsSupported Currencies