Payment Components

Payments in MoneyHash are composed of several interrelated entities. Understanding these components and their roles will help you manage payments effectively and build reliable payment flows.

1. Intent

An Intent is your starting point and represents a payment session mapped directly to your internal payment record. It maintains context and orchestrates multiple payment attempts (transactions).

Intent's Role

• Context Management: Stores initial and ongoing information (card tokens, billing data, customer IDs, 3DS authentication data).
• Multiple Attempts: Supports retries and alternate payment methods without requiring customers to re-enter data.

Intent Lifecycle Statuses

• Unprocessed: Initial status upon creation. Remains until a transaction succeeds, or the intent is manually closed or expires.
• Processed: Achieved after a successful payment attempt. No further payment attempts allowed.
• Closed: Manually terminated intent without a successful transaction. No further attempts allowed, any pending attempt will be transitioned to failed. Please read more about closing intents possible side effects here
• Expired: Automatically terminated after exceeding the configured time limit. No further attempts allowed, any pending attempt will be transitioned to failed. Please read more about expiring intents possible side effects here

2. Transaction

A Transaction is a single payment attempt within an Intent. Each retry, new payment method, or provider switch creates a new Transaction. Transactions handle specific details of each financial action.

Transactions become the primary entity after successful payment authorization and enable subsequent financial operations such as refunds or voids.

3. Operation

An Operation represents a financial action (authorize, capture, refund, void) performed within a Transaction. Operations define the exact sequence of financial steps executed during a Transaction's lifecycle.

4. Payment Status

The payment_status is a simplified high-level indicator reflecting the monetary outcome of a payment (e.g., authorized, captured, refunded). It differs from Intent and Transaction statuses, which focus on the payment process rather than the final monetary state.

payment_status is a field that will exist in all Intent, transaction, operation related response, webhooks.. which will always keep you in the loop about your payment.

{
    "payment_status": {
        "status": "AUTHORIZE_ATTEMPT_FAILED",
        "balances": {
            "total_authorized": "0",
            "total_voided": 0,
            "available_to_void": "0",
            "total_captured": "0",
            "available_to_capture": "0",
            "total_refunded": 0,
            "available_to_refund": "0"
        }
    }
}

Payment Status Reference Table

How MoneyHash Simplifies Status Management

MoneyHash internally manages a detailed composite status system. To simplify integration and provide clarity:

• A high-level payment_status clearly shows the financial outcome.
• Detailed statuses for operations and transactions are available through APIs, webhooks, SDKs, and dashboards for granular insights.
• Partial capture and refund details can be obtained from the balances field.

Understanding the Balances Field

The balances object tracks monetary amounts for different payment operations. It helps you determine if captures, voids, or refunds are full or partial.

Balance Types

• total_authorized: Total amount successfully authorized for the payment
• total_voided: Total amount that has been successfully voided
• available_to_void: Amount still available to void from authorization
• total_captured: Total amount successfully captured from authorization
• available_to_capture: Remaining amount available to capture
• total_refunded: Total amount successfully refunded from captured amount
• available_to_refund: Remaining amount available to refund

This breakdown allows your system to accurately track and handle complex financial transactions, clearly distinguishing between fully and partially completed actions without the need for manual reconciliation.

Summary

• Intent: Manages payment context and retries.
• Transaction: Represents individual payment attempts within an intent.
• Operation: Financial actions within transactions (authorize, capture, refund).
• payment_status: High-level monetary outcome indicator.

This structured framework provides both simplicity and depth, allowing you to manage payments efficiently and reliably.