Quick Start Guide
Get your first Pelago payment integration running in 5 minutes.
Prerequisites
- Node.js 18+ or Python 3.9+
- A cryptocurrency wallet address
- Pelago API credentials (get them from the Dashboard)
Step 1: Install the SDK
JavaScript:
npm install @pelago/sdk
# or
yarn add @pelago/sdk
Python:
pip install pelago-sdk
Go:
go get github.com/polyflow/pelago-go
Step 2: Configure Your Client
JavaScript:
import { PelagoClient } from '@pelago/sdk';
const pelago = new PelagoClient({
apiKey: process.env.PELAGO_API_KEY,
apiSecret: process.env.PELAGO_API_SECRET,
environment: 'sandbox' // Use 'production' for live payments
});
Python:
from pelago import PelagoClient
pelago = PelagoClient(
api_key=os.environ['PELAGO_API_KEY'],
api_secret=os.environ['PELAGO_API_SECRET'],
environment='sandbox'
)
Go:
import "github.com/polyflow/pelago-go"
client := pelago.NewClient(pelago.Config{
APIKey: os.Getenv("PELAGO_API_KEY"),
APISecret: os.Getenv("PELAGO_API_SECRET"),
Environment: pelago.Sandbox,
})
Step 3: Create a Payment
JavaScript:
const payment = await pelago.payments.create({
amount: 50.00,
currency: 'USD',
cryptocurrency: 'USDC',
network: 'stellar',
merchantWallet: 'GXXXXX...', // Your Stellar wallet
redirectUrl: 'https://yourstore.com/success',
webhookUrl: 'https://yourstore.com/api/webhook',
metadata: {
orderId: 'order_12345',
customerEmail: '[email protected]'
}
});
// Redirect customer to payment page
console.log('Payment URL:', payment.url);
console.log('Payment ID:', payment.id);
Python:
payment = pelago.payments.create(
amount=50.00,
currency='USD',
cryptocurrency='USDC',
network='stellar',
merchant_wallet='GXXXXX...',
redirect_url='https://yourstore.com/success',
webhook_url='https://yourstore.com/api/webhook',
metadata={
'order_id': 'order_12345',
'customer_email': '[email protected]'
}
)
print('Payment URL:', payment.url)
print('Payment ID:', payment.id)
Go:
payment, err := client.Payments.Create(context.Background(), &pelago.PaymentRequest{
Amount: 50.00,
Currency: "USD",
Cryptocurrency: "USDC",
Network: "stellar",
MerchantWallet: "GXXXXX...",
RedirectURL: "https://yourstore.com/success",
WebhookURL: "https://yourstore.com/api/webhook",
Metadata: map[string]string{
"orderId": "order_12345",
"customerEmail": "[email protected]",
},
})
if err != nil {
log.Fatal(err)
}
fmt.Printf("Payment URL: %s\n", payment.URL)
fmt.Printf("Payment ID: %s\n", payment.ID)
Step 4: Handle Webhooks
When the payment is completed, Pelago sends a webhook to your server:
// Express.js example
app.post('/api/webhook', async (req, res) => {
const signature = req.headers['x-pelago-signature'];
// Verify webhook signature
if (!pelago.webhooks.verify(req.body, signature)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = req.body;
switch (event.type) {
case 'payment.completed':
// Payment successful - fulfill the order
await fulfillOrder(event.data.metadata.orderId);
break;
case 'payment.failed':
// Payment failed - notify customer
await notifyPaymentFailed(event.data.metadata.customerEmail);
break;
case 'payment.expired':
// Payment expired - cancel the order
await cancelOrder(event.data.metadata.orderId);
break;
}
res.status(200).json({ received: true });
});
Payment Response
A successful payment creation returns:
{
"id": "pay_7xKp9mNq2vT",
"status": "pending",
"amount": 50.00,
"currency": "USD",
"cryptocurrency": "USDC",
"cryptoAmount": "50.000000",
"network": "stellar",
"url": "https://pay.pelago.tech/pay_7xKp9mNq2vT",
"qrCode": "data:image/png;base64,...",
"expiresAt": "2025-02-08T22:00:00Z",
"metadata": {
"orderId": "order_12345",
"customerEmail": "[email protected]"
}
}