Payments API
The Payments API allows you to create, retrieve, and manage cryptocurrency payments.
Create Payment
Create a new payment request. Returns a unique address for the customer to send funds to.
POST /v1/paymentsRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
merchantRef | string | Yes | Your unique reference for this payment |
amount | string | Yes | Amount in smallest unit (wei for ETH, 6 decimals for USDC) |
currency | string | Yes | Token symbol: ETH, USDC, USDT, DAI, WBTC |
chain | string | Yes | ethereum, polygon, arbitrum, optimism, base |
webhookUrl | string | No | URL to receive payment notifications |
redirectUrl | string | No | URL to redirect user after payment |
expiresIn | number | No | Expiration time in seconds (default: 3600) |
metadata | object | No | Custom key-value pairs for your use |
Example Request
curl -X POST https://api.monterrey.app/v1/payments \
-H "X-API-Key: mk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"merchantRef": "order_12345",
"amount": "1000000",
"currency": "USDC",
"chain": "polygon",
"webhookUrl": "https://yoursite.com/webhooks/monterrey",
"metadata": {
"customer_id": "cust_abc123"
}
}'Response
{
"id": "pay_1234567890",
"merchantRef": "order_12345",
"amount": "1000000",
"currency": "USDC",
"chain": "polygon",
"address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
"status": "pending",
"createdAt": "2024-01-15T10:30:00Z",
"expiresAt": "2024-01-15T11:30:00Z",
"metadata": {
"customer_id": "cust_abc123"
}
}Get Payment
Retrieve details of an existing payment.
GET /v1/payments/:idExample Request
curl https://api.monterrey.app/v1/payments/pay_1234567890 \
-H "X-API-Key: mk_live_your_api_key"List Payments
Retrieve a list of payments with optional filters.
GET /v1/paymentsQuery Parameters
| Parameter | Type | Description |
|---|---|---|
status | string | Filter by status: pending, confirmed, expired, failed |
chain | string | Filter by blockchain |
limit | number | Number of results (default: 20, max: 100) |
cursor | string | Pagination cursor from previous response |
Payment Status
| Status | Description |
|---|---|
pending | Waiting for payment |
detecting | Transaction detected, waiting for confirmations |
confirmed | Payment confirmed on blockchain |
expired | Payment window expired without receiving funds |
failed | Payment failed (insufficient amount, wrong token, etc.) |
SDK Examples
import { MonterreyClient } from "@monterrey/sdk";
const monterrey = new MonterreyClient({
apiKey: process.env.MONTERREY_API_KEY,
});
// Create a payment
const payment = await monterrey.payments.create({
merchantRef: "order_12345",
amount: "1000000",
currency: "USDC",
chain: "polygon",
});
// Get a payment
const retrieved = await monterrey.payments.get("pay_1234567890");
// List payments
const { data, cursor } = await monterrey.payments.list({
status: "confirmed",
limit: 50,
});