Payment Webhooks

Receive real-time notifications when payment events occur in your Trustist merchant account. Payment webhooks enable you to automate order fulfilment, update customer records, and trigger business workflows instantly.

Setting Up Payment Webhooks

Payment webhooks are configured through the TrustistTransfer portal, not via the TE API:

1. Log in to TrustistTransfer
2. Navigate to Settings → API Keys
3. Enter your webhook endpoint URL (must be HTTPS for production)
4. Select which events you want to receive
5. Save your configuration

Available Events

Payment Events

Standing Order Events

Webhook Payload Structure

All payment webhooks are sent as HTTP POST requests with a JSON payload.

Payment Event Payload

{
  "merchantId": "mch_abc123xyz",
  "paymentId": "pmt_123456789",
  "orgId": "org_branch001",
  "created": "2025-10-21T14:30:00Z",
  "status": "COMPLETED",
  "amount": 150.00,
  "currency": "GBP",
  "description": "Product purchase",
  "reference": "ORDER-12345",
  "paymentMethod": "Bank Transfer",
  "eventType": "payment.completed"
}

Payment Payload Fields

Standing Order Event Payload

{
  "merchantId": "mch_abc123xyz",
  "standingOrderId": "so_123456789",
  "orgId": "org_branch001",
  "created": "2025-10-21T14:30:00Z",
  "status": "ACTIVE",
  "amount": 50.00,
  "currency": "GBP",
  "frequency": "MONTHLY",
  "description": "Monthly subscription",
  "reference": "SUB-12345",
  "eventType": "standing_order.created"
}

Standing Order Payload Fields

Implementing a Webhook Endpoint

Requirements

Your webhook endpoint must:

• ✅ Accept HTTP POST requests
• ✅ Return a 2xx HTTP status code within 30 seconds
• ✅ Be publicly accessible (not localhost or private network)
• ✅ Use HTTPS in production
• ✅ Process events asynchronously to avoid timeouts
• ✅ Handle duplicate events idempotently

Example Implementation (Node.js/Express)

const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhooks/trustist/payments', async (req, res) => {
    // Immediately acknowledge receipt
    res.status(200).send('OK');
    
    // Process asynchronously
    processPaymentWebhookAsync(req.body).catch(err => {
        console.error('Webhook processing failed:', err);
    });
});

async function processPaymentWebhookAsync(payload) {
    const { eventType, paymentId, status, amount, reference } = payload;
    
    console.log(`Processing webhook: ${eventType} for payment ${paymentId}`);
    
    // Check for duplicates using paymentId + eventType
    const existing = await db.webhookEvents.findOne({ 
        paymentId, 
        eventType 
    });
    
    if (existing) {
        console.log('Duplicate webhook, skipping');
        return;
    }
    
    // Log the event
    await db.webhookEvents.create({ 
        paymentId, 
        eventType, 
        processedAt: new Date(),
        payload 
    });
    
    // Handle the event
    switch (eventType) {
        case 'payment.created':
            await handlePaymentCreated(payload);
            break;
            
        case 'payment.completed':
            await handlePaymentCompleted(payload);
            break;
            
        case 'payment.failed':
            await handlePaymentFailed(payload);
            break;
            
        case 'standing_order.created':
            await handleStandingOrderCreated(payload);
            break;
            
        case 'standing_order.cancelled':
            await handleStandingOrderCancelled(payload);
            break;
            
        default:
            console.warn(`Unknown event type: ${eventType}`);
    }
}

async function handlePaymentCompleted(payload) {
    const { reference, amount, paymentId } = payload;
    
    // Update order status
    await db.orders.update(
        { orderNumber: reference },
        { 
            status: 'PAID',
            paidAt: new Date(),
            paymentId: paymentId,
            paidAmount: amount
        }
    );
    
    // Trigger fulfilment
    await fulfillmentService.processOrder(reference);
    
    // Send confirmation email
    await emailService.sendPaymentConfirmation(reference);
}

Example Implementation (C# ASP.NET Core)

using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("webhooks/trustist/payments")]
public class TrustistPaymentWebhookController : ControllerBase
{
    private readonly ILogger _logger;
    private readonly IBackgroundTaskQueue _taskQueue;
    
    public TrustistPaymentWebhookController(
        ILogger logger,
        IBackgroundTaskQueue taskQueue)
    {
        _logger = logger;
        _taskQueue = taskQueue;
    }
    
    [HttpPost]
    public IActionResult HandleWebhook([FromBody] PaymentWebhookPayload payload)
    {
        // Queue for background processing
        _taskQueue.QueueBackgroundWorkItem(async token =>
        {
            await ProcessWebhookAsync(payload, token);
        });
        
        // Immediately return success
        return Ok();
    }
    
