Payment status and lifecycle reference

Understanding payment statuses is critical for properly handling charges and payouts. Every payment moves through a defined lifecycle with specific status transitions. Knowing when payments can be modified—or when they become unstoppable—directly impacts your application’s payment logic and user experience.

What This Reference Covers

This comprehensive guide provides everything you need to handle payment statuses correctly:

Status lifecycles: The complete flow from creation to terminal states
The pending threshold: Why pending status is the point of no return
Failed vs reversed: Critical distinction between pre-funding and post-funding failures
ACH return codes: All R-codes and S-codes with their meanings and timing
Status reasons: Complete catalog of failure reasons and their sources
Status/Source/Reason matrix: Valid combinations showing what actually occurs
Implementation patterns: Code examples for monitoring and handling status changes

Whether you’re building retry logic, handling disputes, or reconciling returns, this reference ensures you respond appropriately to every payment state.

Payment Lifecycle Overview

The happy path for payments follows this progression:

Created

Payment successfully created and awaiting verification

Scheduled

Payment passed verifications and risk scoring, queued for processing

Pending

Payment sent to network - CANNOT BE STOPPED

Paid

Payment successfully funded

Critical Understanding: Once a payment reaches pending status, it has been submitted to the payment network and cannot be stopped, held, or cancelled. The payment must complete its network processing.

Status Values

Complete Status Reference

Status	Description	Can Modify?	Terminal?
`created`	Payment created, awaiting verification	✅	No
`scheduled`	Verified and queued for processing	✅	No
`pending`	Sent to network	❌	No
`on_hold`	Paused for review	✅*	No
`paid`	Successfully funded	❌	No†
`failed`	Declined/returned before funding	❌	Yes
`reversed`	Returned after funding completed	❌	Yes
`cancelled`	Terminated before network submission	❌	Yes

*Only user-initiated holds can be released by the user; Watchtower holds require Straddle authorization
†Can still transition to reversed if return occurs post-funding

Understanding Failed vs Reversed

Status	When It Occurs	Money Movement	Example
`failed`	Before funding completes	Funds deposited in your account	NSF during processing
`reversed`	After funding completes	Funds deposited then withdrawn from your account	Dispute filed after payment

Status Sources

Sources identify where status changes originate:

Source	Description	When Used
`system`	Automated system processing	Normal status progression (created → scheduled → pending → paid)
`watchtower`	Internal fraud/risk system	Balance checks, fraud screening, validation failures
`bank_decline`	ACH network return	Returns from banks
`customer_dispute`	Customer disputed with their bank	Unauthorized claims (R05, R07, R10, R11, R29)
`user_action`	Manual action via API	User-initiated holds, cancels, releases

Status/Source/Reason Matrix

Success States

Status	Source	Reason	Context
`created`	`system`	`ok`	Payment created and awaiting verification
`scheduled`	`system`	`ok`	Payment validated and scheduled
`pending`	`system`	`ok`	Payment submitted to ACH network
`paid`	`system`	`ok`	Payment successfully funded

Hold States

Status	Source	Reason	Context
`on_hold`	`watchtower`	`risk_review`	Flagged by risk system (paykey or customer under review)
`on_hold`	`watchtower`	`amount_too_large`	Exceeds max transaction or daily limits
`on_hold`	`user_action`	`user_request`	Manually held by user via API

Failed States (Pre-Funding)

