API Integration for International Payments

Payment APIs enable businesses to automate international payments, integrate with accounting systems, and build custom payment workflows. This technical guide covers everything developers need to know about integrating payment provider APIs.

1. Why Use Payment APIs?

Automation Benefits

• Eliminate manual data entry: Payments created automatically from invoices
• Reduce errors: No typing mistakes or mismatched details
• Save time: Process hundreds of payments in minutes
• Real-time status: Instant payment tracking and notifications

Business Advantages

• Scalability: Handle growing payment volumes without extra staff
• Reconciliation: Automatic matching of payments to invoices
• Cash flow visibility: Real-time balance and transaction data
• Custom workflows: Build processes matching your business needs

2. Common Integration Patterns

Direct Integration

Your application makes API calls directly to the payment provider.

• Best for: Custom applications, high transaction volumes
• Complexity: High - requires development resources
• Control: Full control over user experience and workflow

Middleware Integration

Use platforms like Zapier, Make.com, or custom middleware to connect systems.

• Best for: Connecting existing tools without coding
• Complexity: Medium - configuration rather than coding
• Control: Limited to middleware capabilities

Accounting Software Integration

Native integrations with Xero, QuickBooks, Sage, etc.

• Best for: Standard accounting workflow
• Complexity: Low - usually plug-and-play
• Control: Pre-built features only

3. Key API Capabilities

Core Payment Operations

• Create payments: POST /payments - Initiate transfers
• Get payment status: GET /payments/{id} - Check progress
• List payments: GET /payments - Retrieve payment history
• Cancel payment: DELETE /payments/{id} - Cancel pending transfers

Account Management

• Check balance: GET /accounts/{id}/balance
• Get statement: GET /accounts/{id}/statement
• List currencies: GET /currencies
• Account details: GET /accounts/{id}

Beneficiary Management

• Add beneficiary: POST /beneficiaries
• Validate details: POST /beneficiaries/validate
• List beneficiaries: GET /beneficiaries
• Update beneficiary: PATCH /beneficiaries/{id}

Exchange Rates

• Live rates: GET /rates/{from}/{to}
• Quote: POST /quotes - Get locked-in rate
• Convert currency: POST /conversions

4. Authentication Methods

API Keys

Authorization: Bearer YOUR_API_KEY

• Most common method
• Simple to implement
• Store securely in environment variables
• Rotate keys regularly
• Use different keys for test/production

OAuth 2.0

Authorization: Bearer ACCESS_TOKEN

• More secure for multi-user applications
• Tokens expire and refresh automatically
• Better for customer-facing integrations
• Granular permission scopes

Two-Factor Authentication

• Required for high-value transactions
• SMS or authenticator app confirmation
• Webhook notification when 2FA needed
• Timeout periods for pending approvals

5. Example: Creating a Payment

Step 1: Get Exchange Rate Quote

POST /v1/quotes
{
  "sourceCurrency": "GBP",
  "targetCurrency": "USD",
  "amount": 10000,
  "type": "source"
}

Response:

{
  "id": "quote_abc123",
  "rate": 1.2845,
  "sourceAmount": 10000.00,
  "targetAmount": 12845.00,
  "fee": 5.00,
  "expiresAt": "2024-11-08T10:30:00Z"
}

Step 2: Create Payment

POST /v1/payments
{
  "quoteId": "quote_abc123",
  "beneficiaryId": "ben_xyz789",
  "reference": "Invoice INV-2024-001",
  "reason": "Payment for services"
}

Response:

{
  "id": "pay_def456",
  "status": "pending_approval",
  "createdAt": "2024-11-08T10:25:00Z",
  "estimatedArrival": "2024-11-08T16:00:00Z",
  "requiresApproval": true
}

Step 3: Check Status

GET /v1/payments/pay_def456

Response:

{
  "id": "pay_def456",
  "status": "completed",
  "completedAt": "2024-11-08T15:45:00Z",
  "trackingReference": "FT24110812345"
}