    private async Task ProcessWebhookAsync(
        PaymentWebhookPayload payload,
        CancellationToken ct)
    {
        _logger.LogInformation("Processing webhook: {Event} for payment {PaymentId}", 
            payload.EventType, payload.PaymentId);
        
        // Check for duplicates
        var exists = await _db.WebhookEvents
            .AnyAsync(e => e.PaymentId == payload.PaymentId && 
                          e.EventType == payload.EventType, ct);
        
        if (exists)
        {
            _logger.LogInformation("Duplicate webhook, skipping");
            return;
        }
        
        // Log the event
        await _db.WebhookEvents.AddAsync(new WebhookEvent
        {
            PaymentId = payload.PaymentId,
            EventType = payload.EventType,
            ProcessedAt = DateTime.UtcNow,
            Payload = JsonSerializer.Serialize(payload)
        }, ct);
        
        await _db.SaveChangesAsync(ct);
        
        // Handle the event
        switch (payload.EventType)
        {
            case "payment.completed":
                await HandlePaymentCompletedAsync(payload, ct);
                break;
                
            case "payment.failed":
                await HandlePaymentFailedAsync(payload, ct);
                break;
                
            // ... other cases
        }
    }
}

Common Integration Patterns

Order Status Updates

Use payment webhooks to automatically update order statuses:

• payment.created → Set order to "Payment Pending"
• payment.completed → Set order to "Paid", trigger fulfilment
• payment.failed → Set order to "Payment Failed" (keep available for retry)

Subscription Management

Use standing order webhooks to manage subscriptions:

• standing_order.created → Activate subscription, grant access
• standing_order.cancelled → Cancel subscription, revoke access

Customer Communication

Trigger automated customer notifications:

• Send confirmation emails on payment.completed
• Send retry prompts on payment.failed (if retry suppression is not enabled)
• Send subscription confirmation on standing_order.created

Webhook Delivery & Retry Policy

Success Criteria

Trustist considers a webhook successfully delivered if your endpoint:

• Returns an HTTP 2xx status code (200, 201, 204, etc.)
• Responds within 30 seconds

Retry Policy

If webhook delivery fails, Trustist automatically retries:

• Attempt 1: Immediate
• Attempt 2: After 1 second
• Attempt 3: After 3 seconds
• Attempt 4: After 10 seconds

Failure Handling

• 4xx responses (client errors) - Not retried (fix your endpoint)
• 5xx responses (server errors) - Retried automatically
• Network failures - Retried automatically
• Timeouts (>30s) - Retried automatically

Important: Failed Payment Retries

Security Best Practices

Testing Webhooks

Local Development with ngrok

# Install ngrok
npm install -g ngrok

# Start your local server (e.g., port 3000)
node server.js

# Create tunnel in another terminal
ngrok http 3000

# Use the ngrok HTTPS URL in TrustistTransfer settings
# Example: https://abc123.ngrok.io/webhooks/trustist/payments

Webhook Testing Tools

• webhook.site - Get instant webhook URL, inspect payloads
• RequestBin - Collect and inspect HTTP requests
• Hookdeck - Advanced webhook testing with retry and routing

Troubleshooting

Webhooks Not Received

Check:

• Webhook URL is correct and publicly accessible
• Firewall allows incoming connections from Trustist
• SSL certificate is valid (for HTTPS URLs)
• Server is responding with 2xx status codes
• Check webhook delivery logs in TrustistTransfer portal

Duplicate Webhooks

Receiving the same webhook multiple times is expected behavior due to retries. Your handler should be idempotent:

// Check if already processed
const existing = await db.processedWebhooks.findOne({ 
    paymentId: payload.paymentId,
    eventType: payload.eventType 
});

if (existing) {
    console.log('Already processed, skipping');
    return;
}

// Process the webhook
await processPayment(payload);

// Mark as processed
await db.processedWebhooks.create({ 
    paymentId: payload.paymentId,
    eventType: payload.eventType,
    processedAt: new Date()
});

Failed Deliveries

View failed webhook deliveries in the TrustistTransfer portal:

1. Navigate to Settings → API Keys
2. View webhook delivery history
3. Check HTTP status codes and error messages
4. Manually retry failed webhooks if needed

Monitoring & Observability

Best practices for production webhook monitoring:

• Log all webhooks - Keep a record of every webhook received
• Alert on failures - Set up alerts if webhook processing fails
• Track processing time - Monitor how long webhooks take to process
• Monitor duplicate rate - Track how often you receive duplicates
• Check delivery lag - Monitor time between event and webhook receipt

Next Steps

• Return to Getting Started for API overview
• Follow the Quick Start guide to create payments
• View Payment API Reference for endpoint details