Transaction Statuses

This guide explains each transaction status in detail, including when they occur, how to handle them, and what actions are available.

Status Overview

Card transactions can be in one of four states:

Status	Description	When It Occurs	Can Be Changed To
pending	Transaction authorized but not captured	Immediately after authorization	`posted`, `declined`, or `void`
posted	Transaction captured and finalized	After capture (typically automatic)	`refunded` (via new refund transaction)
declined	Authorization failed	Authorization rejected	None (final state)
void	Authorization reversed	Authorization cancelled before capture	None (final state)

Status Transitions

Normal Flow

Typical Flow:

Authorization → Transaction status: pending
Capture (automatic) → Transaction status: posted
Refund (if needed) → New transaction with intent: "refund"

Failure Scenarios

Pending Transactions

Status: pending Pending transactions represent authorized but not yet captured transactions.

Characteristics

Funds Status: Funds are held but not transferred
Reversibility: Can be reversed (voided) before capture
Capture Timing: Automatically captured after authorization (typically within seconds)
postedAt Field: null until captured
Amount: May change while pending (e.g., tip adjustments)

When It Occurs

Immediately after successful authorization
Before capture completes
During tip adjustment period (for certain transaction types)

Use Cases

Monitor pending authorizations
Detect potential fraud before capture
Reverse unauthorized transactions
Track authorization holds

Example Response

{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "pending",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": null,
  "authorization": {
    "id": "auth_abc123",
    "amount": 50.00
  }
}

Actions Available

Monitor: Query transactions with status=pending
Void: Reverse the authorization (if needed)
Wait: Allow automatic capture to proceed

Posted Transactions

Status: posted Posted transactions are finalized and funds have been settled.

Characteristics

Funds Status: Funds have been transferred
Reversibility: Cannot be reversed (only refunded)
Finality: Transaction details are final
postedAt Field: Contains capture timestamp
Amount: Final and cannot change

When It Occurs

After successful capture
Typically automatic after authorization
When funds are settled

Use Cases

Generate statements
Calculate balances
Process refunds
Accounting reconciliation
Compliance reporting

Example Response

{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "posted",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": "2025-01-15T10:30:05Z",
  "authorization": {
    "id": "auth_abc123",
    "amount": 50.00
  }
}

Actions Available

Refund: Create a refund transaction
Report: Include in statements and reports
Monitor: Track for disputes or issues

Declined Transactions

Status: declined Declined transactions failed authorization.

Characteristics

Funds Status: No funds held or transferred
Finality: Cannot be changed or retried
Reason: Declined for specific reason (see below)
postedAt Field: null

Common Reasons

Reason	Description
Insufficient Balance	Card account doesn’t have enough funds
Card Suspended	Card is temporarily blocked
Card Cancelled	Card has been permanently cancelled
Spending Limit Exceeded	Transaction exceeds card or account limits
Card Expired	Card expiration date has passed
Invalid PIN/CVV	Incorrect authentication credentials
Fraud Detection	Transaction flagged by fraud system
Restricted Merchant	Merchant or category is blocked

When It Occurs

During authorization request
Before any funds are held
Immediately after authorization attempt

Use Cases

Monitor decline rates
Identify card issues
Alert cardholders
Fraud detection
Improve authorization rates

Example Response

{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "declined",
  "amount":  Reason": "insufficient_balance",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "postedAt": null
}

Actions Available

Monitor: Track decline rates and reasons
Alert: Notify cardholder of issue
Investigate: Review card account status
Resolve: Fix underlying issue (fund account, unsuspend card, etc.)

Void Transactions

Status: void Void transactions are authorizations that were reversed before capture.

Characteristics

Funds Status: Funds were released back to card account
Transfer: No funds were transferred
Refundability: Cannot be refunded (nothing was captured)
Timing: Must occur before capture

When It Occurs

Authorization reversed before capture
Manual void by issuer
System-initiated reversal
Authorization timeout/expiry

Use Cases

