Authorization API

{
  "transaction_type": "POS",
  "user_id": "5f7e3f7b-8e0c-48b8-9f2c-3e0c9d7a2a11",
  "transaction_id": "a7b2a4b3-2f61-41a7-9f5a-3f3f0b1a3d22",
  "operation_type": "Debit",
  "card_id": "c0b2c7b1-1d2e-4d7a-9a5d-2b7e3c4d5f66",
  "currency": "USD",
  "amount": 123.45,
  "unique_operation_id": "3e1f6a98-6b0a-4c8c-93e5-0b9c6d2a7f31",
  "correlation_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "rates_by_assets": [
    {
      "asset": "USDC",
      "rate": 1.0
    }
  ],
  "is_mandatory": false,
  "related_external_operation_status": "None",
  "transaction_reason": "Authorization"
}

{
  "transaction_id": "a7b2a4b3-2f61-41a7-9f5a-3f3f0b1a3d22",
  "is_allowed": true,
  "decline_reason": null,
  "external_transactions": [
    {
      "account_currency": "USDC",
      "account_id": "user-account-123",
      "amount": 123.45,
      "rate": 1.0,
      "transaction_identifier": "partner-txn-456"
    }
  ]
}

{
  "transaction_type": "POS",
  "user_id": "5f7e3f7b-8e0c-48b8-9f2c-3e0c9d7a2a11",
  "transaction_id": "a7b2a4b3-2f61-41a7-9f5a-3f3f0b1a3d22",
  "operation_type": "Debit",
  "card_id": "c0b2c7b1-1d2e-4d7a-9a5d-2b7e3c4d5f66",
  "currency": "USD",
  "amount": 123.45,
  "unique_operation_id": "3e1f6a98-6b0a-4c8c-93e5-0b9c6d2a7f31",
  "correlation_id": "7a8b9c0d-1e2f-3a4b-5c6d-7e8f9a0b1c2d",
  "settlement_currency": "USD",
  "settlement_amount": 123.45,
  "settlement_decision": "Approve",
  "reject_reason": null
}

{
  "is_processed": true,
  "error_reason": null,
  "transaction_id": "a7b2a4b3-2f61-41a7-9f5a-3f3f0b1a3d22"
}

// Authorization endpoint
app.post('/external-authorization/on-chain/card-transaction/external/authorize', async (req, res) => {
  const {
    user_id,
    transaction_id,
    amount,
    currency,
    is_mandatory,
    unique_operation_id,
    transaction_reason
  } = req.body;

  // Check idempotency
  const existing = await db.findOperation(unique_operation_id);
  if (existing) {
    return res.json({
      transaction_id,
      is_allowed: existing.allowed,
      external_transactions: existing.external_transactions
    });
  }

  // For mandatory transactions, always allow
  if (is_mandatory) {
    const result = await db.recordOperation(unique_operation_id, user_id, amount, true);
    return res.json({
      transaction_id,
      is_allowed: true,
      external_transactions: [{
        account_currency: currency,
        account_id: user_id,
        amount,
        rate: 1.0,
        transaction_identifier: result.id
      }]
    });
  }

  // Check user balance
  const userBalance = await db.getUserBalance(user_id, currency);
  const allowed = userBalance >= amount;

  if (allowed) {
    await db.holdBalance(user_id, amount, unique_operation_id);
  }

  const result = await db.recordOperation(unique_operation_id, user_id, amount, allowed);

  res.json({
    transaction_id,
    is_allowed: allowed,
    decline_reason: allowed ? null : 'InsufficientFunds',
    external_transactions: allowed ? [{
      account_currency: currency,
      account_id: user_id,
      amount,
      rate: 1.0,
      transaction_identifier: result.id
    }] : []
  });
});

// Settlement endpoint
app.post('/external-authorization/on-chain/card-transaction/external/settle', async (req, res) => {
  const {
    transaction_id,
    user_id,
    unique_operation_id,
    settlement_amount,
    settlement_currency,
    settlement_decision
  } = req.body;

  const operation = await db.findOperation(unique_operation_id);
  if (!operation) {
    return res.json({
      is_processed: false,
      error_reason: 'GeneralError',
      transaction_id
    });
  }

  if (settlement_decision === 'Approve') {
    await db.finalizeDebit(user_id, settlement_amount, settlement_currency, unique_operation_id);
  } else {
    await db.releaseHold(user_id, unique_operation_id);
  }

  res.json({
    is_processed: true,
    transaction_id
  });
});

