dbis_core/docs/nostro-vostro/api-reference.md

DBIS Nostro/Vostro API Reference

Base URL

• Production: https://api.scb.example.com/api/v1/nostro-vostro
• Sandbox: https://sandbox.scb.example.com/api/v1/nostro-vostro

Authentication

All requests require OAuth2 authentication with Mutual TLS:

Authorization: Bearer <access_token>

Endpoints

Participants

List Participants

GET /participants

Query Parameters:

• regulatoryTier (optional): Filter by tier (SCB, Tier1, Tier2, PSP)
• country (optional): Filter by country code
• status (optional): Filter by status
• page (optional): Page number (default: 1)
• pageSize (optional): Items per page (default: 50)

Response:

{
  "success": true,
  "data": {
    "data": [
      {
        "participantId": "PART-123",
        "name": "Central Bank of Example",
        "bic": "CBEXUS33",
        "country": "US",
        "regulatoryTier": "SCB",
        "status": "active"
      }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 50,
      "total": 1,
      "totalPages": 1
    }
  }
}

Get Participant

GET /participants/{participantId}

Create Participant

POST /participants

Request Body:

{
  "name": "Central Bank of Example",
  "bic": "CBEXUS33",
  "lei": "5493000X9ZXSQ9B6Y815",
  "country": "US",
  "regulatoryTier": "SCB"
}

Accounts

List Accounts

GET /accounts

Create Account

POST /accounts

Request Body:

{
  "ownerParticipantId": "PART-123",
  "counterpartyParticipantId": "PART-456",
  "ibanOrLocalAccount": "US64SVBKUS6S3300958879",
  "currency": "USD",
  "accountType": "NOSTRO"
}

Get Account

GET /accounts/{accountId}

Get Account Balances

GET /accounts/{accountId}/balances

Response:

{
  "success": true,
  "data": {
    "accountId": "ACC-123",
    "currentBalance": "1000000.00",
    "availableLiquidity": "950000.00",
    "holdAmount": "50000.00",
    "currency": "USD",
    "lastUpdatedAt": "2024-01-15T10:30:00Z"
  }
}

Transfers

Create Transfer

POST /transfers

Headers:

• Idempotency-Key (optional): Unique key for idempotency

Request Body:

{
  "fromAccountId": "ACC-123",
  "toAccountId": "ACC-456",
  "amount": "1000.00",
  "currency": "USD",
  "settlementAsset": "FIAT",
  "valueDate": "2024-01-15",
  "reference": "PAYMENT-REF-001"
}

Get Transfer

GET /transfers/{transferId}

List Transfers

GET /transfers

Reconciliations

Request Reconciliation

POST /reconciliations

Request Body:

{
  "participantId": "PART-123",
  "asOfDate": "2024-01-15"
}

Get Reconciliation

GET /reconciliations/{reportId}

Webhooks

Create Subscription

POST /webhooks/subscriptions

Request Body:

{
  "participantId": "PART-123",
  "webhookUrl": "https://example.com/webhooks",
  "eventTypes": ["TRANSFER_CREATED", "TRANSFER_SETTLED"]
}

List Subscriptions

GET /webhooks/subscriptions?participantId=PART-123

GRU/FX

Get Rate

GET /gru-fx/rates?pair=USD/GRU

Response:

{
  "success": true,
  "data": {
    "pair": "USD/GRU",
    "rate": "0.6667",
    "timestamp": "2024-01-15T10:30:00Z",
    "source": "DBIS_GRU",
    "bid": "0.6663",
    "ask": "0.6671",
    "spread": "0.0008"
  }
}

Get Rate History

GET /gru-fx/rates/history?pair=USD/GRU&startDate=2024-01-01&endDate=2024-01-15&interval=1d

Convert Currency

POST /gru-fx/convert

Request Body:

{
  "fromCurrency": "USD",
  "toCurrency": "EUR",
  "amount": "1000.00",
  "settlementAsset": "FIAT"
}

Error Responses

All errors follow this format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {}
  },
  "timestamp": "2024-01-15T10:30:00Z"
}

Error Codes

• VALIDATION_ERROR: Invalid request parameters
• NOT_FOUND: Resource not found
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions
• CONFLICT: Resource already exists
• UNPROCESSABLE_ENTITY: Business logic error (e.g., insufficient balance)
• INTERNAL_ERROR: Server error

Rate Limiting

• Default: 1000 requests per minute per FI
• Burst: Up to 100 requests in 10 seconds
• Headers:
  • X-RateLimit-Limit: Total allowed requests
  • X-RateLimit-Remaining: Remaining requests
  • X-RateLimit-Reset: Reset time (Unix timestamp)

Webhooks

Event Types

• TRANSFER_CREATED: New transfer created
• TRANSFER_SETTLED: Transfer settled
• TRANSFER_REJECTED: Transfer rejected
• ACCOUNT_UPDATED: Account updated
• BALANCE_CHANGED: Balance changed
• RECONCILIATION_COMPLETED: Reconciliation completed

Webhook Payload

{
  "eventId": "EVT-123",
  "eventType": "TRANSFER_SETTLED",
  "timestamp": "2024-01-15T10:30:00Z",
  "payload": {
    "transferId": "TRF-123",
    "status": "SETTLED",
    "settledAt": "2024-01-15T10:30:00Z"
  }
}

Signature Verification

Webhooks include a signature header:

X-DBIS-Signature: <signature>
X-DBIS-Timestamp: <timestamp>

Verify using HMAC-SHA256:

const message = `${timestamp}.${JSON.stringify(payload)}`;
const signature = crypto.createHmac('sha256', secret).update(message).digest('hex');

Idempotency

Use Idempotency-Key header for idempotent operations:

Idempotency-Key: unique-key-12345

Duplicate requests with the same key return the original response.

Pagination

All list endpoints support pagination:

GET /participants?page=1&pageSize=50

Response includes pagination metadata:

{
  "pagination": {
    "page": 1,
    "pageSize": 50,
    "total": 100,
    "totalPages": 2
  }
}

Examples

Complete Transfer Flow

1. Create Transfer:

curl -X POST https://api.example.com/api/v1/nostro-vostro/transfers \
  -H "Authorization: Bearer $TOKEN" \
  -H "Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{
    "fromAccountId": "ACC-123",
    "toAccountId": "ACC-456",
    "amount": "1000.00",
    "currency": "USD",
    "reference": "PAYMENT-001"
  }'

2. Check Transfer Status:

curl https://api.example.com/api/v1/nostro-vostro/transfers/TRF-123 \
  -H "Authorization: Bearer $TOKEN"

3. Get Account Balances:

curl https://api.example.com/api/v1/nostro-vostro/accounts/ACC-123/balances \
  -H "Authorization: Bearer $TOKEN"

SDKs

Official SDKs available:

• Java
• .NET
• Python
• Node.js

See SDK Documentation for details.

Support

• API Documentation: https://docs.example.com/nostro-vostro
• Support Email: api-support@example.com
• Emergency Hotline: +1-XXX-XXX-XXXX