Reverse mistaken authorizations
Cancel pending transactions
Release held funds
Handle authorization errors

Example Response

{
  "id": "8188d920-2c17-4aba-aa24-6a25f8c12ddb",
  "status": "void",
  "amount": -50.00,
  "createdAt": "2025-01-15T10:30:00Z",
  "voidedAt": "2025-01-15T10:30:02Z",
  "postedAt": null
}

Actions Available

Monitor: Track voided transactions
Verify: Confirm funds were released
Report: Include in reconciliation

Status Comparison

Aspect	pending	posted	declined	void
Funds Held	Yes	No (transferred)	No	No (released)
Funds Transferred	No	Yes	No	No
Can Reverse	Yes (void)	No	N/A	N/A
Can Refund	No	Yes	No	No
postedAt	`null`	Timestamp	`null`	`null`
Final	No	Yes	Yes	Yes

Best Practices

1. Monitor Status Transitions

Set up alerts for unexpected status transitions: Concept:

Query transactions with status=pending and a time threshold
Alert if transactions remain pending longer than expected
Investigate long-pending transactions for potential issues

Endpoint: GET /v1/cardaccounts/transactions Query Parameters:

status: pending
dateRangeFrom: Threshold time (e.g., 1 hour ago)

Example:

curl "https://access.utgl.io/v1/cardaccounts/transactions?cardAccountId=YOUR_ID&status=pending&dateRangeFrom=2025-01-15T09:30:00Z" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Monitoring Strategy:

Set up scheduled queries for pending transactions
Alert when transactions exceed expected pending duration
Review transaction details for investigation

2. Handle Each Status Appropriately

pending: Monitor for fraud, allow capture to proceed
posted: Include in statements, process refunds if needed
declined: Investigate reason, alert cardholder
void: Verify funds released, update records

3. Track Status Changes

Use webhooks to receive real-time status updates:

cardaccount.transaction.created - New transaction (status: pending)
cardaccount.transaction.posted - Transaction captured (status: posted)
cardaccount.transaction.declined - Transaction declined
cardaccount.transaction.void - Transaction voided

Next Steps

Transaction Lifecycle - Overview of transaction flow
Webhooks Guide - Set up status change notifications
API Reference - Explore transaction endpoints

Card Issuing

Transaction Management

Webhooks

Transaction Statuses

Transaction Statuses

Status Overview

Status Transitions

Normal Flow

Failure Scenarios

Pending Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Posted Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Declined Transactions

Characteristics

Common Reasons

When It Occurs

Use Cases

Example Response

Actions Available

Void Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Status Comparison

Best Practices

1. Monitor Status Transitions

2. Handle Each Status Appropriately

3. Track Status Changes

Next Steps

Card Issuing

Transaction Management

Webhooks

​Transaction Statuses

​Status Overview

​Status Transitions

​Normal Flow

​Failure Scenarios

​Pending Transactions

​Characteristics

​When It Occurs

​Use Cases

​Example Response

​Actions Available

​Posted Transactions

​Characteristics

​When It Occurs

​Use Cases

​Example Response

​Actions Available

​Declined Transactions

​Characteristics

​Common Reasons

​When It Occurs

​Use Cases

​Example Response

​Actions Available

​Void Transactions

​Characteristics

​When It Occurs

​Use Cases

​Example Response

​Actions Available

​Status Comparison

​Best Practices

​1. Monitor Status Transitions

​2. Handle Each Status Appropriately

​3. Track Status Changes

​Next Steps

Transaction Statuses

Status Overview

Status Transitions

Normal Flow

Failure Scenarios

Pending Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Posted Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Declined Transactions

Characteristics

Common Reasons

When It Occurs

Use Cases

Example Response

Actions Available

Void Transactions

Characteristics

When It Occurs

Use Cases

Example Response

Actions Available

Status Comparison

Best Practices

1. Monitor Status Transitions

2. Handle Each Status Appropriately

3. Track Status Changes

Next Steps