Yoco API Payment Integration

A full-stack payment processing solution using Yoco API with Node.js backend and React TypeScript frontend.

🚀 Project Overview

This project provides a complete payment integration solution using Yoco's payment gateway. It consists of:

• Backend: Node.js Express server with Yoco API integration
• Frontend: React TypeScript application with Vite build tool

📁 Project Structure

Yoco-API Backend + Frontend/
├── Backend/                 # Node.js Express server
│   ├── routes/             # API routes
│   ├── server.js          # Main server file
│   ├── package.json       # Backend dependencies
│   └── README.md         # Backend documentation
├── Frontend/              # React TypeScript app
│   ├── src/              
│   │   ├── components/   # React components
│   │   ├── services/     # API and Yoco integrations
│   │   └── ...
│   ├── package.json      # Frontend dependencies
│   └── README.md        # Frontend documentation
└── README.md            # This file

🛠️ Features

Backend Features

• ✅ Payment charge creation
• ✅ Charge status retrieval
• ✅ Refund processing
• ✅ Webhook handling
• ✅ CORS enabled for frontend
• ✅ Security middleware
• ✅ Error handling
• ✅ Environment-based configuration

Frontend Features

• ✅ Secure payment form
• ✅ Payment status checking
• ✅ Yoco SDK integration
• ✅ Backend health monitoring
• ✅ Responsive design
• ✅ Real-time feedback
• ✅ Error handling

🚀 Quick Start

Prerequisites

• Node.js 18+ installed
• Yoco developer account
• API keys from Yoco dashboard

1. Clone and Setup Backend

cd Backend
npm install
cp .env.example .env
# Edit .env and add your Yoco secret key
npm run dev

2. Setup Frontend

cd Frontend
npm install
cp .env.example .env
# Edit .env and add your Yoco public key
npm run dev

3. Get Yoco API Keys

1. Sign up at Yoco Developer Portal
2. Navigate to your dashboard
3. Get your API keys:
   • Secret Key (for backend): sk_test_... or sk_live_...
   • Public Key (for frontend): pk_test_... or pk_live_...

4. Configure Environment Variables

Backend (.env):

YOCO_SECRET_KEY=sk_test_your_secret_key_here
PORT=5000
FRONTEND_URL=http://localhost:5173

Frontend (.env):

VITE_YOCO_PUBLIC_KEY=pk_test_your_public_key_here
VITE_API_URL=http://localhost:5000

🔧 Running the Application

1. Start the backend (in Backend directory):

   npm run dev

   Server runs on: http://localhost:5000

2. Start the frontend (in Frontend directory):

   npm run dev

   App runs on: http://localhost:5173

🧪 Testing

Test Cards

Use these test cards for development:

• Successful Payment: 4000000000000002
• Declined Payment: 4000000000000010
• Insufficient Funds: 4000000000000028

Test Process

1. Open the frontend application
2. Enter a test amount (minimum R1.00)
3. Add a description
4. Click "Pay Now"
5. Use test card details in Yoco's popup
6. Verify payment status

📡 API Endpoints

Backend Endpoints

Method	Endpoint	Description
GET	/api/health	Health check
POST	/api/payment/charge	Create payment charge
GET	/api/payment/charge/:id	Get charge details
POST	/api/payment/refund	Process refund
POST	/api/payment/webhook	Webhook for notifications

🔒 Security

• Secret keys are kept server-side only
• Public keys are used for frontend token generation
• CORS configured for specific origins
• Webhook signature validation (implement as needed)
• Input validation and sanitization
• Error messages don't expose sensitive data

🚀 Deployment

Backend Deployment

1. Set environment variables on your server
2. Configure CORS for your frontend domain
3. Set up webhook URL in Yoco dashboard
4. Use PM2 or similar for process management

Frontend Deployment

1. Build the application: npm run build
2. Deploy the dist folder to your hosting service
3. Configure environment variables for production

🛠️ Development

Backend Development

• Uses nodemon for auto-restart
• Morgan for request logging
• Helmet for security headers
• CORS for cross-origin requests

Frontend Development

• Hot Module Replacement (HMR) with Vite
• TypeScript for type safety
• Tailwind CSS for styling
• Axios for HTTP requests

📚 Documentation

• Backend README - Detailed backend documentation
• Frontend README - Detailed frontend documentation
• Yoco API Docs - Official Yoco documentation

🐛 Troubleshooting

Common Issues

1. "Yoco not configured" error

   • Check your environment variables
   • Ensure you're using the correct key format

2. CORS errors

   • Verify backend CORS configuration
   • Check frontend API URL in environment

3. Payment failures

   • Use valid test cards
   • Check amount is >= R1.00
   • Verify API keys are correct

4. Backend connection issues

   • Ensure backend is running on port 5000
   • Check network connectivity
   • Verify environment variables

📄 License

This project is for educational/development purposes. Please check Yoco's terms of service for production use.

🤝 Contributing

1. Fork the project
2. Create your feature branch
3. Commit your changes
4. Push to the branch
5. Open a Pull Request

---

Happy coding! 💻✨