API-First Payment Infrastructure: A Developer's Guide

Modern payment infrastructure is built API-first, giving developers the flexibility to create custom payment experiences while maintaining security and compliance. Let's explore how to leverage these APIs effectively.

RESTful API Design

A well-designed payment API follows RESTful principles with clear, predictable endpoints. Here's an example of creating a payment intent:

// Create a payment intent
const response = await fetch('https://api.kppay.com/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 5000,
    currency: 'USD',
    payment_method: 'card',
    metadata: {
      order_id: 'order_12345'
    }
  })
});

const payment = await response.json();
console.log('Payment ID:', payment.id);

Webhook Integration

Webhooks enable real-time notifications about payment events. Set up a webhook endpoint to receive updates:

import { Request, Response } from 'express';
import crypto from 'crypto';

export async function handleWebhook(req: Request, res: Response) {
  // Verify webhook signature
  const signature = req.headers['x-kppay-signature'];
  const payload = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(payload)
    .digest('hex');

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

  // Process event
  const event = req.body;

  switch (event.type) {
    case 'payment.succeeded':
      await fulfillOrder(event.data.payment_id);
      break;
    case 'payment.failed':
      await notifyCustomer(event.data.payment_id);
      break;
  }

  res.status(200).send('Webhook received');
}

Error Handling

Robust error handling is crucial. Payment APIs should return clear error codes and messages that help developers diagnose and resolve issues quickly.

Great APIs make complex payment flows simple through thoughtful design and comprehensive documentation.