MoneyGraph Recipe

# Build a Payment Acceptance Platform with MoneyGraph

This recipe shows you how to build a complete payment acceptance platform using MoneyGraph SDK. You'll learn to accept card payments via embedded widgets, popup checkout, or server-side API calls.

User Journey Overview

┌─────────────────────────────────────────────────────────────────────────────┐
│                        PAYMENT ACCEPTANCE FLOW                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. CHECKOUT INITIATION                                                     │
│     ├── Customer adds items to cart                                         │
│     ├── Customer clicks "Pay Now"                                           │
│     └── Your app generates external_reference                               │
│                                                                             │
│  2. PAYMENT COLLECTION                                                      │
│     ├── Option A: Widget Embed (embedded on page)                           │
│     ├── Option B: Popup Checkout (modal overlay)                            │
│     └── Option C: Server-Side Charge (requires PCI compliance)              │
│                                                                             │
│  3. CARD PROCESSING                                                         │
│     ├── Card details collected securely                                     │
│     ├── 3DS authentication (if required)                                    │
│     └── Payment authorization                                               │
│                                                                             │
│  4. RESULT HANDLING                                                         │
│     ├── success → Fulfill order, redirect to thank-you                      │
│     ├── pending → Show processing, wait for webhook                         │
│     ├── requires_action → Redirect to 3DS authentication                    │
│     └── declined/blocked → Show error, offer retry                          │
│                                                                             │
│  5. SERVER VERIFICATION                                                     │
│     ├── Verify payment via API (mg.payments.verifyPayment)                  │
│     └── Fulfill order only after verification                               │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘

Prerequisites

MoneyGraph account with payment acceptance enabled
Public key (pk_test_* or pk_live_*) for client-side
Secret key (sk_test_* or sk_live_*) for server-side

AI Agent Quick Start

Use this prompt with your AI coding assistant:

Build a payment acceptance platform using MoneyGraph SDK with these features:

CHECKOUT PAGE
- Product display with price
- Embedded payment widget (stratos-embed div)
- Load https://stratospay.com/embed.js
- Configure with public_key, external_reference, amount, customer, billing_address
- Handle onsuccess, onerror callbacks

SERVER VERIFICATION
- POST /api/verify-payment endpoint
- Use mg.payments.verifyPayment(externalReference)
- Only fulfill order after verification returns success

WEBHOOK HANDLER
- POST /webhooks/payments endpoint
- Handle payment.success, payment.failed, payment.refunded events
- Update order status in database

ERROR HANDLING
- Show user-friendly messages for card_declined, insufficient_funds, expired_card
- Offer retry option on failure

TEST MODE
- Use pk_test_* and sk_test_* keys
- Test with card 4917484589897107 for success

SDK METHODS: - mg.payments.chargeCard() - Server-side direct charge (PCI required) - mg.payments.verifyPayment() - Verify payment status

IMPORTANT: Always verify payments server-side before fulfilling orders! ```

Integration Options

Option 1: Widget Embed (Recommended)

Best for seamless checkout embedded directly on your page.

<!DOCTYPE html>
<html>
<head>
  <title>Checkout</title>
</head>
<body>
  <h1>Complete Your Purchase</h1>

```

Option 2: Server-Side Verification

Always verify payments server-side before fulfilling orders!

// POST /api/verify-payment
import { MoneyGraph } from '@moneygraph/sdk';

const mg = new MoneyGraph({ apiKey: process.env.MONEYGRAPH_API_KEY! });

export async function POST(req: Request) { const { externalReference } = await req.json();

const payment = await mg.payments.verifyPayment(externalReference);

if (payment.status === 'success') { // Payment verified - safe to fulfill order await fulfillOrder(externalReference); return Response.json({ success: true }); } else { return Response.json({ success: false, status: payment.status, message: 'Payment not verified' }); } } ```

Test Cards

Use these card numbers in sandbox mode (pk_test_*):

Card Number	Result	Use Case
`4917484589897107`	✅ Success	Happy path
`5555555555554444`	✅ Success	Mastercard
`6011111111111117`	💳 Insufficient	Test decline
`4263982640269299`	🔐 Requires 3DS	Test 3DS flow
`374245455400126`	⏳ Pending	Test async

Error Handling

function handlePaymentError(error: { code: string; message: string }) {
  switch (error.code) {
    case 'card_declined':
      return 'Your card was declined. Please try another card.';
    case 'insufficient_funds':
      return 'Insufficient funds. Please try another payment method.';
    case 'expired_card':
      return 'Your card has expired. Please update your card details.';
    case 'invalid_cvv':
      return 'Invalid security code. Please check and try again.';
    case 'card_blocked':
      return 'This card has been blocked. Please contact your bank.';
    default:
      return 'Payment failed. Please try again.';
  }
}

Next Steps

Resources:

MoneyGraph SDK Documentation - Complete API reference
Payment Widget Guide - Widget configuration
PCI Compliance Guide - Security requirements

Build a Payment Acceptance Platform with MoneyGraph