Error Handling

Handle payment failures gracefully in your integration.

Error Response Format

{
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Balance is insufficient for this payment",
    "details": {
      "available": 5000,
      "required": 10000
    }
  }
}

Common Error Codes

Code	Description	Action
INSUFFICIENT_BALANCE	Not enough funds in balance	Fund balance
INVALID_RECIPIENT	Recipient not found or inactive	Verify recipient ID
PAYMENT_METHOD_NOT_VERIFIED	Bank account not verified	Wait for verification
RAIL_NOT_AVAILABLE	Requested rail not supported	Use different rail
COMPLIANCE_HOLD	Payment flagged for review	Contact support
RAIL_UNAVAILABLE	Requested rail not available	Use different rail

Payment Failures

Payments can fail at different stages:

Validation Failure

Payment fails validation before processing:

{
  "status": "failed",
  "failureCode": "VALIDATION_ERROR",
  "failureReason": "Recipient has no verified payment methods"
}

Processing Failure

Payment fails during processing:

{
  "status": "failed",
  "failureCode": "BANK_REJECTED",
  "failureReason": "Account closed"
}

Retry Logic

Failed payments can be retried:

curl -X POST https://api.paystream.fi/api/v1/payments/pay_123/retry \
  -H "Authorization: Bearer psk_test_xxx"

Retry rules:

• Max 3 retries per payment
• 24-hour cooldown between retries
• Some failures (e.g., account closed) cannot be retried

Idempotency

Use idempotency keys to prevent duplicate payments:

curl -X POST https://api.paystream.fi/api/v1/payments \
  -H "Authorization: Bearer psk_test_xxx" \
  -H "Idempotency-Key: unique-request-id" \
  -d '{...}'