{"openapi":"3.0.3","info":{"title":"Wallet","version":"1.0","description":"Wallet service APIs"},"paths":{"/{companyId}/wallets":{"x-atlas-api":true,"parameters":[{"name":"companyId","in":"path","description":"id of the company","required":true,"schema":{"type":"string"}}],"get":{"operationId":"get_company_wallets","x-permission-config":["Client:EWallets:read","Admin:Wallets:read","Client:At Verto Rate:read","Client:Make Payment To Account:read","Client:Add Funds:read","Client:Add Wallets:read","Client:Make Payment To Another Business:read"],"summary":"Fetch all wallets for a company","tags":["wallet"],"parameters":[{"$ref":"#/components/parameters/limitParam"},{"$ref":"#/components/parameters/skipParam"},{"$ref":"#/components/parameters/currencyParam"},{"name":"currencyId","in":"query","description":"currency id","schema":{"type":"string"}},{"name":"searchTerm","in":"query","description":"search by wallet label","schema":{"type":"string"}},{"name":"isDefault","in":"query","schema":{"type":"boolean"}},{"name":"include","in":"query","description":"comma separated list of what should be included in response","schema":{"type":"string"}},{"name":"isArchived","in":"query","schema":{"type":"boolean"}},{"name":"walletIds","in":"query","description":"comma separated wallet id's","schema":{"type":"string"}},{"name":"type","in":"query","description":"wallet type","schema":{"$ref":"#/components/schemas/WalletType"}},{"name":"fetchPreference","in":"query","description":"Preference for fetching wallets","schema":{"type":"string","enum":["fxAndDefault","fxAndAll","fxOrAll","fxOrDefault","billingOrDefault"]}},{"name":"isBillingWallet","in":"query","description":"filter by billing wallet status","schema":{"type":"boolean"}}],"responses":{"200":{"description":"fetch wallets for a company","content":{"application/json":{"schema":{"type":"object","properties":{"totalCount":{"type":"integer","format":"int32"},"items":{"type":"array","items":{"$ref":"#/components/schemas/Wallet"}}}}}}},"default":{"$ref":"#/components/responses/ErrorResponse"}}},"post":{"operationId":"create_wallet","x-atlas-api":true,"x-permission-config":["Client:EWallets:write","Admin:Wallets:write","Client:Add Wallets:write","Client:Add Funds:write"],"summary":"Create a new wallet","tags":["wallet"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewWalletRq"}}}},"responses":{"201":{"description":"New wallet creation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Wallet"}}}}}}},"/wallets/{walletId}/fetch-statements":{"x-atlas-api":true,"parameters":[{"name":"walletId","in":"path","description":"Specifies the unique identifier assigned to a wallet.\nGet the walletId from the `items[].id` field returned by the Get all Wallets API.","required":true,"schema":{"type":"string"}}],"get":{"summary":"Fetch wallet statements","x-atlas-api":true,"tags":["wallets"],"operationId":"fetch_wallet_statements","x-permission-config":["Client:EWallets:read","Admin:Wallets:read","Client:Add Wallets:read","Client:Add Funds:read"],"parameters":[{"name":"limit","in":"query","description":"max records to return","required":true,"schema":{"type":"integer","format":"int32","maximum":100}},{"$ref":"#/components/parameters/skipParam"},{"name":"since","in":"query","description":"Filter transactions from this date (ISO 8601 date-time format, required)","required":true,"schema":{"type":"string","format":"date-time","example":"2024-01-01T00:00:00.000Z"}},{"name":"till","in":"query","description":"Filter transactions until this date (ISO 8601 date-time format, required)","required":true,"schema":{"type":"string","format":"date-time","example":"2024-12-31T23:59:59.999Z"}},{"name":"searchTerm","in":"query","description":"Search term to filter transactions by description or reference (max 50 characters)","required":false,"schema":{"type":"string","maxLength":50}}],"responses":{"200":{"description":"Successfully retrieved wallet statements","content":{"application/json":{"schema":{"type":"object","properties":{"totalCount":{"type":"integer","format":"int32","description":"Total number of transactions matching the criteria","example":45},"items":{"type":"array","description":"Array of ledger entries (transactions)","items":{"$ref":"#/components/schemas/LedgerEntry"}}}},"example":{"totalCount":2,"items":[{"amount":500000,"runningBalance":504392.49,"currency":"USD","reference":"IN-15012024-009","description":"Incoming payment","timestamp":"2024-01-15T13:41:54.079Z"},{"amount":-1500,"runningBalance":4392.49,"currency":"USD","reference":"TO-15012024-006","description":"External bank transfer","timestamp":"2024-01-15T09:50:17.262Z"}]}}}},"400":{"$ref":"#/components/responses/ClientErrorResponse"},"401":{"$ref":"#/components/responses/ClientErrorResponse"},"403":{"$ref":"#/components/responses/ClientErrorResponse"},"404":{"$ref":"#/components/responses/ClientErrorResponse"},"500":{"$ref":"#/components/responses/ClientErrorResponse"},"default":{"$ref":"#/components/responses/ClientErrorResponse"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Bearer token returned by the Login endpoint. Send it as:\n> Authorization: Bearer <token>\n"}},"parameters":{"limitParam":{"name":"limit","in":"query","description":"max records to return","required":true,"schema":{"type":"integer","format":"int32","maximum":300}},"skipParam":{"name":"skip","in":"query","description":"number of items to skip","required":true,"schema":{"type":"integer","format":"int32"}},"currencyParam":{"name":"currency","in":"query","example":"USD","schema":{"$ref":"#/components/schemas/Currency"}}},"schemas":{"WalletType":{"type":"string","enum":["standard","fx_balance"]},"Wallet":{"type":"object","properties":{"id":{"type":"number","example":1},"totalBalance":{"type":"number","example":100},"availableBalance":{"type":"number","example":90},"currency":{"$ref":"#/components/schemas/Currency"},"type":{"$ref":"#/components/schemas/WalletType"},"companyId":{"type":"number","example":2},"customReferenceLabel":{"type":"string","example":"US_SEGREGATED"},"isDefault":{"type":"boolean"},"isDisabled":{"type":"boolean","example":false},"isBillingWallet":{"type":"boolean","example":false,"description":"Indicates if this wallet is used for billing purposes"},"fundingType":{"$ref":"#/components/schemas/FundingType"},"splitPaymentMessage":{"type":"string","example":"This wallet supports split payments","description":"Message indicating if split payments are enabled for this wallet"},"isSplitPaymentEnabled":{"type":"boolean","example":true,"description":"Indicates if split payments are enabled for this wallet"},"splitPaymentLimit":{"type":"number","example":1000,"description":"Maximum amount allowed for split payments in this wallet"}}},"NewWalletRq":{"type":"object","required":["currency","type"],"properties":{"currency":{"$ref":"#/components/schemas/Currency"},"type":{"$ref":"#/components/schemas/WalletType"},"customReferenceLabel":{"type":"string","maxLength":75}}},"LedgerEntry":{"type":"object","properties":{"runningBalance":{"type":"number","example":900},"amount":{"type":"number","example":100},"currency":{"$ref":"#/components/schemas/Currency"},"reference":{"type":"string","example":"TO-01012023-001"},"description":{"type":"string","example":"Payment to Elon Musk"},"timestamp":{"type":"string"}}},"Currency":{"type":"string","minLength":3,"maxLength":3,"enum":["USD","AED","AFN","ALL","AMD","ANG","AOA","ARS","AUD","AWG","AZN","BAM","BBD","BDT","BGN","BHD","BIF","BMD","BND","BOB","BRL","BSD","BTN","BWP","BYN","BZD","CAD","CDF","CHF","CLP","CNY","COP","CRC","CUC","CUP","CVE","CZK","DJF","DKK","DOP","DZD","EGP","ERN","ETB","EUR","FJD","FKP","GBP","GEL","GGP","GHS","GIP","GMD","GNF","GTQ","GYD","HKD","HNL","HRK","HTG","HUF","IDR","ILS","IMP","INR","IQD","IRR","ISK","JEP","JMD","JOD","JPY","KES","KGS","KHR","KMF","KPW","KRW","KWD","KYD","KZT","LAK","LBP","LKR","LRD","LSL","LYD","MAD","MDL","MGA","MKD","MMK","MNT","MOP","MRU","MUR","MVR","MWK","MXN","MYR","MZN","NAD","NGN","NIO","NOK","NPR","NZD","OMR","PAB","PEN","PGK","PHP","PKR","PLN","PYG","QAR","RON","RSD","RUB","RWF","SAR","SBD","SCR","SDG","SEK","SGD","SHP","SLL","SOS","SPL","SRD","STN","SVC","SYP","SZL","THB","TJS","TMT","TND","TOP","TRY","TTD","TVD","TWD","TZS","UAH","UGX","UYU","UZS","VEF","VND","VUV","WST","XAF","XCD","XDR","XOF","XPF","YER","ZAR","ZMW","ZWD"]},"FundingType":{"type":"string","enum":["account","smartWallet","pooled","null"]}},"responses":{"ErrorResponse":{"description":"Not authorized / Bad input / Server error","content":{"application/json":{"schema":{"required":["message","code"],"type":"object","properties":{"message":{"description":"The error message indicating what the issue is","type":"string"},"code":{"description":"The error code","type":"integer"}},"example":{"code":400,"message":"wrong input"}}}}},"ClientErrorResponse":{"description":"Client-facing API error response with error type and message","content":{"application/json":{"schema":{"required":["error","message"],"type":"object","properties":{"error":{"description":"The error type (e.g., Bad Request, Forbidden, Unauthorized)","type":"string"},"message":{"description":"Detailed error message describing what went wrong","type":"string"}},"example":{"Bad Request":{"value":{"error":"Bad Request","message":"Invalid limit: must be between 1 and 100"}},"Unauthorized":{"value":{"error":"Unauthorized","message":"Invalid or missing authentication token"}},"Forbidden":{"value":{"error":"Forbidden","message":"You are not authorized to access this wallet"}},"Not Found":{"value":{"error":"Not Found","message":"Wallet not found"}}}}}}}}},"security":[{"bearerAuth":[]}],"servers":[{"url":"https://api-wallet-beta.vertofx.com"},{"url":"https://api-wallet-sandbox.vertofx.com"}]}