How to Integrate Azure OpenAI for payments with CosmosDB for RAG

Combining Azure OpenAI for payments with Cosmos DB gives you a clean pattern for agentic finance systems: the model can reason over payment policies, transaction history, and customer context while Cosmos DB stores the retrieval layer that keeps responses grounded. That means you can build assistants that answer payment questions, explain declines, classify disputes, and surface relevant transaction records without stuffing everything into the prompt.

Prerequisites

• •Python 3.10+
• •An Azure subscription with:
  • •Azure OpenAI resource
  • •Azure Cosmos DB account
• •Deployed Azure OpenAI model for chat completions
• •Cosmos DB container for RAG documents or payment metadata
• •Environment variables set:
  • •AZURE_OPENAI_ENDPOINT
  • •AZURE_OPENAI_API_KEY
  • •AZURE_OPENAI_DEPLOYMENT
  • •COSMOS_ENDPOINT
  • •COSMOS_KEY
  • •COSMOS_DB_NAME
  • •COSMOS_CONTAINER_NAME
• •Installed packages:
  • •openai
  • •azure-cosmos
  • •python-dotenv

pip install openai azure-cosmos python-dotenv

Integration Steps

1. •

   Set up your client connections

   Start by creating clients for Azure OpenAI and Cosmos DB. In production, keep these in a shared dependency module so your agent tools can reuse them.

import os
from dotenv import load_dotenv
from openai import AzureOpenAI
from azure.cosmos import CosmosClient

load_dotenv()

aoai_client = AzureOpenAI(
    api_key=os.environ["AZURE_OPENAI_API_KEY"],
    api_version="2024-02-15-preview",
    azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
)

cosmos_client = CosmosClient(
    url=os.environ["COSMOS_ENDPOINT"],
    credential=os.environ["COSMOS_KEY"],
)

db = cosmos_client.get_database_client(os.environ["COSMOS_DB_NAME"])
container = db.get_container_client(os.environ["COSMOS_CONTAINER_NAME"])

2. •

   Store payment and policy documents in Cosmos DB

   For RAG, you need structured chunks. Store each chunk with metadata like source, customer segment, payment type, and embedding-ready text.

from uuid import uuid4

doc = {
    "id": str(uuid4()),
    "type": "payment_policy",
    "customer_tier": "enterprise",
    "payment_method": "card",
    "text": (
        "Card payments over $10,000 require manual review. "
        "Chargebacks must be acknowledged within 48 hours. "
        "Refunds are issued to the original payment method."
    ),
}

container.upsert_item(doc)
print("Stored document:", doc["id"])

If you already have transaction records, store them separately from policy content. That keeps retrieval focused and avoids mixing operational data with knowledge base text.

3. •

   Create embeddings with Azure OpenAI

   Use an embeddings deployment to turn the user query into a vector. If you already precomputed vectors for your Cosmos documents, use the same embedding model for consistency.

query = "What happens when an enterprise card payment is above ten thousand dollars?"

embedding_response = aoai_client.embeddings.create(
    model="text-embedding-3-small",
    input=query,
)

query_vector = embedding_response.data[0].embedding
print("Embedding length:", len(query_vector))

In a real setup, store embeddings alongside each Cosmos document or use a vector-enabled Cosmos DB container if your account supports it.

4. •

   Retrieve relevant context from Cosmos DB

   The exact query pattern depends on whether you are using keyword search, filters, or vector search. A practical first pass is metadata filtering plus text matching; then move to vector search once your container is configured for it.

def retrieve_context(user_query: str):
    results = list(container.query_items(
        query="""
        SELECT TOP 5 c.id, c.type, c.customer_tier, c.payment_method, c.text
        FROM c
        WHERE CONTAINS(LOWER(c.text), LOWER(@q))
           OR CONTAINS(LOWER(c.type), LOWER(@q))
        """,
        parameters=[{"name": "@q", "value": user_query}],
        enable_cross_partition_query=True,
    ))
    return results

contexts = retrieve_context(query)
for item in contexts:
    print(item["id"], item["text"])

For payments workflows, this is enough to ground answers in policy snippets, dispute rules, refund rules, or merchant-specific exceptions.

5. •

   Generate the grounded answer with Azure OpenAI

   Pass retrieved context into the chat completion call. Keep the system message strict so the assistant only answers from retrieved data when possible.

context_text = "\n\n".join(
    f"[{item['type']}] {item['text']}" for item in contexts
) or "No relevant context found."

messages = [
    {
        "role": "system",
        "content": (
            "You are a payments assistant. Answer using only the provided context. "
            "If the context is insufficient, say what is missing."
        ),
    },
    {
        "role": "user",
        "content": f"Context:\n{context_text}\n\nQuestion:\n{query}",
    },
]

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

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

Testing the Integration

Run a full round trip: write a document to Cosmos DB, retrieve it, and ask Azure OpenAI to answer from that context.

test_doc = {
    "id": str(uuid4()),
    "type": "refund_policy",
    "customer_tier": "standard",
    "text": "Refunds are processed within 5 business days after approval.",
}
container.upsert_item(test_doc)

test_query = "How long do refunds take?"
test_contexts = list(container.query_items(
    query="SELECT TOP 1 c.text FROM c WHERE CONTAINS(LOWER(c.text), LOWER(@q))",
    parameters=[{"name": "@q", "value": "refund"}],
    enable_cross_partition_query=True,
))

answer = aoai_client.chat.completions.create(
    model=os.environ["AZURE_OPENAI_DEPLOYMENT"],
    messages=[
        {"role": "system", "content": "Answer only from context."},
        {"role": "user", "content": f"Context: {test_contexts[0]['text']}\nQuestion: {test_query}"},
    ],
)

print(answer.choices[0].message.content)

Expected output:

Refunds are processed within 5 business days after approval.

Real-World Use Cases

• •

  Payment support copilot

  • •Answer questions about failed charges, refund timing, chargeback windows, and card verification using policy docs stored in Cosmos DB.
• •

  Dispute triage agent

  • •Retrieve transaction notes and dispute rules from Cosmos DB, then have Azure OpenAI classify the case and draft next steps.
• •

  Merchant operations assistant

  • •Ground answers in merchant-specific settlement rules, payout schedules, and exception handling policies before generating responses.

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.