M
monterrey

Quick Start

Get up and running with monterrey.app in under 5 minutes. This guide will walk you through creating your first payment.

Prerequisites

  • A monterrey.app account with API keys
  • Node.js 18+ (for the JavaScript SDK)
  • A webhook endpoint to receive payment notifications

Step 1: Install the SDK

npm install @monterrey/sdk
# or
yarn add @monterrey/sdk
# or
pnpm add @monterrey/sdk

Step 2: Initialize the Client

import { MonterreyClient } from "@monterrey/sdk";

const monterrey = new MonterreyClient({
  apiKey: process.env.MONTERREY_API_KEY,
  // Use "testnet" for development
  network: "mainnet",
});

Step 3: Create a Payment

const payment = await monterrey.payments.create({
  // Your internal order reference
  merchantRef: "order_12345",

  // Amount in smallest unit (e.g., 1000000 = 1 USDC)
  amount: "1000000",
  currency: "USDC",

  // Supported: ethereum, polygon, arbitrum, optimism, base
  chain: "polygon",

  // Where to send webhook notifications
  webhookUrl: "https://yoursite.com/api/webhooks/monterrey",

  // Optional: redirect user after payment
  redirectUrl: "https://yoursite.com/order/12345/complete",
});

console.log("Payment address:", payment.address);
console.log("Expires at:", payment.expiresAt);

Step 4: Handle Webhooks

// pages/api/webhooks/monterrey.ts (Next.js example)
import { verifyWebhookSignature } from "@monterrey/sdk";

export default async function handler(req, res) {
  const signature = req.headers["x-monterrey-signature"];
  const payload = req.body;

  // Verify the webhook is from monterrey.app
  const isValid = verifyWebhookSignature(
    payload,
    signature,
    process.env.MONTERREY_WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).json({ error: "Invalid signature" });
  }

  switch (payload.event) {
    case "payment.confirmed":
      // Payment received and confirmed
      await fulfillOrder(payload.data.merchantRef);
      break;
    case "payment.expired":
      // Payment window expired
      await cancelOrder(payload.data.merchantRef);
      break;
  }

  res.status(200).json({ received: true });
}

Step 5: Test Your Integration

Use test mode to verify your integration without real funds:

  1. Use your test API key (starts with mk_test_)
  2. Create a payment on a testnet (e.g., Polygon Mumbai)
  3. Send test tokens to the payment address
  4. Verify your webhook receives the confirmation

Next Steps

    Documentation | Monterrey