Payment Status & Lifecycle

{
  "status": "failed",
  "status_details": {
    "message": "The customer's account has insufficient funds to cover this payment.",
    "reason": "insufficient_funds",
    "source": "bank_decline",
    "code": "R01",
    "changed_at": "2024-10-02T14:30:00Z"
  },
  "status_history": [
    {
      "status": "created",
      "message": "Payment successfully created and awaiting verification.",
      "reason": "ok",
      "source": "system",
      "changed_at": "2024-10-01T10:00:00Z"
    },
    {
      "status": "scheduled",
      "message": "Payment successfully validated and scheduled.",
      "reason": "ok",
      "source": "system",
      "changed_at": "2024-10-01T10:05:00Z"
    },
    {
      "status": "pending",
      "message": "Payment successfully originated to network.",
      "reason": "ok",
      "source": "system",
      "changed_at": "2024-10-01T14:00:00Z"
    },
    {
      "status": "failed",
      "message": "The customer's account has insufficient funds.",
      "reason": "insufficient_funds",
      "source": "bank_decline",
      "code": "R01",
      "changed_at": "2024-10-02T14:30:00Z"
    }
  ]
}

async function handleStatusChange(payment) {
  const { status, status_details } = payment;

  switch (status) {
    case 'created':
      // Payment created, awaiting verification
      console.log('Payment created, will be verified soon');
      break;

    case 'scheduled':
      // Passed verification, queued for processing
      console.log('Payment verified and scheduled');
      // Last chance to cancel if needed
      break;

    case 'pending':
      // CRITICAL: Payment sent to network, cannot stop
      console.log('⚠️ Payment sent to network - CANNOT BE STOPPED');
      await notifyPendingPayment(payment);
      break;

    case 'on_hold':
      // Check source to determine if we can release
      if (status_details.source === 'user_action') {
        console.log('User hold - can release when ready');
      } else if (status_details.source === 'watchtower') {
        console.log('Risk hold - cannot release via API');
        await notifyCompliance(payment);
      }
      break;

    case 'paid':
      // Successfully funded
      console.log('✓ Payment successfully funded');
      await fulfillOrder(payment);
      // Note: Can still reverse later
      break;

    case 'failed':
      // Failed before funding
      console.log(`✗ Payment failed: ${status_details.reason}`);
      await handleFailure(payment);
      break;

    case 'reversed':
      // Returned after funding
      console.log(`⚠️ Payment reversed: ${status_details.reason}`);
      await handleReversal(payment);
      break;

    case 'cancelled':
      // Terminated before network submission
      console.log('Payment cancelled');
      break;
  }
}

async function handlePaymentFailure(payment) {
  const { reason, code, source } = payment.status_details;

  // Determine if retry is possible
  const retryableReasons = [
    'insufficient_funds',  // May succeed later with funds
    'duplicate_entry'      // Timing issue, may succeed
  ];

  const nonRetryableReasons = [
    'closed_bank_account',
    'invalid_bank_account',
    'invalid_routing',
    'disputed',
    'payment_stopped',
    'owner_deceased',
    'frozen_bank_account',
    'invalid_paykey',
    'payment_blocked'
  ];

  if (retryableReasons.includes(reason)) {
    // Can retry after addressing issue
    await scheduleRetry(payment);
  } else if (nonRetryableReasons.includes(reason)) {
    // Cannot retry - need new payment method or investigation
    await requestNewPaymentMethod(payment.customer_id);
  }

  // Log return code for reconciliation
  if (code) {
    await logReturnCode(payment.id, code, reason);
  }
}