Skip to main content

Payment Status

Query and monitor the status of payments.

Get Payment Status​

Request​

GET https://api.pelago.tech/v1/payments/{payment_id}

Example​

cURL:

curl https://api.pelago.tech/v1/payments/pay_7xKp9mNq2vT \
  -H "Authorization: Bearer pk_live_xxxxx" \
  -H "X-Api-Secret: sk_live_xxxxx"

JavaScript:

const payment = await pelago.payments.retrieve('pay_7xKp9mNq2vT');
console.log('Status:', payment.status);

Python:

payment = pelago.payments.retrieve('pay_7xKp9mNq2vT')
print('Status:', payment.status)

Response​

{
  "id": "pay_7xKp9mNq2vT",
  "object": "payment",
  "status": "completed",
  "amount": 99.99,
  "currency": "USD",
  "cryptoAmount": "99.990000",
  "cryptocurrency": "USDC",
  "network": "stellar",
  "merchantWallet": "GXXXXX...",
  "customerWallet": "GCUST...",
  "transactionHash": "abc123...def456",
  "completedAt": "2025-02-08T22:35:00Z",
  "settledAt": null,
  "settlementId": null,
  "metadata": {
    "orderId": "ORD-12345"
  }
}

Payment Statuses​

StatusDescriptionFinal?
createdPayment initializedNo
pendingAwaiting customer actionNo
processingTransaction in progressNo
completedPayment successfulYes
failedPayment failedYes
expiredPayment timed outYes
refundedPayment refundedYes

List Payments​

Request​

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

Query Parameters​

ParameterTypeDescription
limitnumberMax results per page (1-100, default: 10)
starting_afterstringCursor for pagination
statusstringFilter by status
created_gtestringCreated after (ISO datetime)
created_ltestringCreated before (ISO datetime)

Example​

// List recent completed payments
const payments = await pelago.payments.list({
  status: 'completed',
  limit: 20,
  created_gte: '2025-02-01T00:00:00Z'
});

for (const payment of payments.data) {
  console.log(`${payment.id}: $${payment.amount}`);
}

// Pagination
if (payments.hasMore) {
  const nextPage = await pelago.payments.list({
    starting_after: payments.data[payments.data.length - 1].id
  });
}

Response​

{
  "object": "list",
  "data": [
    {
      "id": "pay_7xKp9mNq2vT",
      "status": "completed",
      "amount": 99.99,
      ...
    },
    {
      "id": "pay_6wLo8lMp1uS",
      "status": "completed",
      "amount": 50.00,
      ...
    }
  ],
  "hasMore": true,
  "totalCount": 156
}

Real-time Status Updates​

WebSocket Connection​

For real-time updates, use the WebSocket API:

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

const stream = createPaymentStream({
  apiKey: process.env.PELAGO_API_KEY,
  paymentId: 'pay_7xKp9mNq2vT'
});

stream.on('status_change', (event) => {
  console.log('New status:', event.status);
  console.log('Transaction hash:', event.transactionHash);
});

stream.on('error', (error) => {
  console.error('Stream error:', error);
});

// Clean up when done
stream.close();

Polling (Alternative)​

If WebSocket isn't available, use polling:

async function waitForPayment(paymentId: string, maxAttempts = 60) {
  for (let i = 0; i < maxAttempts; i++) {
    const payment = await pelago.payments.retrieve(paymentId);
    
    if (['completed', 'failed', 'expired'].includes(payment.status)) {
      return payment;
    }
    
    await new Promise(resolve => setTimeout(resolve, 5000)); // 5 second delay
  }
  
  throw new Error('Payment timeout');
}

const payment = await waitForPayment('pay_7xKp9mNq2vT');
console.log('Final status:', payment.status);

Payment Timeline​

Track all status changes:

const timeline = await pelago.payments.getTimeline('pay_7xKp9mNq2vT');

for (const event of timeline.events) {
  console.log(`${event.timestamp}: ${event.status}`);
  console.log(`  Details: ${event.details}`);
}

Response​

{
  "paymentId": "pay_7xKp9mNq2vT",
  "events": [
    {
      "timestamp": "2025-02-08T22:30:00Z",
      "status": "created",
      "details": "Payment request created"
    },
    {
      "timestamp": "2025-02-08T22:32:00Z",
      "status": "pending",
      "details": "Customer opened payment page"
    },
    {
      "timestamp": "2025-02-08T22:34:00Z",
      "status": "processing",
      "details": "Transaction submitted"
    },
    {
      "timestamp": "2025-02-08T22:34:15Z",
      "status": "completed",
      "details": "Transaction confirmed on Stellar",
      "transactionHash": "abc123...def456"
    }
  ]
}

Status Diagram​

Next Steps​