API docs by Redocly

Zindigi-Vavita Integration API (1.0.0)

Download OpenAPI specification:

API Support: api-support@vavita.example.com License: Proprietary

Overview

This documentation describes the secure API integration between Zindigi (bank) and Vavita (fintech platform).

Data Flow

The integration supports bidirectional data flow:

  • Vavita → Zindigi: Account operations, transaction requests, customer verification
  • Zindigi → Vavita: Transaction confirmations, account updates, webhook notifications

Security

All API endpoints require authentication and use industry-standard security practices:

  • OAuth 2.0 with JWT tokens
  • TLS 1.3 encryption for all communications
  • API key authentication for webhooks
  • Request signing for sensitive operations
  • IP whitelisting available for enhanced security

Environments

  • Sandbox: https://sandbox-api.zindigi-vavita.example.com
  • Production: https://api.zindigi-vavita.example.com

Authentication

Authentication and token management endpoints

Obtain access token

Exchange credentials for an OAuth 2.0 access token.

Token Lifetime: 3600 seconds (1 hour)

Rate Limit: 10 requests per minute per client

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "client_credentials"

OAuth 2.0 grant type

client_id
required
string

Your application's client ID

client_secret
required
string <password>

Your application's client secret

scope
string

Space-separated list of scopes

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "refresh_abc123xyz789",
  • "scope": "accounts:read transactions:write"
}

Refresh access token

Obtain a new access token using a refresh token

Request Body schema: application/x-www-form-urlencoded
required
grant_type
required
string
Value: "refresh_token"
refresh_token
required
string

Valid refresh token

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  • "token_type": "Bearer",
  • "expires_in": 3600,
  • "refresh_token": "refresh_abc123xyz789",
  • "scope": "accounts:read transactions:write"
}

Accounts

Customer account operations

List accounts

Retrieve a list of customer accounts

Authorizations:
OAuth2ApiKeyAuth
query Parameters
customer_id
string

Filter by customer ID

status
string
Enum: "active" "suspended" "closed"

Filter by account status

limit
integer [ 1 .. 100 ]
Default: 20

Number of results per page

offset
integer >= 0
Default: 0

Pagination offset

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "pagination": {
    }
}

Get account details

Retrieve detailed information about a specific account

Authorizations:
OAuth2ApiKeyAuth
path Parameters
account_id
required
string
Example: acc_1234567890

Unique account identifier

Responses

Response samples

Content type
application/json
{
  • "id": "acc_1234567890",
  • "customer_id": "cust_abcdef123456",
  • "account_number": "1234567890123456",
  • "iban": "GB82WEST12345698765432",
  • "status": "active",
  • "type": "checking",
  • "balance": {
    },
  • "currency": "USD",
  • "created_at": "2024-01-15T10:30:00Z",
  • "updated_at": "2024-01-20T14:45:00Z"
}

Transactions

Transaction initiation and management

Create transaction

Initiate a new transaction.

Important: This operation requires transaction signing using your private key. Include the signature in the X-Request-Signature header.

Authorizations:
OAuth2ApiKeyAuth
header Parameters
X-Request-Signature
required
string

HMAC-SHA256 signature of request body

X-Idempotency-Key
required
string <uuid>

Unique key to prevent duplicate transactions

Request Body schema: application/json
required
from_account_id
required
string

Source account ID

to_account_id
required
string

Destination account ID

amount
required
number <decimal> >= 0.01

Transaction amount

currency
required
string

ISO 4217 currency code

description
string <= 255 characters

Transaction description

reference
string <= 100 characters

External reference number

object

Additional metadata

Responses

Request samples

Content type
application/json
{
  • "from_account_id": "acc_1234567890",
  • "to_account_id": "acc_0987654321",
  • "amount": 100.5,
  • "currency": "USD",
  • "description": "Invoice payment",
  • "reference": "INV-12345",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "from_account_id": "acc_1234567890",
  • "to_account_id": "acc_0987654321",
  • "amount": 100.5,
  • "currency": "USD",
  • "description": "Invoice payment",
  • "reference": "INV-12345",
  • "metadata": {
    },
  • "id": "txn_9876543210",
  • "status": "completed",
  • "created_at": "2024-01-20T15:30:00Z",
  • "completed_at": "2024-01-20T15:30:05Z",
  • "error_code": "INSUFFICIENT_FUNDS",
  • "error_message": "Insufficient funds in source account"
}

