Every FinCard Virtual API request must carry a valid Bearer JWT token and a set of required context headers. Missing any of them returns HTTP 400 Missing required header(s).
Step 1 — Obtain a Session Token
Call the login endpoint once to obtain a short-lived JWT. Pass it as Authorization: Bearer <token> in all subsequent requests.
POST /api/auth/login
Content-Type: application/json
X-Tenant-ID: <your-tenant-id>
X-Forwarded-For: <client-ip>
X-Forwarded-From: <your-app-name>
platform: web
deviceId: <device-or-session-id>
{
"email": "user@your-domain.com",
"password": "your-password",
"tenantId": "your-tenant-id"
}
{
"accessToken": "eyJ0eXAiOiJKV1Qi...",
"tokenType": "Bearer",
"expiresIn": 3600
}
expiresIn is in seconds. Tokens are valid for 1 hour. Re-authenticate before expiry — there is no refresh token endpoint.
All 46 FinCard Virtual endpoints require the following headers:
| Header | Required | Example | Description |
|---|
Authorization | Yes | Bearer eyJ0eXAi... | JWT from login |
Content-Type | Yes | application/json | Always JSON |
X-Tenant-ID | Yes | tenant_acme | Your tenant identifier |
X-Forwarded-For | Yes | 203.0.113.42 | End-user IP address |
X-Forwarded-From | Yes | my-backend-service | Originating service name |
platform | Yes | web | ios | android | Client platform |
deviceId | Yes | device-abc-123 | Unique device or session ID |
User-Agent | No | MyApp/2.1 | Client user-agent (recommended) |
X-Forwarded-For, X-Forwarded-From, platform, and deviceId are validated server-side. A 400 Missing required header(s) error is returned if any are absent.
Complete Request Example
curl -X POST https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info \
-H "Authorization: Bearer eyJ0eXAiOiJKV1Qi..." \
-H "Content-Type: application/json" \
-H "X-Tenant-ID: tenant_acme" \
-H "X-Forwarded-For: 203.0.113.42" \
-H "X-Forwarded-From: my-backend" \
-H "platform: web" \
-H "deviceId: device-abc-123" \
-d '{ "cardNo": "FC-XXXX-XXXX" }'
Response Envelope
Every response — success or error — is wrapped in the same envelope:
{
"success": true,
"code": 200,
"msg": "Success",
"data": { ... }
}
| Field | Type | Description |
|---|
success | Boolean | true = operation succeeded |
code | Integer | 200 = OK, -1 = business error, 401 = unauthorized, 500 = server error |
msg | String | Human-readable status message |
data | Object | Array | Response payload (varies per endpoint) |
Even HTTP 200 responses can have "success": false for business-level errors (e.g. card not found, insufficient balance). Always check success and code.
Error Reference
| HTTP | code | Cause | Action |
|---|
| 400 | 500 | Missing required header | Add all required headers |
| 401 | 401 | Missing or expired token | Re-authenticate via /api/auth/login |
| 401 | 401 | Empty authorization token | Include Authorization: Bearer <token> |
| 200 | -1 | Business error (e.g. card not found) | Check msg for details |
| 200 | 200 | Success | Process data payload |
SDK / Script Example (PowerShell)
# 1. Login
$loginBody = @{
email = "user@domain.com"
password = "your-password"
tenantId = "your-tenant-id"
} | ConvertTo-Json -Compress
$loginResp = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/auth/login" `
-Method Post `
-Headers @{
"Content-Type" = "application/json"
"X-Tenant-ID" = "your-tenant-id"
"X-Forwarded-For" = "127.0.0.1"
"X-Forwarded-From" = "my-script"
"platform" = "web"
"deviceId" = "script-device-001"
} `
-Body $loginBody
# 2. Use token in all subsequent calls
$headers = @{
"Authorization" = "Bearer $($loginResp.accessToken)"
"Content-Type" = "application/json"
"X-Tenant-ID" = "your-tenant-id"
"X-Forwarded-For" = "127.0.0.1"
"X-Forwarded-From" = "my-script"
"platform" = "web"
"deviceId" = "script-device-001"
}
# 3. Call any endpoint
$cardInfo = Invoke-RestMethod -Uri "https://sandbox.finhub.cloud/api/v2.1/fincard/virtual/card/info" `
-Method Post -Headers $headers -Body '{"cardNo":"FC-XXXX-XXXX"}'
