Build a Payment Acceptance Platform with MoneyGraph

# 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:

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

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

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

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

1. TEST MODE
2. - Use pk_test_* and sk_test_* keys
3. - 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>

// Required: Unique reference for this transaction external_reference: "order_" + Date.now(),

// Required: Payment details title: "Order Payment", description: "Payment for Order #12345", amount: 10000, // Amount in cents ($100.00) currency: "USD",

// Required: Customer info customer: { first_name: "John", last_name: "Doe", email: "[email protected]", phone: "+12025551234", phone_iso2: "US", ip_address: "127.0.0.1" },

// Required: Billing address billing_address: { country: "US", state: "CA", city: "Los Angeles", address: "123 Main Street", postal_code: "90001" },

// Callbacks onsuccess: function(data) { console.log("Payment successful!", data); verifyAndFulfill(data.external_reference); }, onerror: function(data) { console.error("Payment failed:", data); showErrorMessage(data.message); } };

checkout.init(PAYMENT_CONFIG); ```

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_*):

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