Status	Source	Reason	Context
`failed`	`watchtower`	`insufficient_funds`	Pre-submission balance check detected insufficient funds
`failed`	`watchtower`	`payment_blocked`	Blocked by Straddle fraud screening
`failed`	`watchtower`	`invalid_paykey`	Paykey validation failed (blocked, restricted, or customer not found)
`failed`	`watchtower`	`payment_stopped`	Payment rail assignment failed
`failed`	`watchtower`	`duplicate_entry`	Duplicate payment detected during ID assignment
`failed`	`bank_decline`	`insufficient_funds`	ACH return R01/R09
`failed`	`bank_decline`	`closed_bank_account`	ACH return R02
`failed`	`bank_decline`	`invalid_bank_account`	ACH return R03/R04/R20
`failed`	`bank_decline`	`invalid_routing`	ACH return R13
`failed`	`bank_decline`	`frozen_bank_account`	ACH return R16
`failed`	`bank_decline`	`owner_deceased`	ACH return R14/R15
`failed`	`bank_decline`	`payment_stopped`	ACH return R08
`failed`	`bank_decline`	`payout_refused`	ACH return R23
`failed`	`bank_decline`	`duplicate_entry`	ACH return R24
`failed`	`bank_decline`	`other_network_return`	Other ACH return codes
`failed`	`customer_dispute`	`disputed`	ACH return R05/R07/R10/R11/R29 (before funding)
`failed`	`user_action`	`user_request`	Manually failed by user via API

Reversed States (Post-Funding)

Status	Source	Reason	Context
`reversed`	`bank_decline`	`insufficient_funds`	Late ACH return R01/R09
`reversed`	`bank_decline`	`closed_bank_account`	Late ACH return R02
`reversed`	`bank_decline`	`invalid_bank_account`	Late ACH return R03/R04/R20
`reversed`	`bank_decline`	`invalid_routing`	Late ACH return R13
`reversed`	`bank_decline`	`frozen_bank_account`	Late ACH return R16
`reversed`	`bank_decline`	`owner_deceased`	Late ACH return R14/R15
`reversed`	`bank_decline`	`payment_stopped`	Late ACH return R08
`reversed`	`bank_decline`	`payout_refused`	Late ACH return R23
`reversed`	`bank_decline`	`duplicate_entry`	Late ACH return R24
`reversed`	`bank_decline`	`other_network_return`	Other late ACH returns
`reversed`	`customer_dispute`	`disputed`	ACH return R05/R07/R10/R11/R29 (after funding)

Cancelled States

Status	Source	Reason	Context
`cancelled`	`user_action`	`user_request`	Manually cancelled by user via API

Cancellation only occurs via user action in the dashboard or API

Resubmit Failed Payments

Retry any failed, reversed, or cancelled charge or payout by creating a new payment linked to the original. The new payment carries over the original bank information and payment details. Optional: provide a new payment_date, description, or external_id. Otherwise, Straddle generates these from the original payment. The new payment inherits the amount, paykey, currency, and metadata from the original. Each payment can only be resubmitted once, but if a resubmitted payment also fails, resubmit that one to create a chain. Resubmit a charge with an updated payment date and description.

curl -X POST https://api.straddle.com/v1/charges/{id}/resubmit \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "payment_date": "2026-03-01",
       "description": "Customer requested retry after payday",
       "external_id": "my-custom-external-id"
     }'

Refund Paid Charges

Return funds to a customer for a paid charge directly from the dashboard or API. The refund is sent back to the customer’s original bank account using the same paykey as the source charge, so there’s no manual lookup or destination-account work. To issue a refund from the dashboard, see the step-by-step walkthrough in the help center. Each charge can be refunded once, full or partial. The refund amount must be greater than $0 and no more than the original charge amount. When you create a refund:

A new payout is created with payment_type: "payout" and a description of Refund for Charge ID: {id}. If you supplied your own description, it’s appended after the system prefix.
The original charge stays in Paid status. Refunds are tracked separately as payouts and linked through related_payments.
The new refund payout follows normal payout statuses (Pending → Paid).

curl -X POST https://api.straddle.com/v1/charges/{id}/refund \
     -H "Authorization: Bearer YOUR_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "amount": 5000,
       "description": "Customer returned damaged item"
     }'

After a refund, the original charge’s related_payments lists the new refund payout, and the refund payout’s related_payments lists the source charge. Each entry includes the linked payment’s id, relationship, and payment_type. Relationship values:

original: the linked payment is the source. Appears on the refund payout, pointing back to the charge.
refund: the linked payment is a refund. Appears on the original charge, pointing to the new refund payout.

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "related_payments": [
    {
      "id": "019e1bab-2ab4-751d-be80-f51c82c2ea64",
      "relationship": "original",
      "payment_type": "charge"
    }
  ]
}

