Execute Order

curl --request POST \
  --url https://api.finhub.cloud/api/v2.1/fintrans/wal_abc123def456/types/transfer/execute \
  --header 'Authorization: Bearer CUSTOMER_TOKEN' \
  --header 'X-Tenant-ID: fh_api_finsei_ltd_7f957f77' \
  --header 'X-Session-Id: cust_sess_xyz789' \
  --header 'Content-Type: application/json' \
  --data '{
    "preparedOrderId": "prep_order_xyz123abc456",
    "authenticationCode": "123456",
    "consentConfirmation": {
      "consentId": "consent-payment-abc123",
      "confirmed": true,
      "timestamp": "2025-01-23T13:00:00.000Z",
      "channel": "WEB",
      "signature": "customer_confirmed_via_web_interface"
    }
  }'
```text`n## Example Response

```json
{
  "data": {
    "transactionId": "txn_def456ghi789",
    "orderId": "ord_abc123xyz456",
    "status": "COMPLETED",
    "executedAt": "2025-01-23T13:00:05.000Z",
    "amount": {
      "value": "100.00",
      "currency": "EUR"
    },
    "fees": {
      "total": "1.50"
    },
    "balances": {
      "before": {
        "available": "15000.00",
        "current": "15000.00"
      },
      "after": {
        "available": "14898.50",
        "current": "14898.50"
      }
    }
  }
}
```text`n## Consent Confirmation

For operations requiring consent, the confirmation must include:

1. **Valid Consent ID** - From payment consent creation
2. **Explicit Confirmation** - `confirmed: true`
3. **Timestamp** - When customer confirmed
4. **Channel** - How confirmation was obtained

### Example Consent Confirmation

```javascript
const consentConfirmation = {
  consentId: paymentConsentId,
  confirmed: true,
  timestamp: new Date().toISOString(),
  channel: "WEB",
  signature: "customer_confirmed_via_web_interface"
};
```text`n## Authentication Requirements

<Warning>
  This endpoint requires the **customer's** authentication token, not the admin token. The customer must be logged in to execute transactions.
</Warning>

```javascript
// Use customer token for execution
const headers = {
  'Authorization': `Bearer ${customerToken}`,  // NOT adminToken
  'X-Tenant-ID': tenantId,
  'X-Session-Id': customerSessionId
};
```text`n## Transaction States

| Status | Description | Next Actions |
|--------|-------------|--------------|
| COMPLETED | Transaction successful | None required |
| PENDING | Awaiting processing | Check status |
| PROCESSING | Being processed | Wait and check status |
| FAILED | Transaction failed | Review error, retry |

## Balance Updates

The three-balance model ensures accurate tracking:

```json
{
  "balances": {
    "available": "14898.50",  // Reduced by amount + fees
    "current": "14898.50",    // Book balance updated
    "locked": "0.00"          // Released after execution
  }
}
```text`n## High-Value Transaction Execution

For amounts above €10,000:

