Initial commit
This commit is contained in:
defiQUG
397
docs/nostro-vostro/api-reference.md
Normal file
397
docs/nostro-vostro/api-reference.md
Normal file
@@ -0,0 +1,397 @@
|
||||
# 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**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"name": "Central Bank of Example",
|
||||
"bic": "CBEXUS33",
|
||||
"lei": "5493000X9ZXSQ9B6Y815",
|
||||
"country": "US",
|
||||
"regulatoryTier": "SCB"
|
||||
}
|
||||
```
|
||||
|
||||
### Accounts
|
||||
|
||||
#### List Accounts
|
||||
```
|
||||
GET /accounts
|
||||
```
|
||||
|
||||
#### Create Account
|
||||
```
|
||||
POST /accounts
|
||||
```
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"participantId": "PART-123",
|
||||
"asOfDate": "2024-01-15"
|
||||
}
|
||||
```
|
||||
|
||||
#### Get Reconciliation
|
||||
```
|
||||
GET /reconciliations/{reportId}
|
||||
```
|
||||
|
||||
### Webhooks
|
||||
|
||||
#### Create Subscription
|
||||
```
|
||||
POST /webhooks/subscriptions
|
||||
```
|
||||
|
||||
**Request Body**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"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**:
|
||||
```json
|
||||
{
|
||||
"fromCurrency": "USD",
|
||||
"toCurrency": "EUR",
|
||||
"amount": "1000.00",
|
||||
"settlementAsset": "FIAT"
|
||||
}
|
||||
```
|
||||
|
||||
## Error Responses
|
||||
|
||||
All errors follow this format:
|
||||
|
||||
```json
|
||||
{
|
||||
"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
|
||||
|
||||
```json
|
||||
{
|
||||
"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:
|
||||
|
||||
```typescript
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"pagination": {
|
||||
"page": 1,
|
||||
"pageSize": 50,
|
||||
"total": 100,
|
||||
"totalPages": 2
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
### Complete Transfer Flow
|
||||
|
||||
1. **Create Transfer**:
|
||||
```bash
|
||||
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**:
|
||||
```bash
|
||||
curl https://api.example.com/api/v1/nostro-vostro/transfers/TRF-123 \
|
||||
-H "Authorization: Bearer $TOKEN"
|
||||
```
|
||||
|
||||
3. **Get Account Balances**:
|
||||
```bash
|
||||
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](./sdk-documentation.md) for details.
|
||||
|
||||
## Support
|
||||
|
||||
- **API Documentation**: https://docs.example.com/nostro-vostro
|
||||
- **Support Email**: api-support@example.com
|
||||
- **Emergency Hotline**: +1-XXX-XXX-XXXX
|
||||
|
||||
Reference in New Issue
Block a user