Since a refund is created as a payout, the standard payout.* webhook events fire for the refund lifecycle. Existing payout handlers track refunds without changes.

When You Can’t Refund

The charge is not in paid status. Use Resubmit for failed, reversed, or cancelled charges.
The charge has already been refunded. Each charge can have one refund; check related_payments before retrying.
Two requests reach the API at the same time. Straddle uses optimistic concurrency to prevent duplicate refunds — one request succeeds, the other gets a 422 with a clear message.

Important: Same Reason, Different Sources

Some reason codes can originate from different sources depending on when they’re detected:

`insufficient_funds`

Source	When Detected	Description
`watchtower`	Pre-submission	Balance check via Plaid detected insufficient funds before network submission
`bank_decline`	Post-submission	ACH network returned R01/R09 after payment was submitted to bank

Key distinction:

Watchtower: Proactive check using real-time balance data — payment never leaves Straddle
Bank Decline: Reactive return from the ACH network after the payment was sent

Status Reasons

Active Reason Codes

These reason codes are actively used by the system:

Reason Code	Description	Sources
`ok`	Normal/successful status	`system`
`insufficient_funds`	Customer’s account has insufficient funds	`watchtower`, `bank_decline`
`closed_bank_account`	Bank account is closed	`bank_decline`
`invalid_bank_account`	Account cannot be located or is invalid	`bank_decline`
`invalid_routing`	Invalid ACH routing number	`bank_decline`
`frozen_bank_account`	Account frozen or OFAC hold	`bank_decline`
`owner_deceased`	Account owner is deceased	`bank_decline`
`disputed`	Customer notified bank payment was unauthorized	`customer_dispute`
`payment_stopped`	Customer placed stop payment order	`watchtower`, `bank_decline`
`risk_review`	Payment under review by Straddle	`watchtower`
`payment_blocked`	Blocked by fraud screening	`watchtower`
`invalid_paykey`	Paykey blocked due to previous failures	`watchtower`
`amount_too_large`	Exceeds maximum allowed amount	`watchtower`
`duplicate_entry`	Duplicate transaction detected	`watchtower`, `bank_decline`
`user_request`	User-requested action	`user_action`
`other_network_return`	Other network return codes	`bank_decline`
`payout_refused`	Receiver refused credit	`bank_decline`

ACH Return Codes

Standard ACH Returns (R-Codes)

Code	Reason	Message
R01	`insufficient_funds`	The customer’s account has insufficient funds
R09	`insufficient_funds`	Uncollected funds
R02	`closed_bank_account`	The bank account is closed
R03	`invalid_bank_account`	The bank account could not be located
R04	`invalid_bank_account`	Bank account number invalid (missing digits)
R13	`invalid_routing`	Invalid ACH routing number
R20	`invalid_bank_account`	Account not eligible for transaction activity
R05	`disputed`	Debit to consumer account using corporate consent
R07	`disputed`	Authorization revoked by customer
R10	`disputed`	Customer advises not authorized
R11	`disputed`	Check truncation entry return
R29	`disputed`	Corporate customer notified bank unauthorized
R08	`payment_stopped`	Customer placed stop payment order
R14	`owner_deceased`	Representative payee deceased
R15	`owner_deceased`	Beneficiary/account holder deceased
R16	`frozen_bank_account`	Account frozen or OFAC hold
R23	`payout_refused`	Receiver refused credit
R24	`duplicate_entry`	Duplicate entry
R06+	`other_network_return`	Various other return reasons

Straddle Internal Codes (S-Codes)

Code	Reason	Message	When Applied
S01	`payment_blocked`	Invalid routing number	Pre-origination
S02	`payment_blocked`	Known bad account number	Pre-origination
S10	`payment_blocked`	Invalid account number	Pre-origination
S11	`payment_blocked`	Previous R02, R03, R04, R16, or R20	Pre-origination
S12	`payment_blocked`	Previous R05, R07, R08, R10, R11, or R29	Pre-origination
S13	`payment_blocked`	Invalid ODFI credentials	Pre-origination