Get transaction status

Retrieve the current status and details of a transaction

Authorizations:
OAuth2ApiKeyAuth
path Parameters
transaction_id
required
string
Example: txn_9876543210

Unique transaction identifier

Responses

Response samples

Content type
application/json
{
  • "from_account_id": "acc_1234567890",
  • "to_account_id": "acc_0987654321",
  • "amount": 100.5,
  • "currency": "USD",
  • "description": "Invoice payment",
  • "reference": "INV-12345",
  • "metadata": {
    },
  • "id": "txn_9876543210",
  • "status": "completed",
  • "created_at": "2024-01-20T15:30:00Z",
  • "completed_at": "2024-01-20T15:30:05Z",
  • "error_code": "INSUFFICIENT_FUNDS",
  • "error_message": "Insufficient funds in source account"
}

Webhooks

Webhook configuration and management

Transaction completed notification Webhook

Sent when a transaction is successfully completed.

Signature Verification: Verify the X-Webhook-Signature header using HMAC-SHA256 with your webhook secret.

import hmac
import hashlib

signature = hmac.new(
    webhook_secret.encode(),
    request.body,
    hashlib.sha256
).hexdigest()

if signature != request.headers['X-Webhook-Signature']:
    raise ValueError('Invalid signature')
Authorizations:
OAuth2ApiKeyAuth
header Parameters
X-Webhook-Signature
required
string

HMAC-SHA256 signature for verification

X-Webhook-ID
required
string

Unique webhook delivery ID

Request Body schema: application/json
required
event
required
string
Value: "transaction.completed"
required
object (Transaction)
timestamp
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "event": "transaction.completed",
  • "data": {
    },
  • "timestamp": "2024-01-20T15:30:05Z"
}

Transaction failed notification Webhook

Sent when a transaction fails

Authorizations:
OAuth2ApiKeyAuth
header Parameters
X-Webhook-Signature
required
string
X-Webhook-ID
required
string
Request Body schema: application/json
required
event
required
string
Value: "transaction.failed"
required
object (Transaction)
timestamp
required
string <date-time>

Responses

Request samples

Content type
application/json
{
  • "event": "transaction.failed",
  • "data": {
    },
  • "timestamp": "2019-08-24T14:15:22Z"
}

List webhook subscriptions

Retrieve all configured webhook endpoints

Authorizations:
OAuth2ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create webhook subscription

Register a new webhook endpoint to receive event notifications

Authorizations:
OAuth2ApiKeyAuth
Request Body schema: application/json
required
url
required
string <uri>

HTTPS endpoint URL

events
required
Array of strings
Items Enum: "transaction.created" "transaction.completed" "transaction.failed" "account.updated" "account.suspended"

Events to subscribe to

secret
string

Secret for webhook signature verification

description
string <= 255 characters

Webhook description

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "url": "https://vavita.example.com/webhooks/zindigi",
  • "events": [
    ],
  • "secret": "whsec_abc123xyz789",
  • "description": "Production webhook for transaction notifications",
  • "id": "whk_1234567890",
  • "status": "active",
  • "created_at": "2024-01-15T10:00:00Z",
  • "last_triggered_at": "2024-01-20T15:30:00Z"
}

Delete webhook subscription

Remove a webhook endpoint

Authorizations:
OAuth2ApiKeyAuth
path Parameters
webhook_id
required
string

Webhook identifier

Responses

Response samples

Content type
application/json
{
  • "error": "INVALID_REQUEST",
  • "message": "The request was invalid or malformed",
  • "details": [
    ],
  • "request_id": "req_abc123xyz789"
}

Health

System health and status checks

Health check

Check API health and availability

Responses

Response samples

Content type
application/json
{
  • "status": "healthy",
  • "timestamp": "2019-08-24T14:15:22Z",
  • "version": "1.0.0"
}