6. Webhook Integration

Why Use Webhooks?

• Get real-time notifications of status changes
• No need to poll API repeatedly
• Immediate response to events
• Reduce API calls and costs

Common Webhook Events

• payment.created: Payment initiated
• payment.approved: Approval received
• payment.processing: Payment in progress
• payment.completed: Payment successful
• payment.failed: Payment failed
• balance.updated: Account balance changed
• beneficiary.verified: Beneficiary details confirmed

Webhook Endpoint Example

POST https://your-domain.com/webhooks/payments
{
  "event": "payment.completed",
  "timestamp": "2024-11-08T15:45:00Z",
  "data": {
    "paymentId": "pay_def456",
    "status": "completed",
    "amount": 12845.00,
    "currency": "USD"
  }
}

Security Best Practices

• Verify signatures: Check HMAC signature header
• Use HTTPS: Always use secure endpoints
• Validate payload: Check event data matches expected format
• Idempotency: Handle duplicate webhooks gracefully
• Quick response: Return 200 OK within 5 seconds

7. Error Handling

HTTP Status Codes

• 200 OK: Request successful
• 201 Created: Resource created successfully
• 400 Bad Request: Invalid request data
• 401 Unauthorized: Invalid or missing API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource doesn't exist
• 422 Unprocessable: Validation error
• 429 Too Many Requests: Rate limit exceeded
• 500 Server Error: Provider system error

Error Response Format

{
  "error": {
    "code": "insufficient_funds",
    "message": "Account balance too low for this payment",
    "details": {
      "required": 10005.00,
      "available": 9500.00,
      "currency": "GBP"
    }
  }
}

Retry Strategy

• Don't retry 400-level errors: Fix request first
• Retry 500-level errors: Temporary provider issues
• Exponential backoff: Wait 1s, 2s, 4s, 8s between retries
• Max retries: Stop after 3-5 attempts
• Idempotency keys: Prevent duplicate payments

8. Rate Limiting

Typical Limits

• Read operations: 100-1000 requests/minute
• Write operations: 10-100 requests/minute
• Payment creation: 10-50 requests/minute
• Bulk operations: Special limits apply

Handling Rate Limits

• Check X-RateLimit-Remaining header
• Use Retry-After header value
• Implement queue system for high volumes
• Batch operations where supported
• Cache data to reduce API calls

9. Testing

Sandbox Environment

• Separate API keys for testing
• Test data doesn't affect production
• Simulate various scenarios
• No real money involved

Test Scenarios

• Successful payment: End-to-end happy path
• Insufficient funds: Error handling
• Invalid beneficiary: Validation errors
• Rate changes: Quote expiration
• Webhook delivery: Event processing
• 2FA flow: Approval workflow

10. Production Checklist

Security

• □ API keys stored in environment variables (not code)
• □ HTTPS for all API calls
• □ Webhook signature verification implemented
• □ IP whitelist configured if supported
• □ Separate test/production keys

Error Handling

• □ All error responses logged
• □ Retry logic with backoff
• □ Idempotency keys on payment creation
• □ Timeout handling (30-60 seconds)
• □ Dead letter queue for failed webhooks

Monitoring

• □ API response time tracking
• □ Error rate monitoring
• □ Webhook delivery success rate
• □ Alert on payment failures
• □ Daily reconciliation process

Compliance

• □ Audit log all API operations
• □ Store payment records per regulations
• □ PCI compliance if handling card data
• □ GDPR compliance for customer data
• □ KYC/AML checks before payments

Key Takeaways

• APIs automate payment workflows and reduce manual work
• Webhooks provide real-time status updates efficiently
• Error handling and retries are essential for reliability
• Security measures protect sensitive financial operations
• Testing thoroughly in sandbox before production
• Monitor and log all API interactions for troubleshooting

Next Step: Review payment provider API documentation and start with a simple integration in their sandbox environment.