API Reference

Welcome to the Artcade API documentation! This guide explains all the ways your code can talk to the arcade system. Let's make it fun! 🎮

API Overview 🌐

Your arcade API has four main endpoints:

Check if everything's working (/status)
Create payment QR codes (/create-payment-link)
Process payments (/addCredit)
Handle game endings (/gameover)

Think of it Like a Restaurant

/status is like checking if the restaurant is open
/create-payment-link is like creating a menu QR code
/addCredit is like processing a payment at the register
/gameover is like clearing a table for the next customer

Base URL 🔗

Your API will be available at:

https://your-api-id.execute-api.your-region.amazonaws.com/prod

Finding Your URL

You'll get your specific URL when you set up API Gateway in AWS. It will look similar to:

https://abc123def.execute-api.us-west-2.amazonaws.com/prod

Endpoints 🎯

Check Status

Checks if your API is running properly.

GET /status

Response

{
    "status": "up",
    "message": "API is running"
}

Testing Status

curl https://your-api-url/status

Create Payment Link

Creates a QR code payment link for your arcade cabinet.

POST /create-payment-link

Request Body

{
    "machine_id": "your-machine-id",
    "price_id": "price_xxxxxxxxxxxxx",  // Optional
    "quantity": 1                       // Optional
}

Parameters

machine_id (required): Your unique arcade cabinet ID
price_id (optional): Stripe price ID for custom pricing
quantity (optional): Number of credits to purchase

Response

{
    "url": "https://checkout.stripe.com/..."
}

Creating a Payment Link

curl -X POST https://your-api-url/create-payment-link \
  -H "Content-Type: application/json" \
  -d '{"machine_id":"arcade123"}'

Process Payment

Handles Stripe webhook notifications when a payment succeeds.

POST /addCredit

Webhook Security

This endpoint is called by Stripe with a special signature. Don't call it directly!

Headers

Stripe-Signature: Special code from Stripe to verify the webhook

Webhook Event

{
    "type": "checkout.session.completed",
    "data": {
        "object": {
            "metadata": {
                "machine_id": "arcade123"
            },
            "amount_total": 100
        }
    }
}

Response

200 OK: Payment processed successfully
400 Bad Request: Invalid webhook
500 Error: Processing failed

Game Over

Signals that a game has ended.

POST /gameover

Request Body

{
    "machine_id": "arcade123"
}

Response

{
    "message": "Game over signal sent"
}

Sending Game Over

curl -X POST https://your-api-url/gameover \
  -H "Content-Type: application/json" \
  -d '{"machine_id":"arcade123"}'

MQTT Messages 📨

Your API publishes these MQTT messages:

Coin Pulse Signal

Sent when credits should be added:

{
    "machineId": "arcade123",
    "credits": 1,
    "timestamp": "2024-07-01T12:00:00Z"
}

Game Over Signal

Sent when a game ends:

{
    "machineId": "arcade123",
    "status": "game_over",
    "timestamp": "2024-07-01T12:30:00Z"
}

Testing Tips 🧪

Test Cards

Use these Stripe test cards:

Success: 4242 4242 4242 4242
Decline: 4000 0000 0000 0002
Error: 4000 0000 0000 9995

Test Card Details

Use any future expiry date
Any 3-digit CVC
Any 5-digit ZIP code

Using Stripe CLI

Test webhooks locally:

Start webhook forwarding:

stripe listen --forward-to localhost:5000/webhook

Trigger test events:

stripe trigger checkout.session.completed

Error Handling 🔧

Your API returns standard HTTP status codes:

200: Everything worked
400: Something wrong with the request
401: Not authorized
404: Endpoint not found
500: Server error

Error responses look like:

{
    "error": "Description of what went wrong"
}

Rate Limits 📊

Free tier limits:

AWS Lambda: 1,000,000 requests/month
EMQX: 1 GB traffic/month
Stripe: No monthly limits

Stay Within Limits

Monitor your usage in AWS Console
Watch EMQX dashboard
Check Stripe dashboard

Security Best Practices 🔐

Never share:
- API keys
- Webhook secrets
- MQTT credentials
- AWS credentials
Always use:
- HTTPS endpoints
- Webhook signatures
- SSL/TLS for MQTT
- Environment variables

Need Help? 🤔

If you run into problems:

Check the logs:
- AWS CloudWatch
- EMQX Dashboard
- Stripe Dashboard
Common issues:
- Wrong API URL
- Invalid credentials
- Network problems
- Rate limiting

Still Stuck?

Check our Troubleshooting Guide
Ask your teacher or mentor
Review error messages
Try test endpoints first

Next Steps 🚀

Now that you understand the API:

Test the status endpoint
Create a test payment
Monitor the results
Try the game over signal

Try Quick Deploy → Custom Build Guide →