Create Payment

Learn how to create payment requests via the Pelago API.

Basic Payment Creation

Request

POST https://api.pelago.tech/v1/payments

Parameters

Parameter	Type	Required	Description
amount	number	✓	Payment amount
currency	string	✓	Fiat currency (USD, EUR, etc.)
cryptocurrency	string	✓	USDC, USDT, DAI
network	string	✓	stellar, ethereum, polygon
merchantWallet	string	✓	Your wallet address
redirectUrl	string		Success redirect URL
webhookUrl	string		Webhook endpoint
expiresIn	number		Seconds until expiration (default: 1800)
metadata	object		Custom key-value data

Example

cURL:

curl -X POST https://api.pelago.tech/v1/payments \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 99.99,
    "currency": "USD",
    "cryptocurrency": "USDC",
    "network": "stellar",
    "merchantWallet": "GXXXXX...",
    "redirectUrl": "https://mystore.com/order/success",
    "webhookUrl": "https://mystore.com/api/webhook",
    "expiresIn": 1800,
    "metadata": {
      "orderId": "ORD-12345",
      "customerId": "cust_abc123",
      "productName": "Premium Plan"
    }
  }'

JavaScript:

import { PelagoClient } from '@pelago/sdk';

const pelago = new PelagoClient({
  apiKey: process.env.PELAGO_API_KEY,
  apiSecret: process.env.PELAGO_API_SECRET,
  environment: 'production'
});

const payment = await pelago.payments.create({
  amount: 99.99,
  currency: 'USD',
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...',
  redirectUrl: 'https://mystore.com/order/success',
  webhookUrl: 'https://mystore.com/api/webhook',
  expiresIn: 1800,
  metadata: {
    orderId: 'ORD-12345',
    customerId: 'cust_abc123',
    productName: 'Premium Plan'
  }
});

Python:

from pelago import PelagoClient

pelago = PelagoClient(
    api_key=os.environ['PELAGO_API_KEY'],
    api_secret=os.environ['PELAGO_API_SECRET'],
    environment='production'
)

payment = pelago.payments.create(
    amount=99.99,
    currency='USD',
    cryptocurrency='USDC',
    network='stellar',
    merchant_wallet='GXXXXX...',
    redirect_url='https://mystore.com/order/success',
    webhook_url='https://mystore.com/api/webhook',
    expires_in=1800,
    metadata={
        'order_id': 'ORD-12345',
        'customer_id': 'cust_abc123',
        'product_name': 'Premium Plan'
    }
)

Response

{
  "id": "pay_7xKp9mNq2vT",
  "object": "payment",
  "status": "created",
  "amount": 99.99,
  "currency": "USD",
  "cryptoAmount": "99.990000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "url": "https://pay.pelago.tech/pay_7xKp9mNq2vT",
  "qrCode": "data:image/png;base64,iVBORw0KGgo...",
  "merchantWallet": "GXXXXX...",
  "redirectUrl": "https://mystore.com/order/success",
  "webhookUrl": "https://mystore.com/api/webhook",
  "expiresAt": "2025-02-08T23:00:00Z",
  "createdAt": "2025-02-08T22:30:00Z",
  "metadata": {
    "orderId": "ORD-12345",
    "customerId": "cust_abc123",
    "productName": "Premium Plan"
  }
}

Payment Options

Networks & Cryptocurrencies

Network	Cryptocurrencies	Confirmation Time
stellar	USDC	~5 seconds
ethereum	USDC, USDT, DAI	~15 seconds
polygon	USDC, USDT	~5 seconds
arbitrum	USDC	~2 seconds

Settlement Modes

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  settlementMode: 'instant', // or 'batch' (default)
  // ...
});

Mode	Fee	Speed
batch	0.1%	15-30 min
instant	0.5%	< 1 min

Advanced Options

Fixed Crypto Amount

Specify exact crypto amount instead of converting from fiat:

const payment = await pelago.payments.create({
  cryptoAmount: 100.50,  // Fixed USDC amount
  cryptocurrency: 'USDC',
  network: 'stellar',
  merchantWallet: 'GXXXXX...'
});

Multiple Currencies Accepted

Accept any supported cryptocurrency:

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  acceptedCryptocurrencies: ['USDC', 'USDT', 'DAI'],
  acceptedNetworks: ['stellar', 'polygon'],
  merchantWallet: 'GXXXXX...'
});

Customer-Bound Payment

Pre-assign payment to a customer:

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  customerPID: 'did:pelago:stellar:GCUST...', // Customer's PID
  // ...
});

Display Payment UI

Redirect

Redirect customers to the hosted payment page:

// After creating payment
window.location.href = payment.url;

Embed

Embed the payment widget in your page:

<div id="pelago-payment"></div>
<script src="https://js.pelago.tech/embed.js"></script>
<script>
  Pelago.embed({
    container: '#pelago-payment',
    paymentId: 'pay_7xKp9mNq2vT',
    theme: 'dark',
    onSuccess: (payment) => {
      console.log('Payment completed:', payment.id);
    },
    onError: (error) => {
      console.error('Payment failed:', error);
    }
  });
</script>

QR Code

Display the QR code for mobile wallet scanning:

// React example
function PaymentQR({ payment }) {
  return (
    <div>
      <img src={payment.qrCode} alt="Scan to pay" />
      <p>Amount: {payment.cryptoAmount} {payment.cryptocurrency}</p>
      <p>Expires: {new Date(payment.expiresAt).toLocaleString()}</p>
    </div>
  );
}

Idempotency

Use idempotency keys to prevent duplicate payments:

const payment = await pelago.payments.create({
  amount: 100,
  currency: 'USD',
  // ...
}, {
  idempotencyKey: 'order_12345_attempt_1'
});

// Retrying with same key returns the same payment
const samePayment = await pelago.payments.create({
  // ... same params
}, {
  idempotencyKey: 'order_12345_attempt_1' // Same key
});

// samePayment.id === payment.id

Next Steps

• Query Payment Status
• Configure Webhooks
• Handle Errors