# Authorization endpoint
@app.post("/external-authorization/on-chain/card-transaction/external/authorize")
async def authorize_transaction(request: AuthorizeRequest):
    # Check idempotency
    existing = await db.find_operation(request.unique_operation_id)
    if existing:
        return {
            "transaction_id": request.transaction_id,
            "is_allowed": existing.allowed,
            "external_transactions": existing.external_transactions
        }

    # For mandatory transactions, always allow
    if request.is_mandatory:
        result = await db.record_operation(request.unique_operation_id, request.user_id, request.amount, True)
        return {
            "transaction_id": request.transaction_id,
            "is_allowed": True,
            "external_transactions": [{
                "account_currency": request.currency,
                "account_id": request.user_id,
                "amount": request.amount,
                "rate": 1.0,
                "transaction_identifier": result.id
            }]
        }

    # Check user balance
    user_balance = await db.get_user_balance(request.user_id, request.currency)
    allowed = user_balance >= request.amount

    if allowed:
        await db.hold_balance(request.user_id, request.amount, request.unique_operation_id)

    result = await db.record_operation(request.unique_operation_id, request.user_id, request.amount, allowed)

    return {
        "transaction_id": request.transaction_id,
        "is_allowed": allowed,
        "decline_reason": None if allowed else "InsufficientFunds",
        "external_transactions": [{
            "account_currency": request.currency,
            "account_id": request.user_id,
            "amount": request.amount,
            "rate": 1.0,
            "transaction_identifier": result.id
        }] if allowed else []
    }

# Settlement endpoint
@app.post("/external-authorization/on-chain/card-transaction/external/settle")
async def settle_transaction(request: SettleRequest):
    operation = await db.find_operation(request.unique_operation_id)
    if not operation:
        return {
            "is_processed": False,
            "error_reason": "GeneralError",
            "transaction_id": request.transaction_id
        }

    if request.settlement_decision == "Approve":
        await db.finalize_debit(request.user_id, request.settlement_amount, request.settlement_currency, request.unique_operation_id)
    else:
        await db.release_hold(request.user_id, request.unique_operation_id)

    return {
        "is_processed": True,
        "transaction_id": request.transaction_id
    }

// Authorization endpoint
func authorizeTransaction(w http.ResponseWriter, r *http.Request) {
    var req AuthorizeRequest
    json.NewDecoder(r.Body).Decode(&req)

    // Check idempotency
    if existing, found := db.FindOperation(req.UniqueOperationID); found {
        json.NewEncoder(w).Encode(map[string]interface{}{
            "transaction_id":        req.TransactionID,
            "is_allowed":            existing.Allowed,
            "external_transactions": existing.ExternalTransactions,
        })
        return
    }

    // For mandatory transactions, always allow
    if req.IsMandatory {
        result := db.RecordOperation(req.UniqueOperationID, req.UserID, req.Amount, true)
        json.NewEncoder(w).Encode(map[string]interface{}{
            "transaction_id": req.TransactionID,
            "is_allowed":     true,
            "external_transactions": []map[string]interface{}{{
                "account_currency":       req.Currency,
                "account_id":             req.UserID,
                "amount":                 req.Amount,
                "rate":                   1.0,
                "transaction_identifier": result.ID,
            }},
        })
        return
    }

    // Check user balance
    userBalance := db.GetUserBalance(req.UserID, req.Currency)
    allowed := userBalance >= req.Amount

    if allowed {
        db.HoldBalance(req.UserID, req.Amount, req.UniqueOperationID)
    }

    result := db.RecordOperation(req.UniqueOperationID, req.UserID, req.Amount, allowed)

    resp := map[string]interface{}{
        "transaction_id": req.TransactionID,
        "is_allowed":     allowed,
    }
    if !allowed {
        resp["decline_reason"] = "InsufficientFunds"
        resp["external_transactions"] = []map[string]interface{}{}
    } else {
        resp["external_transactions"] = []map[string]interface{}{{
            "account_currency":       req.Currency,
            "account_id":             req.UserID,
            "amount":                 req.Amount,
            "rate":                   1.0,
            "transaction_identifier": result.ID,
        }}
    }
    json.NewEncoder(w).Encode(resp)
}

// Settlement endpoint
func settleTransaction(w http.ResponseWriter, r *http.Request) {
    var req SettleRequest
    json.NewDecoder(r.Body).Decode(&req)

    operation, found := db.FindOperation(req.UniqueOperationID)
    if !found {
        json.NewEncoder(w).Encode(map[string]interface{}{
            "is_processed":   false,
            "error_reason":   "GeneralError",
            "transaction_id": req.TransactionID,
        })
        return
    }

    if req.SettlementDecision == "Approve" {
        db.FinalizeDebit(req.UserID, req.SettlementAmount, req.SettlementCurrency, req.UniqueOperationID)
    } else {
        db.ReleaseHold(req.UserID, req.UniqueOperationID)
    }

    json.NewEncoder(w).Encode(map[string]interface{}{
        "is_processed":   true,
        "transaction_id": req.TransactionID,
    })
}