Get Transaction by Reference

{
  "error": "reference is required. pass reference in the route /ref/:reference"
}

{
  "error": "transaction not found with reference: order-12345"
}

async function createIdempotentTransaction(transactionData) {
  const { reference } = transactionData;
  
  // Try to get existing transaction
  try {
    const existing = await fetch(
      `/transactions/reference/${reference}`
    ).then(r => r.json());
    
    // Transaction already exists
    console.log('Transaction already created:', existing.transaction_id);
    return existing;
  } catch (err) {
    // Transaction doesn't exist, create it
    return await fetch('/transactions', {
      method: 'POST',
      body: JSON.stringify(transactionData)
    }).then(r => r.json());
  }
}

def reconcile_order_payment(order_id):
    # Build reference from order ID
    reference = f"order-{order_id}"
    
    # Fetch transaction
    response = requests.get(
        f'/transactions/reference/{reference}',
        headers={'Authorization': f'Bearer {API_KEY}'}
    )
    
    if response.status_code == 200:
        transaction = response.json()
        
        # Verify payment
        if transaction['status'] == 'APPLIED':
            print(f"Order {order_id} paid: {transaction['amount']} {transaction['currency']}")
            return True
        elif transaction['status'] == 'INFLIGHT':
            print(f"Order {order_id} payment pending")
            return False
        else:
            print(f"Order {order_id} payment failed")
            return False
    else:
        print(f"No payment found for order {order_id}")
        return False

app.post('/webhooks/order-created', async (req, res) => {
  const { orderId, amount, currency } = req.body;
  const reference = `webhook-order-${orderId}`;
  
  try {
    // Check if we already processed this webhook
    const existing = await getTransactionByReference(reference);
    
    console.log('Webhook already processed');
    res.json({ status: 'duplicate', transaction_id: existing.transaction_id });
  } catch (err) {
    // New webhook, create transaction
    const transaction = await createTransaction({
      reference,
      amount,
      currency,
      description: `Order ${orderId}`,
      source: 'customer_balance',
      destination: 'merchant_balance'
    });
    
    res.json({ status: 'created', transaction_id: transaction.transaction_id });
  }
});

def process_refund(original_reference, refund_amount):
    # Get original transaction
    original = get_transaction_by_reference(original_reference)
    
    if original['status'] != 'APPLIED':
        raise ValueError('Cannot refund non-applied transaction')
    
    # Create refund with linked reference
    refund_reference = f"{original_reference}-refund"
    
    # Check if refund already exists
    try:
        existing_refund = get_transaction_by_reference(refund_reference)
        return existing_refund
    except:
        pass
    
    # Create new refund
    refund = create_transaction({
        'reference': refund_reference,
        'amount': refund_amount,
        'currency': original['currency'],
        'description': f"Refund for {original_reference}",
        'source': original['destination'],  # Reverse the flow
        'destination': original['source'],
        'meta_data': {
            'original_transaction_id': original['transaction_id'],
            'refund_type': 'partial' if refund_amount < original['amount'] else 'full'
        }
    })
    
    return refund

async function waitForTransactionByReference(reference, timeoutMs = 30000) {
  const startTime = Date.now();
  
  while (Date.now() - startTime < timeoutMs) {
    try {
      const txn = await fetch(
        `/transactions/reference/${reference}`
      ).then(r => r.json());
      
      if (txn.status === 'APPLIED') {
        return { success: true, transaction: txn };
      }
      
      if (txn.status === 'REJECTED') {
        return { 
          success: false, 
          error: txn.meta_data?.blnk_rejection_reason || 'Transaction rejected'
        };
      }
      
      // Still processing, wait and retry
      await new Promise(resolve => setTimeout(resolve, 1000));
    } catch (err) {
      // Transaction doesn't exist yet, wait and retry
      await new Promise(resolve => setTimeout(resolve, 1000));
    }
  }
  
  return { success: false, error: 'Timeout waiting for transaction' };
}

// Usage
const result = await waitForTransactionByReference('order-12345');
if (result.success) {
  console.log('Transaction completed:', result.transaction);
} else {
  console.error('Transaction failed:', result.error);
}

const references = {
  order: `order-${orderId}`,
  refund: `refund-${refundId}`,
  payout: `payout-${payoutId}`,
  subscription: `sub-${subscriptionId}-${period}`,
  transfer: `transfer-${transferId}`
};

import uuid
from datetime import datetime

# Include timestamp
reference = f"order-{order_id}-{int(datetime.now().timestamp())}"

# Include UUID
reference = f"payment-{order_id}-{uuid.uuid4().hex[:8]}"

# Include customer ID
reference = f"txn-{customer_id}-{order_id}"

// Good
"order-12345"
"refund-order-12345"
"sub-abc123-2024-01"

// Avoid
"a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"
"txn_2024_01_15_customer_abc_order_12345_payment_card_final_v2"

// Reference Format Documentation
type TransactionReference = 
  | `order-${string}`           // Customer order payments
  | `refund-${string}`          // Refund transactions
  | `payout-${string}`          // Seller payouts
  | `sub-${string}-${string}`   // Subscription charges
  | `fee-${string}`             // Fee transactions
  | `adjust-${string}`;         // Manual adjustments