Tracking & Webhooks

GET /api/lookup/{id}

curl -X GET "https://surstrom.io/api/lookup/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \
-H "x-api-key: your-api-key"

{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "PAYMENT",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:35:00.000Z",
"status": "COMPLETED",
"providerId": "provider-uuid",
"relayId": "relay-user-uuid",
"clientId": "your-user-uuid",
"externalId": "order-123",
"relayPage": "https://relay-site.com/checkout?id=a1b2c3d4...",
"suffix": "MYSHOP",
"suffixClient": "ORDER123",
"amount": 100.00,
"currency": "usd",
"fee": 7,
"send": 93.00,
"relayWallet": "RelayWalletPublicKey...",
"clientWallet": "YourWalletPublicKey...",
"txHash": "5UxG7jK2mN...",
"deliveryTime": "2025-01-15T10:35:00.000Z",
"card": "4242",
"cardholder": "John Doe",
"country": "US",
"bin": "424242",
"brand": "visa",
"cardFingerprint": "fp_abc123...",
"fraudScore": 12,
"ip": "192.168.1.1",
"theme": "light",
"sent": "TRUE"
}

{
"error": "Payment not found"
}

{
"error": "API key required"
}

const crypto = require('crypto')

const API_KEY = process.env.SURSTROM_API_KEY

app.post('/webhook/surstrom', (req, res) => {
const signature = req.headers['x-signature']
const rawBody = JSON.stringify(req.body) // must match the raw bytes received

const expected = crypto
  .createHmac('sha256', API_KEY)
  .update(rawBody)
  .digest('hex')

if (signature !== expected) {
  return res.status(401).send('Invalid signature')
}

// Signature valid, process webhook...
res.status(200).send('OK')
})

import hmac
import hashlib

API_KEY = os.environ["SURSTROM_API_KEY"]

@app.route("/webhook/surstrom", methods=["POST"])
def webhook():
  signature = request.headers.get("X-Signature", "")
  raw_body = request.get_data(as_text=True)

  expected = hmac.new(
      API_KEY.encode(),
      raw_body.encode(),
      hashlib.sha256
  ).hexdigest()

  if not hmac.compare_digest(signature, expected):
      return "Invalid signature", 401

  # Signature valid, process webhook...
  return "OK", 200

{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"type": "PAYMENT",
"createdAt": "2025-01-15T10:30:00.000Z",
"updatedAt": "2025-01-15T10:35:00.000Z",
"status": "COMPLETED",
"providerId": "provider-uuid",
"relayId": "relay-user-uuid",
"clientId": "your-user-uuid",
"externalId": "order-123",
"relayPage": "https://relay-site.com/checkout?id=a1b2c3d4...",
"suffix": "MYSHOP",
"suffixClient": "ORDER123",
"amount": 100.00,
"currency": "usd",
"fee": 7,
"send": 93.00,
"relayWallet": "RelayWalletPublicKey...",
"clientWallet": "YourWalletPublicKey...",
"txHash": "5UxG7jK2mN...",
"deliveryTime": "2025-01-15T10:35:00.000Z",
"card": "4242",
"cardholder": "John Doe",
"country": "US",
"bin": "424242",
"brand": "visa",
"cardFingerprint": "fp_abc123...",
"fraudScore": 12,
"ip": "192.168.1.1",
"theme": "light",
"sent": "TRUE"
}

{
"exchangeRoute": {
  "originalValue": 100.00,
  "clientCurrency": "usd",
  "nativeCurrency": "eur",
  "rate": 0.92,
  "result": 92.00
}
}

{
"event": "test",
"timestamp": "2025-01-15T10:30:00.000Z",
"userId": "your-user-uuid",
"message": "This is a test webhook from surstrom"
}

app.post('/webhook/surstrom', (req, res) => {
const event = req.headers['x-payment-event']
const payload = req.body

// Test webhook
if (payload.event === 'test') {
  console.log('Test webhook received')
  return res.status(200).send('OK')
}

// Payment webhook
const { id, status, externalId, amount, currency, txHash, send } = payload

switch (status) {
  case 'PENDING':
    // Payment created - redirect customer to relayPage
    console.log(`Payment ${id} created for order ${externalId}`)
    break

  case 'PROCESSING':
    // Payment confirmed, settlement in progress
    console.log(`Payment ${id} confirmed for ${amount} ${currency}`)
    break

  case 'COMPLETED':
    // Settlement complete - fulfill the order
    console.log(`Payment ${id} settled. TX: ${txHash}`)
    console.log(`Received ${send} USDC`)
    await fulfillOrder(externalId)
    break

  case 'FAILED':
    console.log(`Payment ${id} failed: ${payload.errorDesc}`)
    await cancelOrder(externalId)
    break
}

res.status(200).send('OK')
})

const processedPayments = new Set()

app.post('/webhook/surstrom', (req, res) => {
const { id, status } = req.body
const key = `${id}:${status}`

if (processedPayments.has(key)) {
  return res.status(200).send('Already processed')
}

processedPayments.add(key)
// Process payment...

res.status(200).send('OK')
})

app.post('/webhook/surstrom', async (req, res) => {
const { id, status, externalId } = req.body

// Acknowledge webhook immediately
res.status(200).send('OK')

// Verify status before fulfilling order
if (status === 'COMPLETED') {
  const payment = await fetch(`https://surstrom.io/api/lookup/${id}`, {
    headers: { 'x-api-key': API_KEY }
  }).then(r => r.json())

  if (payment.status === 'COMPLETED' && payment.sent === 'TRUE') {
    await fulfillOrder(externalId)
  }
}
})

const payment = await fetch('https://surstrom.io/api/payment/init', {
method: 'POST',
headers: {
  'Content-Type': 'application/json',
  'x-api-key': API_KEY
},
body: JSON.stringify({
  amount: 99.99,
  maxFee: 10,
  currency: 'usd',
  externalId: 'order-12345'  // Your order ID
})
}).then(r => r.json())

// Later, look up by your order ID:
const status = await fetch('https://surstrom.io/api/lookup/order-12345', {
headers: { 'x-api-key': API_KEY }
}).then(r => r.json())

app.post('/webhook/surstrom', (req, res) => {
// Respond immediately
res.status(200).send('OK')

// Queue for async processing
paymentQueue.add(req.body)
})