Status Details Structure

Every payment includes detailed status information:

{
  "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"
    }
  ]
}

Handling Status Changes

Monitoring for Status Changes

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;
  }
}

Handling Specific Failure Reasons

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);
  }
}

Common Scenarios

Successful Payment Flow

created → system / ok - Payment initialized
scheduled → system / ok - Verification passed, risk approved
pending → system / ok - Sent to ACH network
paid → system / ok - Funds successfully transferred

Pre-Submission Balance Check Failure

created → system / ok
Balance check detects insufficient funds
failed → watchtower / insufficient_funds
No money moved, payment never sent to bank

NSF After Submission (ACH Return)

created → scheduled → pending
Bank returns with R01
failed → bank_decline / insufficient_funds / code: R01
No money moved (failed before funding)

Dispute After Funding

created → scheduled → pending → paid
Customer disputes with their bank
Bank sends R10 return
reversed → customer_dispute / disputed / code: R10
Money was moved, then returned

Risk Hold and Release

created → system / ok - Payment initialized
Watchtower flags for review
on_hold → watchtower / risk_review
Manual review in dashboard
If approved: released → scheduled → normal flow
If declined: → failed or cancelled

User-Initiated Hold

created → system / ok
User calls hold API
on_hold → user_action / user_request
User can release when ready
Released → continues processing

Best Practices

Monitor Pending Status

Once pending, payments cannot be stopped. Plan accordingly.

Check Both Source and Reason

The same reason can come from different sources with different implications.

Handle Failed vs Reversed

Different workflows for pre-funding failures vs post-funding reversals.

Track Return Codes

Log ACH return codes for reconciliation and pattern analysis.

Next Steps

Webhook Events

Set up real-time status notifications

Testing Statuses

Test various status scenarios in sandbox

Charges Guide

Learn about charge-specific flows

Payouts Guide

Understand payout-specific scenarios

​What This Reference Covers

​Payment Lifecycle Overview

​Status Values

​Complete Status Reference

​Understanding Failed vs Reversed

​Status Sources

​Status/Source/Reason Matrix

​Success States

​Hold States

​Failed States (Pre-Funding)

​Reversed States (Post-Funding)

​Cancelled States

​Resubmit Failed Payments

​Refund Paid Charges

​When You Can’t Refund

​Important: Same Reason, Different Sources

​insufficient_funds

​Status Reasons

​Active Reason Codes

​ACH Return Codes

​Standard ACH Returns (R-Codes)

​Straddle Internal Codes (S-Codes)

​Status Details Structure

​Handling Status Changes

​Monitoring for Status Changes

​Handling Specific Failure Reasons

​Common Scenarios

​Successful Payment Flow

​Pre-Submission Balance Check Failure

​NSF After Submission (ACH Return)

​Dispute After Funding

​Risk Hold and Release

​User-Initiated Hold

​Best Practices

Monitor Pending Status

Check Both Source and Reason

Handle Failed vs Reversed

Track Return Codes

​Next Steps

Webhook Events

Testing Statuses

Charges Guide

Payouts Guide

What This Reference Covers

Payment Lifecycle Overview

Status Values

Complete Status Reference

Understanding Failed vs Reversed

Status Sources

Status/Source/Reason Matrix

Success States

Hold States

Failed States (Pre-Funding)

Reversed States (Post-Funding)

Cancelled States

Resubmit Failed Payments

Refund Paid Charges

When You Can’t Refund

Important: Same Reason, Different Sources

`insufficient_funds`

Status Reasons

Active Reason Codes

ACH Return Codes

Standard ACH Returns (R-Codes)

Straddle Internal Codes (S-Codes)

Status Details Structure

Handling Status Changes

Monitoring for Status Changes

Handling Specific Failure Reasons

Common Scenarios

Successful Payment Flow

Pre-Submission Balance Check Failure

NSF After Submission (ACH Return)

Dispute After Funding

Risk Hold and Release

User-Initiated Hold

Best Practices

Next Steps