NVC Platform API Documentation

Integration Guide for Strategic Partners

Getting Started: To integrate with the NVC Platform, you'll need an API user account. Contact your administrator to set up your API credentials.

Authentication

Obtaining an Access Token

All API requests require authentication. You can authenticate using either:

  • API Key: Include in the header as X-API-Key
  • JWT Token: Include in the header as Authorization: Bearer <token>
Get a JWT Token
POST /api/token
Content-Type: application/json

{
    "username": "your_api_username",
    "password": "your_api_password"
}
Response
{
    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "user_id": 123,
    "username": "your_api_username"
}

Transactions

Get Transaction History
GET /api/transactions
Authorization: Bearer <token>

Optional parameters:
- type: Filter by transaction type (deposit, withdrawal, transfer, payment, settlement)
- status: Filter by status (pending, processing, completed, failed, refunded)
- start_date: Filter from date (YYYY-MM-DD)
- end_date: Filter to date (YYYY-MM-DD)
- limit: Number of results (default: 50)
- offset: Pagination offset (default: 0)
Response
{
    "transactions": [
        {
            "id": 456,
            "transaction_id": "TX123456789",
            "amount": 100.00,
            "currency": "USD",
            "type": "payment",
            "status": "completed",
            "description": "Payment for services",
            "eth_transaction_hash": "0x1234...",
            "created_at": "2023-09-01T12:00:00Z",
            "updated_at": "2023-09-01T12:05:00Z"
        },
        ...
    ],
    "total": 127,
    "limit": 50,
    "offset": 0
}
Get Transaction Details
GET /api/transactions/<transaction_id>
Authorization: Bearer <token>
Response
{
    "id": 456,
    "transaction_id": "TX123456789",
    "user_id": 123,
    "amount": 100.00,
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "description": "Payment for services",
    "eth_transaction_hash": "0x1234...",
    "institution_id": 5,
    "gateway_id": 3,
    "created_at": "2023-09-01T12:00:00Z",
    "updated_at": "2023-09-01T12:05:00Z",
    "blockchain_transaction": {
        "eth_tx_hash": "0x1234...",
        "from_address": "0xabcd...",
        "to_address": "0xefgh...",
        "amount": 0.05,
        "gas_used": 21000,
        "gas_price": 5000000000,
        "block_number": 12345678,
        "status": "confirmed",
        "created_at": "2023-09-01T12:01:00Z"
    }
}

Payments

Create a Payment
POST /api/payments
Authorization: Bearer <token>
Content-Type: application/json

{
    "gateway_id": 3,
    "amount": 100.00,
    "currency": "USD",
    "description": "Payment for services",
    "metadata": {
        "order_id": "ORD123456",
        "customer_name": "John Doe"
    }
}
Response
{
    "success": true,
    "transaction_id": "TX123456789",
    "payment_intent_id": "pi_1234567890",  // For Stripe
    "client_secret": "pi_1234_secret_5678"  // For Stripe
    // or
    "hosted_url": "https://checkout.example.com/c/1234",  // For Coinbase
    "charge_id": "charge_1234567890"  // For Coinbase
    // or
    "approval_url": "https://paypal.com/checkout/1234567890",  // For PayPal
    "paypal_order_id": "ORDER-1234567890"  // For PayPal
}
Check Payment Status
GET /api/payments/<transaction_id>/status
Authorization: Bearer <token>
Response
{
    "success": true,
    "transaction_id": "TX123456789",
    "status": "completed",
    "amount": 100.00,
    "currency": "USD",
    "gateway_reference": "pi_1234567890"
}

Transfers

Create a Transfer
POST /api/transfers
Authorization: Bearer <token>
Content-Type: application/json

{
    "institution_id": 5,
    "amount": 500.00,
    "currency": "USD",
    "description": "Funds transfer to investment account",
    "recipient_info": {
        "account_number": "1234567890",
        "routing_number": "987654321"
    }
}
Response
{
    "success": true,
    "transaction_id": "TX987654321",
    "transfer_id": "TRF123456789",
    "status": "pending",
    "amount": 500.00,
    "currency": "USD"
}
Check Transfer Status
GET /api/transfers/<transaction_id>/status
Authorization: Bearer <token>
Response
{
    "success": true,
    "transaction_id": "TX987654321",
    "transfer_id": "TRF123456789",
    "status": "completed",
    "amount": 500.00,
    "currency": "USD",
    "institution_reference": "REF123456"
}

Blockchain

Create a Blockchain Transaction
POST /api/blockchain/transactions
Authorization: Bearer <token>
Content-Type: application/json

{
    "to_address": "0xabcdef1234567890abcdef1234567890abcdef12",
    "amount": 0.1,
    "description": "Settlement payment",
    "use_contract": true  // Use settlement smart contract
}
Response
{
    "success": true,
    "transaction_id": "TX567890123",
    "eth_transaction_hash": "0x1234...",
    "from_address": "0xabcd...",
    "to_address": "0xefgh...",
    "amount": 0.1,
    "status": "pending"
}
Get Ethereum Balance
GET /api/blockchain/balance
Authorization: Bearer <token>
Response
{
    "success": true,
    "address": "0xabcd...",
    "balance_eth": 1.25,
    "balance_wei": "1250000000000000000"
}

Integration Partners

Note: For asset managers and business partners that require deeper integration, we provide additional services and dedicated support. Please contact the NVC Platform administrator for more details.