Skip to main content

Python Examples

Complete Python client for Ozura Vault.

Installation

pip install requests

Complete Client Library

# ozura_vault_client.py

import requests
from typing import Optional, Dict, Any

class OzuraVaultError(Exception):
    def __init__(self, message: str, status_code: int = None, data: dict = None):
        super().__init__(message)
        self.status_code = status_code
        self.data = data

class OzuraVaultClient:
    def __init__(
        self,
        api_key: str,
        base_url: str = 'https://pci-vault-hrhwdgc4akhse3bs.eastus-01.azurewebsites.net'
    ):
        self.api_key = api_key
        self.base_url = base_url
        self.session = requests.Session()
        self.session.headers.update({
            'Content-Type': 'application/json',
            'X-API-Key': api_key
        })

    def _request(
        self,
        method: str,
        endpoint: str,
        data: dict = None,
        params: dict = None
    ) -> dict:
        url = f'{self.base_url}{endpoint}'

        response = self.session.request(
            method=method,
            url=url,
            json=data,
            params=params
        )

        result = response.json()

        if not result.get('success', False):
            raise OzuraVaultError(
                result.get('message', 'Unknown error'),
                response.status_code,
                result
            )

        return result

    # Tokenization
    def tokenize(self, token_type: str, data: dict) -> dict:
        return self._request('POST', '/tokenize', {
            'type': token_type,
            'data': data
        })

    def tokenize_card(
        self,
        card_number: str,
        expiration_month: str,
        expiration_year: str,
        cvv: Optional[str] = None
    ) -> dict:
        data = {
            'cardNumber': card_number,
            'expirationMonth': expiration_month,
            'expirationYear': expiration_year
        }
        if cvv:
            data['cvv'] = cvv
        return self.tokenize('card', data)

    def tokenize_bank(
        self,
        account_number: str,
        routing_number: str,
        account_type: str
    ) -> dict:
        return self.tokenize('bank', {
            'accountNumber': account_number,
            'routingNumber': routing_number,
            'accountType': account_type
        })

    def create_test_token(
        self,
        card_number: str,
        expiration_month: str,
        expiration_year: str,
        cvv: str
    ) -> dict:
        return self._request('POST', '/test-tokens', {
            'type': 'card',
            'data': {
                'cardNumber': card_number,
                'expirationMonth': expiration_month,
                'expirationYear': expiration_year,
                'cvv': cvv
            }
        })

    # Detokenization
    def detokenize(self, token: str) -> dict:
        return self._request('POST', '/detokenize', {'token': token})

    # Proxy
    def proxy(
        self,
        token: str,
        proxy_url: str,
        request_data: dict,
        cvc_session_id: Optional[str] = None,
        http_headers: Optional[dict] = None
    ) -> dict:
        payload = {
            'token': token,
            'proxy_url': proxy_url,
            'request_data': request_data
        }
        if cvc_session_id:
            payload['cvc_session_id'] = cvc_session_id
        if http_headers:
            payload['http_headers'] = http_headers

        return self._request('POST', '/proxy/transaction', payload)

    # Verify
    def verify_api_key(self) -> dict:
        return self._request('GET', '/api/applications/key')

Usage Examples

Initialize Client

import os
from ozura_vault_client import OzuraVaultClient

client = OzuraVaultClient(os.environ['OZURA_API_KEY'])

Tokenize a Card

def tokenize_card():
    try:
        result = client.tokenize_card(
            card_number='4111111111111111',
            expiration_month='12',
            expiration_year='2025',
            cvv='123'
        )

        print(f"Token: {result['token']}")
        print(f"CVC Session: {result['cvc_session_id']}")
        print(f"Masked: {result['mask']['card_number']}")

        return result

    except OzuraVaultError as e:
        print(f"Tokenization failed: {e}")
        raise

Process Payment with Stripe

import os

def process_stripe_payment(token: str, cvc_session_id: str, amount: int):
    try:
        result = client.proxy(
            token=token,
            cvc_session_id=cvc_session_id,
            proxy_url='https://api.stripe.com/v1/charges',
            request_data={
                'amount': amount,
                'currency': 'usd',
                'source': {
                    'object': 'card',
                    'number': '${cardNumber}',
                    'exp_month': '${expirationMonth}',
                    'exp_year': '${expirationYear}',
                    'cvc': '${cvv}'
                }
            },
            http_headers={
                'Authorization': f"Bearer {os.environ['STRIPE_SECRET_KEY']}"
            }
        )

        stripe_response = result['proxy_response']['body']
        print(f"Charge ID: {stripe_response['id']}")
        print(f"Status: {stripe_response['status']}")

        return stripe_response

    except OzuraVaultError as e:
        print(f"Payment failed: {e}")
        raise

