capture Method

Overview

The capture method finalizes an authorized payment by transferring the reserved funds from the customer's account to your merchant account. This completes the payment lifecycle after a successful authorization.

Business Use Case: An e-commerce order has shipped. The customer's payment was authorized at checkout, and now that the order is on its way, you capture the funds to complete the transaction.

Purpose

Why use capture?

Scenario	Benefit
E-commerce fulfillment	Charge customers only when orders ship
Hotel checkout	Capture final bill amount at check-out
Service completion	Bill after service is rendered
Partial shipments	Capture only what was actually shipped

Key outcomes:

• Funds transfer from customer to merchant
• Payment reaches CAPTURED status
• Transaction proceeds to settlement

Request Fields

Field	Type	Required	Description
merchant_transaction_id	string	Yes	Your unique transaction reference
connector_transaction_id	string	Yes	The connector's transaction ID from authorize
amount	Money	No	Amount to capture (can be partial)
description	string	No	Description for customer's statement
metadata	dict	No	Additional data (max 20 keys)

Response Fields

Field	Type	Description
merchant_transaction_id	string	Your transaction reference (echoed back)
connector_transaction_id	string	Connector's transaction ID
status	PaymentStatus	Current status: CAPTURED, PENDING, FAILED
captured_amount	int64	Amount captured in minor units
error	ErrorInfo	Error details if status is FAILED
status_code	int	HTTP-style status code (200, 402, etc.)

Example

SDK Setup

from orchestratorx_prism import PaymentClient

payment_client = PaymentClient(
    connector='stripe',
    api_key='YOUR_API_KEY',
    environment='SANDBOX'
)

Request

request = {
    "merchant_transaction_id": "txn_order_001",
    "connector_transaction_id": "pi_3Oxxx...",
    "amount": {
        "minor_amount": 1000,
        "currency": "USD"
    },
    "description": "Order shipment #12345"
}

response = await payment_client.capture(request)

Response

{
    "merchant_transaction_id": "txn_order_001",
    "connector_transaction_id": "pi_3Oxxx...",
    "status": "CAPTURED",
    "captured_amount": 1000,
    "status_code": 200
}

Common Patterns

Two-Step Payment Flow

sequenceDiagram
    participant App as Your App
    participant CS as Prism
    participant PP as Payment Provider

    Note over App: Customer places order
    App->>CS: 1. authorize payment
    CS->>PP: Reserve funds
    PP-->>CS: Return: AUTHORIZED
    CS-->>App: Confirm authorization
    Note over App: Order ships
    App->>CS: 2. capture payment
    CS->>PP: Transfer funds
    PP-->>CS: Return: CAPTURED
    CS-->>App: Confirm capture

Flow Explanation:

1. Authorize - Reserve funds at checkout to verify payment method.

2. Fulfill - Process and ship the order.

3. Capture - Transfer funds when order ships.

Partial Capture

Capture less than the authorized amount:

# Authorized for $100, capture only $75
request = {
    "merchant_transaction_id": "txn_order_001",
    "connector_transaction_id": "pi_3Oxxx...",
    "amount": {
        "minor_amount": 7500,  # $75.00
        "currency": "USD"
    }
}

The remaining $25 is automatically released back to the customer.

Error Handling

Error Code	Meaning	Action
402	Capture failed	Authorization expired or insufficient funds
404	Transaction not found	Verify connector_transaction_id
409	Already captured	Idempotent - already captured successfully

Next Steps

• authorize - Create initial authorization
• void - Cancel authorization instead of capturing
• refund - Return funds after capture