```json
{
  "preparedOrderId": "prep_order_highvalue_123",
  "supportingDocuments": [
    "doc_proof_of_funds_123",
    "doc_bank_statement_456",
    "doc_income_verification_789"
  ],
  "consentConfirmation": {
    "consentId": "consent-payment-highvalue",
    "confirmed": true,
    "timestamp": "2025-01-23T13:00:00.000Z",
    "channel": "WEB",
    "signature": "enhanced_verification_completed"
  }
}
```text`n## Error Handling

| Error Code | Description | Resolution |
|------------|-------------|------------|
| 401 | Invalid customer token | Customer must log in |
| 403 | Consent not confirmed | Provide valid confirmation |
| 404 | Prepared order not found | Check order ID |
| 409 | Order expired | Prepare new order |
| 422 | Invalid consent | Check consent validity |

## Idempotency

Execute requests are idempotent within the prepared order validity period:
- Multiple executions with same `preparedOrderId` return the same result
- Prevents duplicate transactions
- Safe to retry on network errors

## PowerShell Script Example

```powershell
# Execute prepared orders
foreach ($preparedOrder in $preparedOrders) {
    try {
        # Use fintrans API endpoint  
        $executeUrl = "$baseUrl/api/v2.1/fintrans/$walletId/types/transfer/execute"
        
        # Build execution body
        $executeBody = @{
            preparedOrderId = $preparedOrder.orderId
            authenticationCode = "123456"  # In production, get from user
            consentConfirmation = @{
                consentId = $paymentConsentId
                confirmed = $true
                timestamp = (Get-Date -Format "yyyy-MM-ddTHH:mm:ss.fffZ")
                channel = "WEB"
                signature = "customer_confirmed_via_web_interface"
            }
        }
        
        # Check if order needs approval (high-value)
        if ($preparedOrder.amount -gt 10000) {
            Write-Host "`nHigh-value order $($preparedOrder.orderId) detected" -ForegroundColor Yellow
            Write-Host "Amount: €$($preparedOrder.amount.ToString('N2'))" -ForegroundColor White
            
            # Add supporting documents for high-value
            $executeBody.supportingDocuments = @(
                "doc_proof_of_funds_123",
                "doc_bank_statement_456",
                "doc_income_verification_789"
            )
            
            # Enhanced verification signature
            $executeBody.consentConfirmation.signature = "enhanced_verification_completed"
        }
        
        # Execute the order
        Write-Host "`nExecuting order: $($preparedOrder.reference)" -ForegroundColor Cyan
        Write-Host "  Order ID: $($preparedOrder.orderId)" -ForegroundColor White
        Write-Host "  Amount: €$($preparedOrder.amount.ToString('N2'))" -ForegroundColor White
        Write-Host "  Target: $($preparedOrder.target)" -ForegroundColor White
        
        $executeBodyJson = $executeBody | ConvertTo-Json -Depth 3
        
        # Create headers with customer authentication
        $headers = @{
            "Authorization" = "Bearer $token"  # Customer token
            "Content-Type"  = "application/json"
            "Accept"        = "application/json"
            "X-Tenant-Id"   = $xTenantId
            "X-Session-Id"  = $sessionId
        }
        
        $executeResponse = Invoke-RestMethod -Uri $executeUrl -Method Post -Headers $headers -Body $executeBodyJson
        
        if ($executeResponse.data) {
            $executionData = $executeResponse.data
            Write-Host "Order executed successfully!" -ForegroundColor Green
            Write-Host "  Transaction ID: $($executionData.transactionId)" -ForegroundColor White
            Write-Host "  Status: $($executionData.status)" -ForegroundColor White
            Write-Host "  Executed at: $($executionData.executedAt)" -ForegroundColor White
            
            # Display balance changes
            if ($executionData.balances) {
                $balanceBefore = [decimal]$executionData.balances.before.available
                $balanceAfter = [decimal]$executionData.balances.after.available
                $totalDeducted = $balanceBefore - $balanceAfter
                
                Write-Host "  Balance changes:" -ForegroundColor Cyan
                Write-Host "    Before: €$($balanceBefore.ToString('N2'))" -ForegroundColor White
                Write-Host "    After: €$($balanceAfter.ToString('N2'))" -ForegroundColor White
                Write-Host "    Total deducted: €$($totalDeducted.ToString('N2'))" -ForegroundColor Yellow
            }
            
            # Display fees
            if ($executionData.fees -and $executionData.fees.total) {
                Write-Host "  Fees charged: €$($executionData.fees.total)" -ForegroundColor Yellow
            }
            
            # Save execution confirmation
            $executionFile = "./executed_order_$($preparedOrder.orderId).json"
            $executeResponse | ConvertTo-Json -Depth 5 | Set-Content -Path $executionFile
            Write-Host "  Confirmation saved to: $executionFile" -ForegroundColor Green
            
            # Check final status
            switch ($executionData.status) {
                "COMPLETED" {
                    Write-Host "  ✓ Transfer completed successfully" -ForegroundColor Green
                }
                "PENDING" {
                    Write-Host "  ⏳ Transfer is pending processing" -ForegroundColor Yellow
                }
                "PROCESSING" {
                    Write-Host "  ⏰ Transfer is being processed" -ForegroundColor Yellow
                }
                default {
                    Write-Host "  Status: $($executionData.status)" -ForegroundColor White
                }
            }
        }
    }
    catch {
        Write-Host "Failed to execute order $($preparedOrder.orderId): $($_.Exception.Message)" -ForegroundColor Red
        
        # Handle specific errors
        if ($_.Exception.Response.StatusCode -eq 401) {
            Write-Host "  Invalid customer token - customer must be logged in" -ForegroundColor Yellow
        }
        elseif ($_.Exception.Response.StatusCode -eq 403) {
            Write-Host "  Consent not confirmed or invalid" -ForegroundColor Yellow
        }
        elseif ($_.Exception.Response.StatusCode -eq 404) {
            Write-Host "  Prepared order not found" -ForegroundColor Yellow
        }
        elseif ($_.Exception.Response.StatusCode -eq 409) {
            Write-Host "  Order has expired - need to prepare again" -ForegroundColor Yellow
        }
        elseif ($_.Exception.Response.StatusCode -eq 422) {
            Write-Host "  Invalid consent or authentication" -ForegroundColor Yellow
        }
    }
    
    # Small delay between executions
    Start-Sleep -Seconds 2
}

Write-Host "`nOrder execution completed" -ForegroundColor Cyan

# Generate execution summary
$executionSummary = @{
    totalOrders = $preparedOrders.Count
    executedOrders = @()
    timestamp = (Get-Date).ToString("yyyy-MM-dd HH:mm:ss")
}

# Save execution summary
$summaryFile = "./execution_summary_$(Get-Date -Format 'yyyyMMddHHmmss').json"
$executionSummary | ConvertTo-Json -Depth 3 | Set-Content -Path $summaryFile
Write-Host "Execution summary saved to: $summaryFile" -ForegroundColor Green
```text`n## Post-Execution

After successful execution:

1. **Transaction Receipt** - Available via transaction ID
2. **Balance Update** - Immediate reflection
3. **Notifications** - Sent to configured channels
4. **Audit Trail** - Complete record maintained

## Related Endpoints

- [Get Allowed Operations](/latest/api-reference/v2.1/fintrans/allowed-operations) - Step 1 of flow
- [Prepare Order](/latest/api-reference/v2.1/fintrans/prepare-order) - Step 2 of flow
- [Get Order Status](/latest/api-reference/v2.1/fintrans/order-status) - Check transaction status
- [Get Transaction History](/latest/api-reference/v2.1/fintrans/transactions) - View all transactions