Complete Checkout Flow

def checkout(card_details: dict, amount: int, customer_id: str):
    # 1. Tokenize the card
    token_result = client.tokenize_card(
        card_number=card_details['number'],
        expiration_month=card_details['exp_month'],
        expiration_year=card_details['exp_year'],
        cvv=card_details['cvv']
    )

    # 2. Store token for future use
    save_to_database(
        customer_id=customer_id,
        token=token_result['token'],
        last4=token_result['mask']['card_number'][-4:]
    )

    # 3. Process payment
    payment = process_stripe_payment(
        token=token_result['token'],
        cvc_session_id=token_result['cvc_session_id'],
        amount=amount
    )

    return payment

Flask Integration

from flask import Flask, request, jsonify
from ozura_vault_client import OzuraVaultClient, OzuraVaultError
import os

app = Flask(__name__)
vault = OzuraVaultClient(os.environ['OZURA_API_KEY'])

@app.route('/api/tokenize', methods=['POST'])
def tokenize():
    try:
        data = request.json
        result = vault.tokenize_card(
            card_number=data['cardNumber'],
            expiration_month=data['expMonth'],
            expiration_year=data['expYear'],
            cvv=data.get('cvv')
        )

        return jsonify({
            'token': result['token'],
            'cvcSessionId': result.get('cvc_session_id'),
            'last4': result['mask']['card_number'][-4:]
        })

    except OzuraVaultError as e:
        return jsonify({'error': str(e)}), 400

@app.route('/api/pay', methods=['POST'])
def pay():
    try:
        data = request.json
        result = vault.proxy(
            token=data['token'],
            cvc_session_id=data.get('cvcSessionId'),
            proxy_url='https://api.stripe.com/v1/charges',
            request_data={
                'amount': data['amount'],
                'currency': 'usd',
                'source': {
                    'object': 'card',
                    'number': '${cardNumber}',
                    'exp_month': '${expirationMonth}',
                    'exp_year': '${expirationYear}',
                    'cvc': '${cvv}'
                }
            },
            http_headers={
                'Authorization': f"Bearer {os.environ['STRIPE_SECRET_KEY']}"
            }
        )

        proxy_response = result['proxy_response']
        if proxy_response['status_code'] >= 400:
            error_msg = proxy_response['body'].get('error', {}).get('message', 'Payment failed')
            return jsonify({'error': error_msg}), 400

        return jsonify(proxy_response['body'])

    except OzuraVaultError as e:
        return jsonify({'error': str(e)}), 400

if __name__ == '__main__':
    app.run(port=3000)

Error Handling

from ozura_vault_client import OzuraVaultClient, OzuraVaultError

def safe_tokenize(card_data: dict):
    try:
        return client.tokenize_card(
            card_number=card_data['number'],
            expiration_month=card_data['exp_month'],
            expiration_year=card_data['exp_year'],
            cvv=card_data.get('cvv')
        )

    except OzuraVaultError as e:
        if 'Invalid API key' in str(e):
            print('Check your API key configuration')
        elif 'Invalid card number' in str(e):
            print('Please check the card number')
        else:
            print(f'Unexpected error: {e}')
        raise

Django Integration

# views.py
from django.http import JsonResponse
from django.views.decorators.csrf import csrf_exempt
from django.conf import settings
import json

from ozura_vault_client import OzuraVaultClient, OzuraVaultError

vault = OzuraVaultClient(settings.OZURA_API_KEY)

@csrf_exempt
def tokenize_view(request):
    if request.method != 'POST':
        return JsonResponse({'error': 'Method not allowed'}, status=405)

    try:
        data = json.loads(request.body)
        result = vault.tokenize_card(
            card_number=data['cardNumber'],
            expiration_month=data['expMonth'],
            expiration_year=data['expYear'],
            cvv=data.get('cvv')
        )

        return JsonResponse({
            'token': result['token'],
            'cvcSessionId': result.get('cvc_session_id'),
            'last4': result['mask']['card_number'][-4:]
        })

    except OzuraVaultError as e:
        return JsonResponse({'error': str(e)}, status=400)
    except json.JSONDecodeError:
        return JsonResponse({'error': 'Invalid JSON'}, status=400)

Next Steps