How to Integrate Azure OpenAI for payments with CosmosDB for production AI

Why this integration matters

If you’re building an AI agent that touches payments, you need two things: a model that can reason over payment workflows and a durable system of record for transactions, fraud signals, and audit trails. Azure OpenAI gives you the reasoning layer; Cosmos DB gives you the low-latency state layer that keeps the agent grounded in production data.

That combination unlocks payment assistants that can validate transactions, explain declines, summarize chargeback cases, and keep every interaction tied to a customer or payment session.

Prerequisites

• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB for NoSQL account
• •Python 3.10+
• •pip installed
• •An Azure OpenAI deployment name for a chat model
• •Cosmos DB database and container created
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_DB_ENDPOINT
  • •COSMOS_DB_KEY
  • •COSMOS_DB_DATABASE
  • •COSMOS_DB_CONTAINER

Install the SDKs:

pip install openai azure-cosmos python-dotenv

Integration Steps

1) Initialize Azure OpenAI and Cosmos DB clients

Use the official Azure OpenAI client for chat completions and the Cosmos SDK for persistence.

import os
from openai import AzureOpenAI
from azure.cosmos import CosmosClient, PartitionKey

azure_openai_client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-06-01",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)

cosmos_client = CosmosClient(
    url=os.environ["COSMOS_DB_ENDPOINT"],
    credential=os.environ["COSMOS_DB_KEY"]
)

database_name = os.environ["COSMOS_DB_DATABASE"]
container_name = os.environ["COSMOS_DB_CONTAINER"]

database = cosmos_client.get_database_client(database_name)
container = database.get_container_client(container_name)

If you’re creating the container from code, keep the partition key aligned to your payment/session identifier.

if not list(database.read_all_containers()):
    database = cosmos_client.create_database_if_not_exists(database_name)

container = database.create_container_if_not_exists(
    id=container_name,
    partition_key=PartitionKey(path="/paymentId"),
)

2) Read payment context from Cosmos DB

Your agent should never guess payment state. Pull the transaction record first, then ask the model to reason over it.

payment_id = "pay_100245"

payment_record = container.read_item(
    item=payment_id,
    partition_key=payment_id
)

print(payment_record)

A typical document should look like this:

{
  "id": "pay_100245",
  "paymentId": "pay_100245",
  "customerId": "cust_7781",
  "amount": 149.99,
  "currency": "USD",
  "status": "pending_review",
  "riskScore": 82,
  "createdAt": "2026-04-21T10:15:00Z"
}

3) Send the payment context to Azure OpenAI

Use chat.completions.create() to generate a decision summary or next action based on the stored payment data.

import json

messages = [
    {
        "role": "system",
        "content": (
            "You are a payments operations assistant. "
            "Return concise operational guidance only."
        )
    },
    {
        "role": "user",
        "content": f"""
Review this payment record and recommend the next action:

{json.dumps(payment_record, indent=2)}
"""
    }
]

response = azure_openai_client.chat.completions.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    messages=messages,
    temperature=0.2,
)

analysis = response.choices[0].message.content
print(analysis)

For production use, keep temperature low. You want consistent operational output, not creative variation.

4) Persist the model’s decision back into Cosmos DB

Store both the raw model output and your final system action. That gives you traceability for audits and incident review.

from datetime import datetime, timezone

updated_record = {
    **payment_record,
    "agentSummary": analysis,
    "lastReviewedAt": datetime.now(timezone.utc).isoformat(),
    "reviewSource": "azure-openai",
}

container.upsert_item(updated_record)
print("Payment record updated.")

If your agent takes an action like “escalate to manual review” or “release hold,” store that as a separate field too.

updated_record["recommendedAction"] = "manual_review"
updated_record["actionStatus"] = "pending_approval"

container.upsert_item(updated_record)

5) Wrap it in a single orchestration function

This is the pattern you actually ship: fetch state, call the model, persist result.

def review_payment(payment_id: str):
    record = container.read_item(item=payment_id, partition_key=payment_id)

    prompt = f"""
You are reviewing a card payment for operations.
Return:
1. risk assessment
2. recommended action
3. short reason

Payment record:
{json.dumps(record, indent=2)}
"""

    result = azure_openai_client.chat.completions.create(
        model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
        messages=[
            {"role": "system", "content": "You are a payments risk assistant."},
            {"role": "user", "content": prompt},
        ],
        temperature=0.1,
    )

    decision_text = result.choices[0].message.content

    record["agentDecision"] = decision_text
    record["reviewedBy"] = "azure-openai"
    record["reviewedAt"] = datetime.now(timezone.utc).isoformat()

    container.upsert_item(record)
    return decision_text


print(review_payment("pay_100245"))

Testing the Integration

Run a simple end-to-end test with one known payment document in Cosmos DB.

test_payment_id = "pay_100245"
output = review_payment(test_payment_id)

print("Model output:")
print(output)

saved_doc = container.read_item(item=test_payment_id, partition_key=test_payment_id)
print("\nSaved fields:")
print(saved_doc["reviewedBy"])
print(saved_doc["reviewedAt"])
print(saved_doc["agentDecision"][:120])

Expected output:

Model output:
Risk assessment: High.
Recommended action: Manual review.
Reason: Elevated risk score and pending_review status require human approval before release.

Saved fields:
azure-openai
2026-04-21T10:20:31.123456+00:00
Risk assessment: High.
Recommended action: Manual review.
Reason: Elevated risk score...

If this works end-to-end, your agent can now reason over live payment state and write decisions back into your system of record.

Real-World Use Cases

• •

  Payment exception handling

  • •Detect high-risk payments in Cosmos DB.
  • •Ask Azure OpenAI to summarize why a transaction was flagged.
  • •Persist escalation notes for operations teams.
• •

  Chargeback case assistants

  • •Pull transaction history, merchant notes, and dispute metadata from Cosmos DB.
  • •Generate case summaries and evidence checklists with Azure OpenAI.
  • •Store reviewer responses and final outcomes in Cosmos DB.
• •

  Customer support copilots

  • •Retrieve failed-payment records by customer ID.
  • •Have the model explain decline reasons in plain language.
  • •Save support transcripts and resolution status for compliance tracking.

Keep learning

• •The complete AI Agents Roadmap — my full 8-step breakdown
• •Free: The AI Agent Starter Kit — PDF checklist + starter code
• •Work with me — I build AI for banks and insurance companies

By Cyprian Aarons, AI Consultant at Topiax.